Node.js/NPM

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

より細かな制御が必要で、アプリケーションレベルで作業したい場合は、npm から GitBook の埋め込みパッケージをインストールできます。このアプローチは、サーバーサイドレンダリング、ビルド時の統合、またはカスタム iframe 管理に最適です。

手順

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

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

npm install @gitbook/embed

完全な API リファレンスとソースコードについては、 @gitbook/embed の GitHub 上のパッケージを参照してください.

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

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

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

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

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

GitBook を初期化する

ドキュメントサイトの URL を使って GitBook インスタンスを作成します:

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

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";

フレームを追加する

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

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

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

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

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

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

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

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

埋め込みを設定する

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

frame.configure({
  trademark: false,
  tabs: ['assistant', 'search', 'docs'],
  actions: [
    {
      icon: 'circle-question',
      label: 'サポートに問い合わせる',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: 'ようこそ！', subtitle: 'どのようにお手伝いできますか？' },
  assistantName: 'Support Copilot',
  closeButton: true,
  suggestions: ['GitBook とは何ですか？', 'どうやって始めればよいですか？'],
  tools: [/* ... */]
});

イベントを監視する

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

frame.on('close', () => {
  console.log('フレームが閉じられました');
});

// 完了したら購読解除
const unsubscribe = frame.on('navigate', (data) => {
  console.log('移動先:', data.path);
});

API リファレンス

クライアントファクトリー

createGitBook(options: { siteURL: string }) → GitBookClient
client.getFrameURL(options?: { visitor?: {...}, colorScheme?: 'light' | 'dark' }) → 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 - イベントリスナーを登録する（unsubscribe 関数を返します）

設定オプション

ほとんどのカスタマイズオプションは frame.configure({...}).

`tabs`

で利用できます。表示するタブを上書きします。

検索はデフォルトで有効です。 tabsを設定すると、埋め込みにはリストしたタブのみが表示されます。

入力します: ('assistant' | 'search' | 'docs')[]

`を設定すると`

タブと並んでサイドバーに表示されるカスタムアクションボタンです。各アクションボタンはクリック時にコールバックを実行します。

注: 以前はこれは buttonsという名前でした。 を設定すると の代わりに行うことをおすすめします。

入力します: Array<{ icon: string, label: string, onClick: () => void }>

`greeting`

Assistant タブに表示されるウェルカムメッセージ。

入力します: { title: string, subtitle: string }

`assistantName`

UI に表示されるアシスタント名を上書きします。

入力します: string
最大長: 32 文字

`closeButton`

Assistant 内に閉じるボタンを表示します。

入力します: boolean

`suggestions`

Assistant のウェルカム画面に表示されるおすすめの質問。

入力します: string[]

`trademark`

埋め込み UI で GitBook の商標を表示または非表示にします。これには Docs Embed のフッターと Assistant のブランド表示が含まれます。

入力します: boolean
デフォルト: true

`tools`

Assistant を拡張するカスタム AI ツール。詳細はカスタムツールの作成を参照してください。

入力します: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

フレーム URL のオプション

一部のオプションは getFrameURL({...}).

`colorScheme`

に渡されます。埋め込みの配色を上書きします。

省略した場合、埋め込みは iframe の CSS color-schemeに従い、親ページまたはブラウザの設定を継承できます。

入力します: 'light' | 'dark'

`visitor` (認証済みアクセス)

以下に渡します getFrameURL({ visitor: {...} })。用途は Adaptive Content 、認証済みアクセス.

入力します: { token?: string, unsignedClaims?: Record<string, unknown> }

よくある落とし穴

パッケージのインストールを忘れる – 次を実行してから npm install @gitbook/embed インポートしてください。
siteURL がない – siteURL オプションは必須で、公開済みのドキュメントサイトと一致している必要があります。
iFrame がレンダリングされない – 親コンテナに iframe を表示するのに十分な幅/高さがあることを確認してください。
初期化前にフレームメソッドを呼び出す – まで待ってから createFrame() が完了してからフレームメソッドを呼び出してください。
イベントの購読解除をしない – frame.on() から返される unsubscribe 関数を必ず呼び出して、メモリリークを防いでください。
古い API メソッドを使う – 以下のようなメソッド open(), close(), toggle()、および destroy() は NPM パッケージでは利用できません。代わりに frame client のメソッドを使用してください。

最終更新 1 か月前

役に立ちましたか？

おやすみ

hashtag手順

hashtagAPI リファレンス

hashtagクライアントファクトリー

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

hashtag設定オプション

hashtagtabs

hashtagを設定すると

hashtaggreeting

hashtagassistantName

hashtagcloseButton

hashtagsuggestions

hashtagtrademark

hashtagtools

hashtagフレーム URL のオプション

hashtagcolorScheme

hashtagvisitor (認証済みアクセス)

hashtagよくある落とし穴

手順