認証

訪問者トークンの渡しや認証付きアクセスを使って認証が必要なサイトでDocs Embedを使う

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

アプローチは二つあります：

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

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

アプローチ1：トークンを直接渡す（推奨）

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

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

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

NPM パッケージ

React コンポーネント

アプローチ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";
    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";
    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、ユーザーはまだあなたのドキュメントにサインインしていません。

次のステップ

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

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

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