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): 移動先ページへのパス

例:

// はじめにガイドへ移動
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', 'docs'],
  actions: [
    {
      icon: 'circle-question',
      label: 'サポートに連絡',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: 'ようこそ！', subtitle: 'どのようにお手伝いできますか？' },
  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> } } （任意）

返り値: 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)

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

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