認証

訪問者トークンを渡す、または認証済みアクセスを使用することで、認証が必要なサイトでも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 config API は変更されていません。署名付きの訪問者トークンは次のように渡します visitor.token.

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

アプローチ 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を返す場合、ユーザーはまだドキュメントにサインインしていません。

次のステップ

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

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

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