APIリファレンス

Docs Embed をプログラム的に操作する際に利用できるメソッドについて詳しく学ぶ

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

メソッド比較

メソッド	スタンドアロンスクリプト	NPM パッケージ	React コンポーネント
初期化	GitBook('init', options, frameOptions)	createGitBook(options)	<GitBookProvider siteURL="...">
フレーム 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> } } （任意）- 認証アクセスのオプション

例：

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

ウィジェットの制御

ウィジェットを表示する

非表示になっている場合に 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): 移動したいページのパス

例：

// Getting Started ガイドへ移動
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", "How do I reset my password?");

// ユーザーアクションに基づいてメッセージを送信
function askAboutBilling() {
  window.GitBook("postUserMessage", "I have questions about my billing");
}

// コンテキスト付きでメッセージを送信
const userPlan = "premium";
window.GitBook(
  "postUserMessage",
  `I'm on the ${userPlan} plan and need help with advanced features`
);

GitBook('clearChat')

現在のチャットセッションのすべてのメッセージをクリアします。

例：

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

// チャットをクリアして新しい会話を開始
function startNewConversation() {
  window.GitBook("clearChat");
  window.GitBook("postUserMessage", "Hello, I need help with a new issue");
}

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

設定

GitBook('configure', settings)

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

例：

window.GitBook('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?']
});

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> } } （任意）

返り値： string

例：

const iframeURL = gitbook.getFrameURL({
  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)

ドキュメントタブ内の特定のページへ移動します。

パラメータ：

• 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('Frame closed');
});

// 後で購読を解除
unsubscribe();

React コンポーネント API

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