認証

訪問者トークンを渡すか、認証済みアクセスを使用することで、認証が必要なサイトで Docs Embed を利用する

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

アプローチは2つあります:

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

2. Cookie ベースの検出を使う - 読み込み前に Cookie 内のトークンを確認する

アプローチ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/script の URL 内。認証済みサイトからスタンドアロンのスクリプトを読み込む場合は、必ず jwt_token を <script src> を含める必要があります。

アプローチ2: Cookie ベースの検出

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

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

フロー:

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

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

3. アプリがトークンの有無を確認する

4. トークンがあれば、埋め込みを読み込んでトークンを渡す

5. トークンがなければ、ユーザーにサインインを促す

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

コピペ用スニペット

このスニペットを使うと、ユーザーがサインインした後にのみ埋め込みを読み込めます:

<script>
  (function () {
    // Cookie 内の訪問者トークンを確認する
    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 コンポーネント

よくある落とし穴

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

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

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

• Cookie 名が間違っている – トークンは gitbook-visitor-tokenであり、 gitbook-token またはその他のバリエーションとして保存されます。

• init/getFrameURL にトークンを渡していない – Cookie ベースのアプローチを使う場合は、必ずトークンを次の関数に渡してください GitBook('init', ..., { visitor: { token } }) または getFrameURL({ visitor: { token } }).

デバッグ

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

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

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

次のステップ

• 埋め込みのカスタマイズ – ウェルカムメッセージとアクションを追加する

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

• Docs Embed のドキュメント – 埋め込みガイド کامل版