Node.js/NPM

アプリケーションレベルで完全に制御するために NPM パッケージを使って Docs Embed を統合する

より細かく制御し、アプリケーションレベルで操作したい場合は、npmからGitBookのembedパッケージをインストールできます。この方法はサーバーサイドレンダリング、ビルド時の統合、またはカスタムiframe管理に最適です。

手順

1

パッケージをインストールする

追加する @gitbook/embed をプロジェクトに：

npm install @gitbook/embed

完全なAPI参照とソースコードは、次を参照してください @gitbook/embed GitHubのパッケージ.

2

パッケージをインポートする

アプリケーションコード内で、次をインポートします createGitBook 関数：

import { createGitBook } from "@gitbook/embed";

またはCommonJSを使用する場合：

const { createGitBook } = require("@gitbook/embed");

3

GitBookを初期化する

ドキュメントサイトのURLでGitBookインスタンスを作成します：

const gitbook = createGitBook({
  siteURL: "https://docs.company.com",
});

4

iframeを作成する

iframe要素を生成し、そのソースを埋め込み用URLに設定します：

const iframe = document.createElement("iframe");
iframe.src = gitbook.getFrameURL({
  visitor: {
    token: 'your-jwt-token', // 任意：Adaptive Contentや認証付きアクセス用
    unsignedClaims: { // 任意：動的式のためのカスタムクレーム
      userId: '123',
      plan: 'premium'
    }
  }
});
iframe.id = "gitbook-embed-container";
iframe.style.border = "none";
iframe.style.width = "100%";
iframe.style.height = "600px";

5

フレームを取り付ける

GitBookフレームインスタンスを作成し、ページにマウントします：

const frame = gitbook.createFrame(iframe);
document.getElementById("gitbook-embed-container").appendChild(iframe);

6

埋め込みをプログラムで制御する

フレームインスタンスを使って埋め込みとやり取りします：

// ドキュメントタブの特定ページへ移動する
frame.navigateToPage("/getting-started");

// アシスタントタブに切り替える
frame.navigateToAssistant();

// チャットにメッセージを送る
frame.postUserMessage("How do I get started?");

// チャット履歴をクリアする
frame.clearChat();

7

埋め込みを設定する

カスタマイズオプションで埋め込みを設定します：

frame.configure({
  trademark: false,
  tabs: ['assistant', 'docs'],
  actions: [
    {
      icon: 'circle-question',
      label: 'Contact Support',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
  suggestions: ['What is GitBook?', 'How do I get started?'],
  tools: [/* ... */]
});

8

イベントをリッスンする

埋め込みイベントに応答するためにイベントリスナーを登録します：

frame.on('close', () => {
  console.log('Frame closed');
});

// 完了したら購読を解除する
const unsubscribe = frame.on('navigate', (data) => {
  console.log('Navigated to:', data.path);
});

APIリファレンス

クライアントファクトリ

• createGitBook(options: { siteURL: string }) → GitBookClient

• client.getFrameURL(options?: { visitor?: {...} }) → string - 認証付きアクセスを含めたオプションでiframeのURLを取得する

• client.createFrame(iframe: HTMLIFrameElement) → GitBookFrameClient - iframeと通信するためのフレームクライアントを作成する

フレームクライアントのメソッド

• frame.navigateToPage(path: string) → void - ドキュメントタブの特定ページへ移動する

• frame.navigateToAssistant() → void - アシスタントタブに切り替える

• frame.postUserMessage(message: string) → void - チャットにメッセージを投稿する

• frame.clearChat() → void - チャット履歴をクリアする

• frame.configure(settings: Partial<GitBookEmbeddableConfiguration>) → void - 埋め込みを設定する

• frame.on(event: string, listener: Function) → () => void - イベントリスナーを登録する（解除関数を返します）

設定オプション

設定オプションは次で利用可能です frame.configure({...}):

tabs

表示するタブを上書きします。デフォルトはサイトの設定です。

• 型: ('assistant' | 'docs')[]

actions

タブの横にサイドバー内でレンダリングされるカスタムアクションボタン。各アクションボタンはクリック時にコールバックをトリガーします。

注意: 以前は次の名前でした buttons。代わりに actions を使用してください。

• 型: Array<{ icon: string, label: string, onClick: () => void }>

greeting

アシスタントタブに表示される歓迎メッセージ。

• 型: { title: string, subtitle: string }

suggestions

アシスタントのウェルカム画面に表示される推奨質問。

• 型: string[]

trademark

Docs Embedのフッターやアシスタントのブランディングを含む、埋め込みUI内のGitBookの商標を表示または非表示にします。

• 型: boolean

• デフォルト: true

tools

アシスタントを拡張するカスタムAIツール。詳細は次を参照してください。 カスタムツールの作成 をご覧ください。

• 型: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

visitor （認証付きアクセス）

次に渡します getFrameURL({ visitor: {...} })。使用されるのは Adaptive Content と Authenticated Access.

• 型: { token?: string, unsignedClaims?: Record<string, unknown> }

よくある落とし穴

• パッケージをインストールし忘れること – インポートする前に npm install @gitbook/embed を実行してください。

• siteURLがない – オプションの siteURL は必須で、公開されているドキュメントサイトと一致する必要があります。

• iFrameがレンダリングされない – iframeが表示されるために、親コンテナに十分な幅/高さがあることを確認してください。

• 初期化前にフレームメソッドが呼ばれる – フレームメソッドを呼び出す前に、 createFrame() が完了するのを待ってください。

• イベントの購読を解除していない – メモリリークを防ぐために、 frame.on() が返す解除関数を呼び出すことを忘れないでください。

• 古いAPIメソッドを使用している – 次のようなメソッドは open(), close(), toggle()、および destroy() はNPMパッケージでは利用できません。代わりにフレームクライアントのメソッドを使用してください。