# Node.js/NPM

より細かな制御が必要で、アプリケーションレベルで作業したい場合は、npm から GitBook の埋め込みパッケージをインストールできます。このアプローチは、サーバーサイドレンダリング、ビルド時の統合、またはカスタム iframe 管理に最適です。

## 手順

{% stepper %}
{% step %}
**パッケージをインストールする**

追加する `@gitbook/embed` をプロジェクトに:

```bash
npm install @gitbook/embed
```

完全な API リファレンスとソースコードについては、 [`@gitbook/embed` の GitHub 上のパッケージを参照してください](https://github.com/GitbookIO/gitbook/tree/main/packages/embed).
{% endstep %}

{% step %}
**パッケージをインポートする**

アプリケーションコードで、 `createGitBook` 関数をインポートします:

```javascript
import { createGitBook } from "@gitbook/embed";
```

または CommonJS を使用する場合:

```javascript
const { createGitBook } = require("@gitbook/embed");
```

{% endstep %}

{% step %}
**GitBook を初期化する**

ドキュメントサイトの URL を使って GitBook インスタンスを作成します:

```javascript
const gitbook = createGitBook({
  siteURL: "https://docs.company.com",
});
```

{% endstep %}

{% step %}
**iframe を作成する**

iframe 要素を生成し、そのソースを埋め込み URL に設定します:

```javascript
const iframe = document.createElement("iframe");
iframe.src = gitbook.getFrameURL({
  visitor: {
    token: 'your-jwt-token', // 任意: Adaptive Content または認証済みアクセス用
    unsignedClaims: { // 任意: 動的式のためのカスタムクレーム
      userId: '123',
      plan: 'premium'
    }
  }
});
iframe.id = "gitbook-embed-container";
iframe.style.border = "none";
iframe.style.width = "100%";
iframe.style.height = "600px";
```

{% endstep %}

{% step %}
**フレームを追加する**

GitBook フレームインスタンスを作成し、ページにマウントします:

```javascript
const frame = gitbook.createFrame(iframe);
document.getElementById("gitbook-embed-container").appendChild(iframe);
```

{% endstep %}

{% step %}
**埋め込みをプログラムで制御する**

フレームインスタンスを使って埋め込みとやり取りします:

```javascript
// ドキュメントタブの特定ページへ移動
frame.navigateToPage("/getting-started");

// アシスタントタブに切り替える
frame.navigateToAssistant();

// チャットにメッセージを送信
frame.postUserMessage("How do I get started?");

// チャット履歴をクリア
frame.clearChat();
```

{% endstep %}

{% step %}
**埋め込みを設定する**

カスタマイズオプションで埋め込みを設定します:

```javascript
frame.configure({
  trademark: false,
  tabs: ['assistant', 'search', 'docs'],
  actions: [
    {
      icon: 'circle-question',
      label: 'サポートに問い合わせる',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: 'ようこそ！', subtitle: 'どのようにお手伝いできますか？' },
  assistantName: 'Support Copilot',
  closeButton: true,
  suggestions: ['GitBook とは何ですか？', 'どうやって始めればよいですか？'],
  tools: [/* ... */]
});
```

{% endstep %}

{% step %}
**イベントを監視する**

埋め込みイベントに応答するためにイベントリスナーを登録します:

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

// 完了したら購読解除
const unsubscribe = frame.on('navigate', (data) => {
  console.log('移動先:', data.path);
});
```

{% endstep %}
{% endstepper %}

## API リファレンス

### クライアントファクトリー

* `createGitBook(options: { siteURL: string })` → `GitBookClient`
* `client.getFrameURL(options?: { visitor?: {...}, colorScheme?: 'light' | 'dark' })` → `string` - 任意のフレームオプション付きで iframe の URL を取得する
* `client.createFrame(iframe: HTMLIFrameElement)` → `GitBookFrameClient` - iframe と通信するためのフレームクライアントを作成する

### フレームクライアントメソッド

* `frame.navigateToPage(path: string)` → `void` - ドキュメントタブの特定ページへ移動する
* `frame.navigateToAssistant()` → `void` - アシスタンスタブに切り替える
* `frame.postUserMessage(message: string)` → `void` - チャットにメッセージを送信する
* `frame.clearChat()` → `void` - チャット履歴をクリアする
* `frame.configure(settings: Partial<GitBookEmbeddableConfiguration>)` → `void` - 埋め込みを設定する
* `frame.on(event: string, listener: Function)` → `() => void` - イベントリスナーを登録する（unsubscribe 関数を返します）

## 設定オプション

ほとんどのカスタマイズオプションは `frame.configure({...})`.

#### `tabs`

で利用できます。表示するタブを上書きします。

検索はデフォルトで有効です。 `tabs`を設定すると、埋め込みにはリストしたタブのみが表示されます。

* **入力します**: `('assistant' | 'search' | 'docs')[]`

#### `を設定すると`

タブと並んでサイドバーに表示されるカスタムアクションボタンです。各アクションボタンはクリック時にコールバックを実行します。

**注**: 以前はこれは `buttons`という名前でした。 `を設定すると` の代わりに行うことをおすすめします。

* **入力します**: `Array<{ icon: string, label: string, onClick: () => void }>`

#### `greeting`

Assistant タブに表示されるウェルカムメッセージ。

* **入力します**: `{ title: string, subtitle: string }`

#### `assistantName`

UI に表示されるアシスタント名を上書きします。

* **入力します**: `string`
* **最大長**: `32` 文字

#### `closeButton`

Assistant 内に閉じるボタンを表示します。

* **入力します**: `boolean`

#### `suggestions`

Assistant のウェルカム画面に表示されるおすすめの質問。

* **入力します**: `string[]`

#### `trademark`

埋め込み UI で GitBook の商標を表示または非表示にします。これには Docs Embed のフッターと Assistant のブランド表示が含まれます。

* **入力します**: `boolean`
* **デフォルト**: `true`

#### `tools`

Assistant を拡張するカスタム AI ツール。詳細は [カスタムツールの作成](/docs/documentation/ja-gitbook-documentation/docs-site/embedding/configuration/creating-custom-tools.md) を参照してください。

* **入力します**: `Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>`

### フレーム URL のオプション

一部のオプションは `getFrameURL({...})`.

#### `colorScheme`

に渡されます。埋め込みの配色を上書きします。

省略した場合、埋め込みは iframe の CSS `color-scheme`に従い、親ページまたはブラウザの設定を継承できます。

* **入力します**: `'light' | 'dark'`

### `visitor` (認証済みアクセス)

以下に渡します `getFrameURL({ visitor: {...} })`。用途は [Adaptive Content](/docs/documentation/ja-gitbook-documentation/saitoakusesu/adaptive-content.md) 、 [認証済みアクセス](/docs/documentation/ja-gitbook-documentation/saitoakusesu/authenticated-access.md).

* **入力します**: `{ token?: string, unsignedClaims?: Record<string, unknown> }`

## よくある落とし穴

* **パッケージのインストールを忘れる** – 次を実行してから `npm install @gitbook/embed` インポートしてください。
* **siteURL がない** – `siteURL` オプションは必須で、公開済みのドキュメントサイトと一致している必要があります。
* **iFrame がレンダリングされない** – 親コンテナに iframe を表示するのに十分な幅/高さがあることを確認してください。
* **初期化前にフレームメソッドを呼び出す** – まで待ってから `createFrame()` が完了してからフレームメソッドを呼び出してください。
* **イベントの購読解除をしない** – `frame.on()` から返される unsubscribe 関数を必ず呼び出して、メモリリークを防いでください。
* **古い API メソッドを使う** – 以下のようなメソッド `open()`, `close()`, `toggle()`、および `destroy()` は NPM パッケージでは利用できません。代わりに frame client のメソッドを使用してください。


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-site/embedding/implementation/nodejs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.