# scriptタグ GitBook Assistant をウェブサイトやアプリに埋め込むための最も簡単な統合方法は、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-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/authenticated-access)場合、スクリプトには署名付き JWT トークンを含める必要があります。クエリパラメータとして追加します: ```html ``` {% endstep %} {% step %} ### 確認するページを再読み込みします。ウィジェットは右下隅に表示されるはずです。 {% endstep %} {% endstepper %} ### 必要に応じて埋め込みを設定する表示する前にウィジェットをカスタマイズできます。スクリプトを読み込んだ後、次を呼び出します `configure` そして次を呼び出す前に `window.GitBook('show')`. ```html ``` この方法を使うと、以下をカスタマイズできます: * ボタンのラベルとアイコン * ウィジェット内で表示されるタブ * カスタムアクションボタン * 挨拶のタイトルとサブタイトル * ユーザーに表示される提案プロンプト。 ### ウィジェットの表示を制御する API を通じて、実行時に表示や状態を制御できます。 ```html ``` これは、ウィジェットを独自の UI トリガーに接続したい場合に便利です。 ### プログラムで移動して操作するコードからウィジェットを操作して、移動したり、タブを切り替えたり、メッセージを送信したりできます。 ```html ``` この機能の典型的な用途には次のものがあります: * アプリからドキュメントページへのディープリンクを追加する * 質問を事前入力する * フロー間で会話をリセットする ### 埋め込みスクリプトを動的に読み込むウィジェットを条件付きでのみ読み込みたい場合や、実行時に認証トークンを付与する必要がある場合は、スクリプトをプログラムで挿入します。 ```html ``` ウィジェットをユーザー操作後や機能フラグ有効化後にのみ読み込む場合は、このパターンを使用してください ## API リファレンス ### 初期化 * `GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} })` - サイト 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', {...})`: ### `tabs` 表示するタブを上書きします。既定値はサイトの設定です。 * **入力**: `('assistant' | 'docs')[]` * **オプション**: * `['assistant', 'docs']` - 両方のタブを表示する * `['assistant']` - アシスタントタブのみを表示する * `['docs']` - ドキュメントタブのみを表示する ### `actions` タブの横にあるサイドバーに表示されるカスタムアクションボタンです。各アクションボタンはクリック時にコールバックをトリガーします。 **注意**：以前はこれを `buttons`と呼んでいました。 `actions` の使用を検討してください。 * **入力**: `Array<{ icon: string, label: string, onClick: () => void }>` * **プロパティ**: * `icon`: `string` - アイコン名。任意の [FontAwesome アイコン](https://fontawesome.com/search) がサポートされています * `label`: `string` - ボタンラベルのテキスト * `onClick`: `() => void | Promise` - クリック時のコールバック関数 ### `greeting` アシスタンタブに表示されるウェルカムメッセージ。 * **入力**: `{ title: string, subtitle: string }` ### `suggestions` アシスタントのウェルカム画面に表示される提案質問。 * **入力**: `string[]` ### `trademark` 埋め込み UI で GitBook の商標を表示または非表示にします — Docs Embed のフッターと Assistant のブランド表示を含みます。 * **入力**: `boolean` * **デフォルト**: `true` * **例**: ```javascript window.GitBook('configure', { trademark: false }); ``` ### `tools` アシスタントを拡張するためのカスタム AI ツールです。詳細は [カスタムツールの作成](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/embedding/configuration/creating-custom-tools) をご覧ください。 * **入力**: `Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>` ### `ボタン` 埋め込みを起動するウィジェットボタンを構成します（スタンドアロンスクリプトのみ）。これにより、ページの右下隅に表示されるボタンのラベルとアイコンをカスタマイズできます。 * **入力**: `{ label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }` * **プロパティ**: * `label`: `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 %} ### `visitor` （認証済みアクセス）次を使って初期化する際に渡します `GitBook('init', options, frameOptions)`。用途は [Adaptive Content](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/adaptive-content) 、 [認証済みアクセス](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/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-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/embedding/using-with-authenticated-docs). * **CORS または CSP のエラー** – サイトの Content Security Policy で、GitBook ドメインからのスクリプトと iframe の読み込みが許可されていることを確認してください。 * **ウィジェットが表示されない** – ページ上の他の要素との z-index の競合を確認してください。ウィジェットはデフォルトで高い z-index を使用します。 * **初期化を忘れている** – 次を呼び出していることを確認してください `GitBook('init', { siteURL: '...' })` 他のメソッドを使用する前に。