認証
訪問者トークンを渡すか認証済みアクセスを使用することで、認証が必要なサイトでも Docs Embed を利用できます
GitBook のドキュメントで認証が必要な場合（例: OIDC、Auth0、またはカスタムバックエンドによる訪問者認証）、ユーザーの認証トークンが提供されない限り、埋め込みはドキュメントの内容にアクセスできません。
アプローチは 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>import { createGitBook } from "@gitbook/embed";
const gitbook = createGitBook({
siteURL: "https://docs.company.com",
});
const iframe = document.createElement("iframe");
iframe.src = gitbook.getFrameURL({
visitor: {
token: "your-jwt-token",
unsignedClaims: { userId: "123", plan: "premium" },
},
});<GitBookProvider siteURL="https://docs.company.com">
<GitBookFrame
visitor={{
token: "your-jwt-token",
unsignedClaims: { userId: "123" },
}}
/>
</GitBookProvider>アプローチ 2: Cookie ベースの検出
ドキュメントサイトが Cookie に訪問者トークンを保存している場合（ gitbook-visitor-tokenのように）、埋め込みを読み込む前にそれを確認できます。
ユーザーが認証済みドキュメントにサインインすると、GitBook はブラウザ Cookie にキー gitbook-visitor-tokenとして訪問者トークンを保存します。埋め込みは、ドキュメントからコンテンツを取得するためにこのトークンを必要とします。
フロー:
ユーザーがドキュメントサイトにサインインする
GitBook がブラウザ Cookie に訪問者トークンを保存する
アプリがトークンの有無を確認する
トークンが存在する場合、埋め込みを読み込んでトークンを渡す
トークンが存在しない場合、ユーザーにサインインを促す
コピペ用スニペット
このスニペットを使うと、ユーザーがサインインした後にのみ埋め込みを読み込めます:
<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 パッケージを使用する場合は、初期化前にトークンの有無を確認します:
import { createGitBook } from "@gitbook/embed";
function initializeEmbed() {
// Cookie 内のトークンを確認する
const getCookie = (name) => {
const value = `; ${document.cookie}`;
const parts = value.split(`; ${name}=`);
if (parts.length === 2) return parts.pop().split(";").shift();
};
const token = getCookie("gitbook-visitor-token");
if (!token) {
console.warn("[Docs Embed] まずユーザーはサインインする必要があります。");
return null;
}
const gitbook = createGitBook({
siteURL: "https://docs.example.com",
});
const iframe = document.createElement("iframe");
iframe.src = gitbook.getFrameURL({
visitor: { token: token },
});
const frame = gitbook.createFrame(iframe);
document.getElementById("embed-container").appendChild(iframe);
return frame;
}
initializeEmbed();React アプリでは、トークンの有無に基づいて埋め込みを条件付きで表示します:
import { useEffect, useState } from "react";
import { GitBookProvider, GitBookFrame } from "@gitbook/embed/react";
function App() {
const [token, setToken] = useState(null);
useEffect(() => {
// Cookie 内のトークンを確認する
const getCookie = (name) => {
const value = `; ${document.cookie}`;
const parts = value.split(`; ${name}=`);
if (parts.length === 2) return parts.pop().split(";").shift();
};
const visitorToken = getCookie("gitbook-visitor-token");
setToken(visitorToken);
}, []);
if (!token) {
return (
<div>
<p>ヘルプにアクセスするにはサインインしてください。</p>
<a href="https://docs.example.com">サインイン</a>
</div>
);
}
return (
<GitBookProvider siteURL="https://docs.example.com">
<YourAppContent />
<GitBookFrame visitor={{ token: token }} />
</GitBookProvider>
);
}よくある落とし穴
サインイン前に埋め込みを読み込む – スクリプトやコンポーネントを読み込む前に必ずトークンを確認するか、初期化時にトークンを直接渡してください。
トークンがドメイン間で保持されない – ブラウザのセキュリティポリシーにより、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 のドキュメント – 完全な埋め込みガイド
最終更新
役に立ちましたか？