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', {
  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: 関数 - コールバック関数

戻り値： () => void - 解除関数

例：

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

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

React コンポーネント API

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