Cookies（Cookie）

通过公共或签名 cookie 将访客数据传入您的文档

前往我们的指南以查找 完整的逐步教程 有关使用 cookie 设置自适应内容的说明。

将自适应内容与功能开关一起使用需要向您的应用程序添加代码。

此方法仅在您的网站在 自定义域名.

下提供服务时才有效。您可以通过访问者的浏览器 cookie 将访问者数据传递到您的文档。下面是不同方法的概述。

方法	使用场景	设置难易度	安全性	格式
签名 cookie gitbook-visitor-token	API 测试凭据、客户识别	需要签名和自定义域名	✅ 属性只能由后端定义	JWT
公开 cookie gitbook-visitor-public	功能开关、角色	易于设置	❌ 访问者可以覆盖这些属性	JSON

公开 cookie

要通过公开 cookie 将数据传递到 GitBook，您需要从应用程序发送数据，通过设置一个公开的 gitbook-visitor-public cookie。

下面是一个简单的 JavaScript 示例：

import Cookies from 'js-cookie';

const cookieData = {
  isLoggedIn: true,
  isBetaUser: false,
};

Cookies.set('gitbook-visitor-public', JSON.stringify(cookieData), {
  secure: true,
  domain: '*.acme.org',
})

通过公开 cookie 传递的数据必须在您的访问者模式（visitor schema）中通过一个 未签名的 对象来定义。

签名 cookie

要更安全地将数据传递给 GitBook，您需要从应用程序将数据作为 JSON Web Token 在名为的 cookie 中发送， gitbook-visitor-token 并绑定到您的域名。

要设置此项，您需要调整应用的登录流程以包含以下步骤：

1

在用户登录到您的应用时生成 JWT

每当用户登录您的产品时，生成一个包含已验证用户信息中所选属性的 JWT。

2

使用站点的访问者签名密钥对 JWT 进行签名

然后，确保使用站点的 访问者签名密钥对 JWT 进行签名，您可以在启用自适应内容后在站点的受众设置中找到它。

3

将 JWT 存储在通配符会话 cookie 中

最后，您需要将包含用户信息的已签名 JWT 存储到一个通配符会话 cookie 中 在您的产品域名下。.

例如，如果您的应用部署在 app.acme.org 域名后面，则该 cookie 需要在 .acme.org 通配符域名下创建。

下面是一个简单的 TypeScript 示例：

import * as jose from 'jose';

import { Request, Response } from 'express';

import { getUserInfo } from '../services/user-info-service';
import { getFeatureFlags } from '../services/feature-flags-service';

const GITBOOK_VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY;
const GITBOOK_VISITOR_COOKIE_NAME = 'gitbook-visitor-token';


export async function handleAppLoginRequest(req: Request, res: Response) {
   // 处理登录请求的业务逻辑
   // 例如，检查凭证并对用户进行认证
   //
   // 例如：
   // const loggedInUser = await authenticateUser(req.body.username, req.body.password);

   // 在验证用户后，从您的数据库或用户服务中检索您希望
   // 传递给 GitBook 的用户信息。
   const userInfo = await getUserInfo(loggedInUser.id);
      
   // 使用用户的信息构建 JWT 负载
   const gitbookVisitorClaims = {
       firstName: userInfo.firstName,
       lastName: userInfo.lastName,
       isBetaUser: userInfo.isBetaUser
       products: userInfo.products.map((product) => product.name),
       featureFlags: await getFeatureFlags({userId: loggedInUser.id})
   }
   
   // 使用声明生成已签名的 JWT
   const gitbookVisitorJWT = await new jose.SignJWT(gitbookVisitorClaims)
     .setProtectedHeader({ alg: 'HS256' })
     .setIssuedAt()
     .setExpirationTime('2h') // 任意的 2 小时过期时间
     .sign(GITBOOK_VISITOR_SIGNING_KEY);
     
  // 在您的登录处理程序响应中包含一个包含编码后 JWT 的 `gitbook-visitor-token` cookie
  //
  res.cookie(GITBOOK_VISITOR_COOKIE_NAME, gitbookVisitorJWT, {
     httpOnly: true,
     secure: process.env.NODE_ENV === 'production',
     maxAge: 2 * 60 * 60 * 1000, // 任意的 2 小时过期时间
     domain: '.acme.org' //
  });
  
  // 登录处理程序的其余逻辑，包括将用户重定向到您的应用
  res.redirect('/'); // 示例重定向
}