> 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)`           | のプロパティ `<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')`

Assistant タブに直接移動します。

**例:**

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

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

### チャット

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

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

**パラメーター:**

* `message` （string）：チャットに送信するメッセージ

**例:**

```javascript
// 定型メッセージを送信
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')`

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

**例:**

```javascript
// チャットを消去する
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)`

カスタマイズオプションを使用して埋め込みを設定します。利用可能なオプションについては、 [設定セクション](https://gitbook.com/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: 'Contact Support',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
  assistantName: 'Support Copilot',
  closeButton: true,
  suggestions: ['What is GitBook?', 'How do I get started?']
});
```

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

埋め込みを設定します。利用可能なオプションについては、 [設定セクション](https://gitbook.com/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('Frame closed');
});

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

## React コンポーネント API

コンポーネントの props と [React 統合ガイド](https://gitbook.com/docs/documentation/ja-gitbook-documentation/publish/embedding/implementation/react.md) 、および `useGitBook` フック API については、

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

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


---

# 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.
