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: 'サポート 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() 同じ colorScheme パラメーターを NPM パッケージと同じように受け取ります。