APIリファレンス

Docs Embedをプログラムで扱う際に利用できるメソッドについて、詳しく学びます

Docs Embed は、統合方法に応じて異なる API を提供します。このリファレンスでは、すべての統合方法で利用可能なメソッドを網羅しています。

メソッド比較

方法	スタンドアロンスクリプト	NPM パッケージ	React コンポーネント
初期化	GitBook('init', options, frameOptions)	createGitBook(options)	<GitBookProvider siteURL="...">
配色スキームの上書き	GitBook('init', options, { colorScheme })	client.getFrameURL({ colorScheme })	<GitBookFrame colorScheme="..." />
フレーム URL を取得	❌（内部で処理されます）	client.getFrameURL(options)	useGitBook().getFrameURL(options)
フレームクライアントを作成	❌（内部で処理されます）	client.createFrame(iframe)	useGitBook().createFrame(iframe)
ウィジェットの表示/非表示	GitBook('show') / GitBook('hide')	❌	❌
ウィンドウを開く/閉じる	GitBook('open') / GitBook('close') / GitBook('toggle')	❌	❌
ページへ移動	GitBook('navigateToPage', path)	frame.navigateToPage(path)	フレームクライアント経由
アシスタントへ移動	GitBook('navigateToAssistant')	frame.navigateToAssistant()	フレームクライアント経由
メッセージを送信	GitBook('postUserMessage', message)	frame.postUserMessage(message)	フレームクライアント経由
チャットをクリア	GitBook('clearChat')	frame.clearChat()	フレームクライアント経由
設定	GitBook('configure', settings)	frame.configure(settings)	Props 対応 <GitBookFrame>
イベントリスナー	❌	frame.on(event, listener)	フレームクライアント経由
アンロード	GitBook('unload')	❌	❌

スタンドアロンスクリプト API

初期化

GitBook('init', options, frameOptions)

サイト URL と、必要に応じて認証済みアクセスを使ってウィジェットを初期化します。

パラメータ:

• options: { siteURL: string } - GitBook ドキュメントサイトの URL

• frameOptions: { visitor?: { token?: string, unsignedClaims?: Record<string, unknown> }, colorScheme?: 'light' | 'dark' } （任意）- フレームオプション

例:

window.GitBook('init', 
  { siteURL: 'https://docs.company.com' },
  { visitor: { token: 'your-jwt-token' }, colorScheme: 'dark' }
);

省略した場合、 colorScheme は iframe の CSS に従います color-scheme.

ウィジェットの制御

ウィジェットを表示

非表示になっている場合は GitBook ウィジェットを表示します。

例:

window.GitBook("show");

ウィジェットを非表示にする

GitBook ウィジェットをアンロードせずに非表示にします。

例:

window.GitBook("hide");

ウィンドウを開く

Docs Embed ウィンドウを開きます。

例:

window.GitBook("open");

ウィンドウを閉じる

Docs Embed ウィンドウを閉じます。

例:

window.GitBook("close");

ウィンドウを切り替える

Docs Embed ウィンドウの開閉を切り替えます。

例:

window.GitBook("toggle");

ウィジェットをアンロードする

サイトから GitBook ウィジェットを完全に削除します。

例:

window.GitBook("unload");

ナビゲーション

GitBook('navigateToPage', path)

パスを指定して、GitBook ドキュメント内の特定のページへ移動します。

パラメータ:

• path (string): 移動先ページのパス

例:

// はじめにガイドへ移動
window.GitBook("navigateToPage", "/getting-started");

// 特定の API ドキュメントページへ移動
window.GitBook("navigateToPage", "/api/authentication");

// FAQ セクションへ移動
window.GitBook("navigateToPage", "/faq/billing");

GitBook('navigateToAssistant')

アシスタントタブへ直接移動します。

例:

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

// ボタンクリックへの応答として使用できます
document.getElementById("help-button").addEventListener("click", () => {
  window.GitBook("navigateToAssistant");
});

チャット

GitBook('postUserMessage', message)

ユーザーが入力したかのようにチャットへメッセージを送信します。

パラメータ:

• message (string): チャットに送信するメッセージ

例:

// 事前定義されたメッセージを送信
window.GitBook("postUserMessage", "パスワードをリセットするにはどうすればよいですか？");

// ユーザー操作に基づいてメッセージを送信
function askAboutBilling() {
  window.GitBook("postUserMessage", "請求に関して質問があります");
}

// コンテキスト付きでメッセージを送信
const userPlan = "premium";
window.GitBook(
  "postUserMessage",
  `私は ${userPlan} プランを利用しており、高度な機能についてサポートが必要です`
);

GitBook('clearChat')

現在のチャットセッションからすべてのメッセージを消去します。

例:

// チャットをクリア
window.GitBook("clearChat");

// チャットをクリアして新しい会話を開始
function startNewConversation() {
  window.GitBook("clearChat");
  window.GitBook("postUserMessage", "こんにちは。新しい問題について助けが必要です");
}

// コンテキストを切り替えるときにチャットをクリア
document.getElementById("new-topic").addEventListener("click", () => {
  window.GitBook("clearChat");
  window.GitBook("navigateToAssistant");
});

設定

GitBook('configure', settings)

カスタマイズオプションで埋め込みを設定します。利用可能なオプションについては、 設定セクション を参照してください。

例:

window.GitBook('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 とは何ですか？', 'どうやって始めればよいですか？']
});

NPM パッケージ API

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

createGitBook(options)

GitBook クライアントインスタンスを作成します。

パラメータ:

• options: { siteURL: string } - GitBook ドキュメントサイトの URL

戻り値: GitBookClient

例:

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

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

client.getFrameURL(options)

認証済みアクセスをオプションで使用して iframe URL を取得します。

パラメータ:

• options: { visitor?: { token?: string, unsignedClaims?: Record<string, unknown> }, colorScheme?: 'light' | 'dark' } （任意）

戻り値: string

例:

const iframeURL = gitbook.getFrameURL({
  colorScheme: 'dark',
  visitor: {
    token: 'your-jwt-token',
    unsignedClaims: { userId: '123', plan: 'premium' }
  }
});

client.createFrame(iframe)

iframe と通信するためのフレームクライアントを作成します。

パラメータ:

• iframe: HTMLIFrameElement - iframe 要素

戻り値: GitBookFrameClient

例:

const iframe = document.createElement('iframe');
iframe.src = gitbook.getFrameURL();
const frame = gitbook.createFrame(iframe);

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

frame.navigateToPage(path)

docs タブ内の特定のページへ移動します。

パラメータ:

• path: string - ページへのパス

frame.navigateToAssistant()

アシスタントタブに切り替えます。

frame.postUserMessage(message)

チャットへメッセージを送信します。

パラメータ:

• message: string - 送信するメッセージ

frame.clearChat()

チャット履歴をクリアします。

frame.configure(settings)

埋め込みを設定します。詳しくは 設定セクション を参照してください。

frame.on(event, listener)

イベントリスナーを登録します。

パラメータ:

• event: string - イベント名

• listener: Function - コールバック関数

戻り値: () => void - 登録解除関数

例:

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

// 後で登録解除
unsubscribe();

React コンポーネント API

詳しくは React 統合ガイド でコンポーネント props と useGitBook フック API を参照してください。

GitBookFrame は assistantName, closeButton, colorScheme="light" | "dark"をサポートし、認証済みアクセス用の visitor prop もサポートします。

useGitBook().getFrameURL() は NPM パッケージと同じ colorScheme パラメータを受け取ります。