> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/ja-gitbook-documentation/publish/embedding/configuration/reference.md).

# 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' }` （任意）- フレームオプション

**例:**

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

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

### ウィジェットの制御

#### ウィジェットを表示

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

**例:**

```js
window.GitBook("show");
```

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

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

**例:**

```js
window.GitBook("hide");
```

#### ウィンドウを開く

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

**例:**

```js
window.GitBook("open");
```

#### ウィンドウを閉じる

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

**例:**

```js
window.GitBook("close");
```

#### ウィンドウを切り替える

Docs Embed ウィンドウを開閉します。

**例:**

```js
window.GitBook("toggle");
```

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

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

**例:**

```js
window.GitBook("unload");
```

### ナビゲーション

#### `GitBook('navigateToPage', path)`

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

**パラメーター:**

* `path` （string）: 移動先ページのパス

**例:**

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

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

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

#### `GitBook('navigateToAssistant')`

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

**例:**

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

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

### チャット

#### `GitBook('postUserMessage', message)`

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

**パラメーター:**

* `message` （string）: チャットに投稿するメッセージ

**例:**

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

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

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

#### `GitBook('clearChat')`

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

**例:**

```javascript
// チャットをクリア
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)`

埋め込みをカスタマイズオプションで設定します。詳細は [設定セクション](/docs/documentation/ja-gitbook-documentation/publish/embedding/implementation/script.md#configuration-options) 利用可能なオプションについて。

**例:**

```javascript
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`

**例:**

```javascript
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`

**例:**

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

#### `client.createFrame(iframe)`

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

**パラメーター:**

* `iframe`: `HTMLIFrameElement` - iframe 要素

**返り値:** `GitBookFrameClient`

**例:**

```javascript
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)`

埋め込みを設定します。詳細は [設定セクション](/docs/documentation/ja-gitbook-documentation/publish/embedding/implementation/nodejs.md#configuration-options) 利用可能なオプションについて。

#### `frame.on(event, listener)`

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

**パラメーター:**

* `event`: `string` - イベント名
* `listener`: `Function` - コールバック関数

**返り値:** `() => void` - 登録解除関数

**例:**

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

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

## React コンポーネント API

以下を参照してください [React 統合ガイド](/docs/documentation/ja-gitbook-documentation/publish/embedding/implementation/react.md) コンポーネントの props と `useGitBook` フック API。

`GitBookFrame` がサポートする `assistantName`, `closeButton`, `colorScheme="light" | "dark"`、および `visitor` 認証済みアクセス用の prop。

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/publish/embedding/configuration/reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.