# script タグ Docs Embed をウェブサイトやアプリに追加する最も簡単な方法は、HTML に含める単独のスクリプトを使うことです。各 GitBook ドキュメントサイトには、ウィジェットを自動的に読み込み、ドキュメントに接続する、すぐに使える埋め込みスクリプトが用意されています。このページでは、その方法を説明します。 SDK、ビルド手順、フレームワーク統合は不要です。スクリプトを含めるだけで、ウィジェットがページに表示されます。 ## はじめに {% stepper %} {% step %} #### 埋め込みスクリプトのURLをコピーする GitBook アプリでドキュメントサイトに移動し、 **設定** タブを開いてから **AI & MCP** に進み、埋め込みスクリプトのURLをコピーします。手動で作成することもできます: ``` https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js ``` を `YOUR_DOCS_DOMAIN` 実際のドキュメントサイトのドメインに置き換えてください。 {% endstep %} {% step %} #### スクリプトをHTMLに追加する次のタグをページのHTMLに追加してください。 `` の中、または `の直前に配置します。`. ```html ``` {% endstep %} {% step %} #### ドキュメントに認証が必要な場合ドキュメントが [認証の背後にある](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/saitoakusesu/authenticated-access)場合、スクリプトには署名済みJWTトークンを含める必要があります。クエリパラメータとして追加します: ```html ``` {% endstep %} {% step %} #### 確認するページを再読み込みしてください。ウィジェットは右下に表示されるはずです。 {% endstep %} {% endstepper %} ### 埋め込みを任意で設定する表示する前にウィジェットをカスタマイズできます。スクリプトを読み込んだ後、 `configure` を呼び出す前に `window.GitBook('show')`. ```html ``` この方法では、次の項目をカスタマイズできます: * ボタンのラベルとアイコン * ウィジェット内に表示されるタブ * カスタムアクションボタン * 挨拶のタイトルとサブタイトル * UIに表示されるアシスタント名 * アシスタント内の閉じるボタン * ユーザーに表示される提案プロンプト。検索はデフォルトで有効です。 `tabs`、保持したいタブをすべて列挙してください。 ### 配色テーマを設定するデフォルトでは、埋め込みは iframe の CSS `color-scheme`に従います。これにより、アプリのテーマやブラウザの設定を自動的に継承できます。モードを強制したい場合は、埋め込みを初期化して `colorScheme` を `frameOptions`: ```html ``` 次のようなフレームレベルのオプションが必要な場合は、このパターンを使用します: `colorScheme` または `visitor`. ### ウィジェットの表示/非表示を制御する API を通じて、実行時に表示と状態を制御できます。 ```html ``` ウィジェットを独自のUIトリガーに接続したい場合に便利です。 ### プログラムで移動および操作するコードからウィジェットを操作して、移動、タブ切り替え、メッセージ送信ができます。 ```html ``` この機能の一般的な用途には次のようなものがあります: * アプリからドキュメントページへのディープリンクを追加する * 質問をあらかじめ入力しておく * フロー間で会話をリセットする ### 埋め込みスクリプトを動的に読み込むウィジェットを条件付きで読み込みたい場合や、実行時に認証トークンを付与する必要がある場合は、スクリプトをプログラムで挿入します。 ```html ``` ウィジェットをユーザー操作や機能フラグの後にのみ読み込む場合は、このパターンを使用します ## API リファレンス ### 初期化 * `GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...}, colorScheme?: 'light' | 'dark' })` - サイトURLと任意のフレームオプションでウィジェットを初期化する ### ウィジェットの制御 * `GitBook('show')` - ウィジェットボタンを表示する * `GitBook('hide')` - ウィジェットボタンを非表示にする * `GitBook('open')` - ウィジェットウィンドウを開く * `GitBook('close')` - ウィジェットウィンドウを閉じる * `GitBook('toggle')` - ウィジェットウィンドウを切り替える ### ナビゲーション * `GitBook('navigateToPage', path: string)` - ドキュメントタブの特定ページへ移動する * `GitBook('navigateToAssistant')` - アシスタンスタブに移動する ### チャット * `GitBook('postUserMessage', message: string)` - チャットにメッセージを送信する * `GitBook('clearChat')` - チャット履歴をクリアする ### 設定 * `GitBook('configure', settings: {...})` - ウィジェット設定を構成する（下の設定セクションを参照） * `GitBook('unload')` - ウィジェットをページから完全に削除する ## 設定オプション ### `GitBook('configure')` ほとんどの設定オプションは `GitBook('configure', {...})`: #### `tabs` で利用できます。表示するタブを上書きします。検索はデフォルトで有効です。 `tabs`を設定すると、埋め込みにはリストしたタブのみが表示されます。 * **入力します**: `('assistant' | 'search' | 'docs')[]` * **オプション**: * `['assistant', 'search', 'docs']` - すべてのタブを表示する * `['search', 'docs']` - 検索とドキュメントのみを表示する * `['docs']` - ドキュメントタブのみを表示する #### `を設定すると` タブと並んでサイドバーに表示されるカスタムアクションボタンです。各アクションボタンはクリック時にコールバックを実行します。 **注**: 以前はこれは `buttons`という名前でした。 `を設定すると` の代わりに行うことをおすすめします。 * **入力します**: `Array<{ icon: string, label: string, onClick: () => void }>` * **プロパティ**: * `icon`: `string` - アイコン名。任意の [FontAwesome アイコン](https://fontawesome.com/search) がサポートされています * `ラベル`: `string` - ボタンラベルのテキスト * `onClick`: `() => void | Promise` - クリック時のコールバック関数 #### `greeting` Assistant タブに表示されるウェルカムメッセージ。 * **入力します**: `{ title: string, subtitle: string }` #### `assistantName` UI に表示されるアシスタント名を上書きします。 * **入力します**: `string` * **最大長**: `32` 文字 * **例**: ```javascript window.GitBook('configure', { assistantName: 'Support Copilot' }); ``` #### `closeButton` Assistant 内に閉じるボタンを表示します。 * **入力します**: `boolean` * **例**: ```javascript window.GitBook('configure', { closeButton: true }); ``` #### `suggestions` Assistant のウェルカム画面に表示されるおすすめの質問。 * **入力します**: `string[]` #### `trademark` 埋め込み UI で GitBook の商標を表示または非表示にします。これには Docs Embed のフッターと Assistant のブランド表示が含まれます。 * **入力します**: `boolean` * **デフォルト**: `true` * **例**: ```javascript window.GitBook('configure', { trademark: false }); ``` #### `tools` Assistant を拡張するカスタム AI ツール。詳細は [カスタムツールの作成](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/docs-site/embedding/configuration/creating-custom-tools) を参照してください。 * **入力します**: `Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>` #### `ボタン` 埋め込みを起動するウィジェットボタンを設定します（単独スクリプトのみ）。これにより、ページ右下に表示されるボタンのラベルとアイコンをカスタマイズできます。 * **入力します**: `{ label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }` * **プロパティ**: * `ラベル`: `string` - ボタンに表示されるテキスト * `icon`: `'assistant' | 'sparkle' | 'help' | 'book'` - ボタンに表示されるアイコン * `assistant` - アシスタントアイコン * `sparkle` - スパークルアイコン * `help` - ヘルプ/質問アイコン * `book` - ブックアイコン **例:** ```javascript window.GitBook('configure', { button: { label: 'Ask', icon: 'assistant' } }); ``` {% hint style="info" %} **注：** このオプションは、単独の script タグ実装を使用している場合にのみ利用できます。React または Node.js の実装では、埋め込みを起動するための独自ボタンを作成する必要があります。 {% endhint %} ### `frameOptions` 一部のオプションは、設定ではなくフレーム上で設定されます。呼び出し時にそれらを渡してください `frameOptions` when calling `GitBook('init', options, frameOptions)`. #### `colorScheme` に渡されます。埋め込みの配色を上書きします。省略した場合、埋め込みは iframe の CSS `color-scheme`に従い、親ページまたはブラウザの設定を継承できます。 * **入力します**: `'light' | 'dark'` * **例**: ```javascript window.GitBook( 'init', { siteURL: 'https://docs.company.com' }, { colorScheme: 'dark' } ); ``` #### `visitor` (認証済みアクセス) 次のもので初期化する際に渡す `GitBook('init', options, frameOptions)`。用途は [Adaptive Content](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/saitoakusesu/adaptive-content) 、 [認証済みアクセス](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/saitoakusesu/authenticated-access). * **入力します**: `{ token?: string, unsignedClaims?: Record }` * **プロパティ**: * `token`: `string` (任意) - 署名済みJWTトークン * `unsignedClaims`: `Record` (任意) - 動的式用の未署名クレーム ## よくある落とし穴 * **スクリプトURLが正しくありません** – 例ではなく、実際のドキュメントURLを使用していることを確認してください `docs.company.com`. * **スクリプトの読み込み前に GitBook を呼び出している** – API 呼び出しを `script.onload` でラップするか、スクリプトタグの後に配置してください。 * **認証済みドキュメントにアクセスできない** – ドキュメントにサインインが必要な場合は、 `visitor.token` を初期化時に指定する必要があります。参照: [認証済みドキュメントでの使用](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/docs-site/embedding/using-with-authenticated-docs). * **CORS または CSP エラー** – サイトの Content Security Policy で、GitBook ドメインからのスクリプトと iframe の読み込みが許可されていることを確認してください。 * **ウィジェットが表示されない** – ページ上の他の要素との z-index の競合を確認してください。ウィジェットはデフォルトで高い z-index を使用します。 * **初期化し忘れている** – 必ず `GitBook('init', { siteURL: '...' })` を他のメソッドを使用する前に呼び出してください。