認証

訪問者トークンを渡すか認証付きアクセスを使用して認証が必要なサイトで Docs Embed を利用する

GitBookドキュメントが認証を必要とする場合（例：OIDC、Auth0、またはカスタムバックエンドを介した訪問者認証）、ユーザーの認証トークンが提供されない限り埋め込みはドキュメントのコンテンツにアクセスできません。

2つの方法があります：

1. トークンを直接渡す （推奨）- 訪問者トークンで埋め込みを初期化する

2. クッキー検出を使用する - 読み込み前にクッキー内のトークンを確認する

方法1：トークンを直接渡す（推奨）

埋め込みを初期化する際に、訪問者トークンを直接渡します：

スタンドアロンスクリプト

<script src="https://docs.company.com/~gitbook/embed/script.js?jwt_token=your-jwt-token"></script>
<script>
  window.GitBook(
    "init",
    { siteURL: "https://docs.company.com" },
    { visitor: { token: "your-jwt-token" } }
  );
  window.GitBook("show");
</script>

NPMパッケージ

Reactコンポーネント

Embed構成APIは変更されていません。署名済みの訪問者トークンはとして渡してください visitor.token.

認証されたサイトの場合、GitBookはこのトークンをサイトにとして転送します jwt_token iframe／スクリプトのURLに含めます。認証されたサイトからスタンドアロンスクリプトを読み込む場合、含める必要があります jwt_token に <script src> URL。

方法2：クッキーに基づく検出

ドキュメントサイトが訪問者トークンをクッキーに保存している場合（例： gitbook-visitor-token）、埋め込みを読み込む前にそれを確認できます。

ユーザーが認証されたドキュメントにサインインすると、GitBookはブラウザのクッキーにキーとして訪問者トークンを保存します gitbook-visitor-token。埋め込みはドキュメントからコンテンツを取得するためにこのトークンを必要とします。

フロー：

1. ユーザーがあなたのドキュメントサイトにサインインする

2. GitBookがブラウザのクッキーに訪問者トークンを保存する

3. あなたのアプリがトークンを確認する

4. トークンが存在する場合、埋め込みを読み込みトークンを渡す

5. トークンが存在しない場合、ユーザーにサインインを促す

スタンドアロンスクリプト

コピーペースト用スニペット

ユーザーがサインインした後にのみ埋め込みを読み込むにはこのスニペットを使用します：

<script>
  (function () {
    // クッキー内の訪問者トークンを確認する
    function getCookie(name) {
      var value = "; " + document.cookie;
      var parts = value.split("; " + name + "=");
      if (parts.length === 2) return parts.pop().split(";").shift();
    }

    var token = getCookie("gitbook-visitor-token");

    if (!token) {
      console.warn("[Docs Embed] まずドキュメントにサインインしてください。");
      return;
    }

    // トークンが存在するので埋め込みを読み込む
    var script = document.createElement("script");
    script.src =
      "https://docs.example.com/~gitbook/embed/script.js?jwt_token=" +
      encodeURIComponent(token);
    script.async = true;
    script.onload = function () {
      window.GitBook(
        "init",
        { siteURL: "https://docs.example.com" },
        { visitor: { token: token } }
      );
      window.GitBook("show");
    };
    document.head.appendChild(script);
  })();
</script>

を置き換えてください docs.example.com を実際のドキュメントサイトのURLにしてください。

代替：ユーザーにサインインを促す

トークンが見つからない場合、ユーザーにサインインを促すことができます：

<script>
  (function () {
    function getCookie(name) {
      var value = "; " + document.cookie;
      var parts = value.split("; " + name + "=");
      if (parts.length === 2) return parts.pop().split(";").shift();
    }

    var token = getCookie("gitbook-visitor-token");

    if (!token) {
      // ドキュメントにリダイレクトするかメッセージを表示する
      alert("ヘルプにアクセスするにはドキュメントにサインインしてください。");
      window.location.href = "https://docs.example.com";
      return;
    }

    // トークンを使って埋め込みを読み込む
    var script = document.createElement("script");
    script.src =
      "https://docs.example.com/~gitbook/embed/script.js?jwt_token=" +
      encodeURIComponent(token);
    script.async = true;
    script.onload = function () {
      window.GitBook(
        "init",
        { siteURL: "https://docs.example.com" },
        { visitor: { token: token } }
      );
      window.GitBook("show");
    };
    document.head.appendChild(script);
  })();
</script>

NPMパッケージ

Reactコンポーネント

よくある落とし穴

• サインイン前に埋め込みを読み込んでしまうこと – スクリプトやコンポーネントを読み込む前に常にトークンを確認するか、初期化時にトークンを直接渡してください。

• ドメイン間でトークンが保持されないこと – ブラウザのセキュリティポリシーによりクッキーは異なるドメイン間で保持されません。アプリとドキュメントは同じドメインまたはサブドメイン上である必要があるか、トークンを直接渡してください。

• トークンの有効期限切れ – トークンは期限切れになります。埋め込みが認証エラーを返す場合、ユーザーに再度サインインを促してください。

• 間違ったクッキー名の使用 – トークンはとして保存されます gitbook-visitor-token、ではなく gitbook-token やその他のバリエーションではありません。

• init/getFrameURLにトークンを渡していない – クッキー方式を使用する場合、トークンをに渡すことを確認してください GitBook('init', ..., { visitor: { token } }) または getFrameURL({ visitor: { token } }).

デバッグ

トークンが存在するか確認するには、ブラウザコンソールを開いて次を実行します：

document.cookie.split(";").find((c) => c.includes("gitbook-visitor-token"));

これが返された場合 undefined、ユーザーはまだドキュメントにサインインしていません。

次のステップ

• 埋め込みのカスタマイズ – ようこそメッセージやアクションを追加する

• カスタムツールの作成 – 製品のAPIと統合する

• Docs Embedドキュメント – 埋め込みガイド（完全版）