个性化内容

在保持文档公开访问的同时，为已识别的访客定制内容。个性化的典型场景包括预填充 API 密钥、展示与用户订阅计划或角色相关的特定内容，以及根据用户组成员身份筛选 API 参考内容。

个性化通过共享会话、JWT 或 OAuth 来识别访客，同时不会限制访客对页面的访问。

在控制台的 常规 页面启用个性化。个性化与完整认证相互排斥。JWT 与 OAuth 认证已经包含个性化功能。

1. 前往控制台的 常规 页面。
2. 在 Personalization 部分，选择共享会话、JWT 或 OAuth。
3. 配置所选的个性化方式。
4. 点击 Save changes。

共享会话会复用访客在你的应用中已有的会话，因此他们无需在 Mintlify 站点上再次登录。

1. 在 Personalization 设置中选择 Shared session。
2. 填入一个用于返回当前访客用户数据的 Info API URL。
3. 可选：填入 Login URL。当 Info API 未返回用户数据时，Mintlify 会显示一个登录链接。
4. 点击 Save changes。

Mintlify 会从访客的浏览器向 Info API 发起一个带凭据的 GET 请求。对于已识别的访客，请返回成功的 JSON 响应：

{
  "expiresAt": 1893456000,
  "content": {
    "firstName": "Jane",
    "plan": "Enterprise"
  },
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer user_abc123"
    }
  }
}

如果访客没有有效会话，请返回非成功的响应，例如 401。此时 Mintlify 会将该访客保持为未识别状态，并继续提供公开内容。

如果 Info API 与你的文档不在同一来源，请将其配置为允许来自文档确切来源的带凭据跨源请求。请勿在启用凭据的同时使用通配符来源。为防止浏览器和中间缓存存储用户数据，请返回 Cache-Control: private, no-store。

JWT 和 OAuth 个性化使用与共享会话相同的用户数据格式，但不会限制对文档的访问。请在 常规 而不是 访问 中配置这些方式。

JWT 个性化的配置步骤：

1. 输入你现有登录流程的 URL。
2. 点击 Save changes。
3. 点击 Generate new key，并将下载的私钥安全存储起来。
4. 在你的登录流程中，创建一个包含已识别访客用户数据的 JWT，并使用生成的私钥以 ES256 算法进行签名。
5. 将访客重定向到你文档站点上的某个页面，并将已签名的 JWT 作为 URL 片段。例如 https://docs.example.com/get-started#{SIGNED_JWT}。若使用自定义子路径，请在此 URL 中包含该子路径。

将 JWT 的 exp 声明设置为一个较短的时长，10 秒或更短。使用用户数据中的 expiresAt 字段来控制 Mintlify 存储个性化数据的时间。

OAuth 个性化的配置步骤：

1. 输入你的授权 URL、Client ID、scopes、Token URL、Info API URL 以及任何可选设置，然后点击 Save changes。OAuth 个性化使用带 Proof Key for Code Exchange (PKCE) 的 Authorization Code 流程，无需 client secret。
2. 从控制台复制 Redirect URL，并将其添加为 OAuth 提供方的授权重定向 URL。
3. 将 Info API 配置为接受带有 Authorization: Bearer <access_token> 头的 GET 请求，并返回用户数据。

OAuth 回调路径为 /mintlify-oauth-callback。如果使用自定义子路径，控制台会在重定向 URL 中包含该子路径。

Mintlify 会交换授权码，并从访客浏览器向 Info API 发起请求。如果 token 端点或 Info API 端点与你的文档不在同一来源，请将其配置为允许来自文档确切来源的跨源请求。Info API 必须允许 Authorization 请求头。

通过在用户数据中返回匹配的字段名，自动为 API 操作台中的字段填入用户特定的值。将这些值包含在你的用户数据的 apiPlaygroundInputs 字段中。

{
  "apiPlaygroundInputs": {
    "header": { "X-API-Key": "user_api_key_123" },
    "server": { "subdomain": "acme" }
  }
}

字段名必须与 OpenAPI 规范中定义的名称完全一致。Mintlify 只会应用与当前端点安全方案匹配的值。

在 MDX 页面中使用 user 变量，可根据用户的姓名、套餐或组织等信息动态展示内容。将自定义数据放入用户数据中的 content 字段。

{
  "content": {
    "firstName": "Jane",
    "company": "Acme Corp",
    "plan": "Enterprise"
  }
}

在 MDX 中引用这些值。

欢迎回来,{user.firstName}!您的 {user.plan} 计划为 {user.company} 组织的成员提供 100 个席位。

若要根据用户数据进行条件渲染，请在 JSX 组件中使用 user 变量。

{
  user.plan === 'enterprise'
    ? <>请联系您的管理员以启用此功能。</>
    : <>查看<a href="https://yoursite.com/pricing">定价</a>以了解升级信息。</>
}

要从自定义 JavaScript 文件中读取同一个用户对象，请使用 window.mintlify.user 并监听 mintlify:user 事件。

通过在页面 frontmatter 中添加 groups，可根据用户组控制页面在导航中的显示。

---
title: "管理员设置"
groups: ["admin"]
---

使用 OpenAPI 规范中的 x-mint 扩展，根据用户组过滤 API 参考内容。你可以过滤整个端点、单个 schema 属性、oneOf 变体以及枚举值。

在某个 operation 或 path 上添加 x-mint.groups，可以仅在导航中向特定用户组显示该端点。在仅启用个性化（独立于认证）的场景下，不在所列用户组中的用户仍然可以通过直接 URL 打开该端点页面。

{
  "paths": {
    "/billing": {
      "get": {
        "summary": "Get billing details",
        "x-mint": {
          "groups": ["admin", "billing"]
        },
        "responses": {
          "200": {
            "description": "Billing details"
          }
        }
      }
    }
  }
}

为请求体、参数或响应中的各个属性添加 x-mint.groups。未包含 x-mint.groups 的属性将仍对所有用户可见。

{
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "internal_id": {
            "type": "string",
            "x-mint": {
              "groups": ["admin"]
            }
          }
        }
      }
    }
  }
}

在本示例中，所有用户都可以看到 name 属性。只有属于 admin 组的用户可以看到 internal_id 属性。

为各个 oneOf 选项添加 x-mint.groups，以限制用户可见的架构变体。

{
  "schema": {
    "oneOf": [
      {
        "title": "Enterprise config",
        "type": "object",
        "x-mint": {
          "groups": ["enterprise"]
        },
        "properties": {
          "sso_enabled": { "type": "boolean" }
        }
      },
      {
        "title": "Standard config",
        "type": "object",
        "properties": {
          "notifications": { "type": "boolean" }
        }
      }
    ]
  }
}

使用 x-mint-enum 扩展按分组来限制单个枚举值。将每个受限的枚举值作为一个 key，并将其允许访问的分组作为对应的值。未在 x-mint-enum 中列出的枚举值对所有用户可见。

{
  "type": "string",
  "enum": ["free", "pro", "enterprise"],
  "x-mint-enum": {
    "pro": ["pro", "enterprise"],
    "enterprise": ["enterprise"]
  }
}

在此示例中，所有用户都会看到 free。属于 pro 或 enterprise 分组的用户会看到 pro。只有属于 enterprise 分组的用户会看到 enterprise。

你的识别或认证系统会返回用于控制个性化的用户数据。本页中描述的 groups、content 和 apiPlaygroundInputs 字段都是用户数据对象的一部分。

有关完整的用户数据格式和字段说明，请参见用户数据格式。

登出操作在客户端完成。当用户点击登出按钮时，Mintlify 会清除他们在浏览器中存储的会话数据。

要限制个性化数据的保留时间，请在用户数据中设置 expiresAt 字段。