# Node.js/NPM

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

## 手順

{% stepper %}
{% step %}

#### パッケージをインストールする

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

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

完全な API リファレンスとソースコードについては、GitHub 上の次のものを参照してください： [`@gitbook/embed` パッケージ](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 を初期化する

docs サイトの 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', 'docs'],
  actions: [
    {
      icon: 'circle-question',
      label: 'サポートに連絡',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: 'ようこそ！', subtitle: 'どのようにお手伝いできますか？' },
  suggestions: ['What is GitBook?', 'How do I get started?'],
  tools: [/* ... */]
});
```

{% endstep %}

{% step %}

#### イベントを監視する

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

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

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

{% endstep %}
{% endstepper %}

## API リファレンス

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

* `createGitBook(options: { siteURL: string })` → `GitBookClient`
* `client.getFrameURL(options?: { visitor?: {...} })` → `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`

表示するタブを上書きします。既定値はサイトの設定です。

* **入力**: `('assistant' | 'docs')[]`

### `actions`

タブの横にあるサイドバーに表示されるカスタムアクションボタンです。各アクションボタンはクリック時にコールバックをトリガーします。

**注意**：以前はこれを `buttons`と呼んでいました。 `actions` の使用を検討してください。

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

### `greeting`

アシスタンタブに表示されるウェルカムメッセージ。

* **入力**: `{ title: string, subtitle: string }`

### `suggestions`

アシスタントのウェルカム画面に表示される提案質問。

* **入力**: `string[]`

### `trademark`

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

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

### `tools`

アシスタントを拡張するためのカスタム AI ツールです。詳細は [カスタムツールの作成](/docs/documentation/ja-gitbook-documentation/docs-site/embedding/configuration/creating-custom-tools.md) をご覧ください。

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

### `visitor` （認証済みアクセス）

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

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

## よくある落とし穴

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


---

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