パーソナライゼーションのセットアップ

ユーザーがログインして、カスタマイズされたドキュメント体験を利用できるようにする

パーソナライゼーションは、ユーザーがログインしているときに、ユーザーごとにドキュメントを最適化します。たとえば、APIキーを自動入力したり、プランや役割に応じたコンテンツを表示したり、不要なセクションを非表示にできます。

パーソナライゼーション機能

以下のパーソナライゼーション機能でコンテンツを最適化・カスタマイズできます。

APIキーの自動入力

ユーザーデータで一致するフィールド名を返すことで、APIプレイグラウンドのフィールドにユーザー固有の値を自動入力できます。自動入力を機能させるには、ユーザーデータ内のフィールド名がAPIプレイグラウンドのフィールド名と完全に一致している必要があります。

動的MDXコンテンツ

user 変数を使って、名前、プラン、組織などのユーザー情報に基づく動的コンテンツを表示します。

Welcome back, {user.firstName}! Your {user.org?.plan} plan includes...

詳しい例と実装ガイドは、以下のユーザーデータ形式セクションを参照してください。

ページの表示制御

ページのフロントマターに groups フィールドを追加して、ユーザーごとに表示されるページを制限できます。デフォルトでは、すべてのページがすべてのユーザーに表示されます。

ユーザーには、自分が所属する groups に該当するページのみが表示されます。

---
title: "Managing your users"
description: "Adding and removing users from your organization"
groups: ["admin"]
---

ユーザーデータ形式

パーソナライゼーションを実装する際、システムはコンテンツのカスタマイズを可能にする特定の形式でユーザーデータを返します。このデータは、ハンドシェイク方式に応じて、生のJSONオブジェクトとして、または署名付きJWT内で送信できます。データの構造はどちらの場合も同じです。

type User = {
  expiresAt?: number;
  groups?: string[];
  content?: Record<string, any>;
  apiPlaygroundInputs?: {
    header?: Record<string, any>;
    query?: Record<string, any>;
    cookie?: Record<string, any>;
    server?: Record<string, string>;
  };
};

expiresAt · number

セッションの有効期限（UNIXエポックからの秒数）。この時刻を過ぎてページを読み込んだ場合、保存されたデータは自動的に削除され、再認証が必要になります。

groups · string[]

ユーザーが所属するグループの一覧。フロントマターの groups が一致するページは、このユーザーに表示されます。

例: groups: ["admin", "engineering"] を持つユーザーは、admin または engineering グループでタグ付けされたページにアクセスできます。

content · object

user 変数を介して MDX コンテンツ内で参照できるカスタムデータ。ドキュメント全体での動的なパーソナライゼーションに使用します。

基本例:

{ "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" }

MDX での使用例:

Welcome back, {user.firstName}! Your {user.plan} plan includes...

上記の user データ例では、次のように表示されます: Welcome back, Ronan! Your Enterprise plan includes…

高度な条件付きレンダリング:

Authentication is an enterprise feature. {
  user.org === undefined
    ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
    : user.org.plan !== 'enterprise'
      ? <>You are currently on the ${user.org.plan ?? 'free'} plan. See <a href="https://mintlify.com/pricing">our pricing page</a> for information about upgrading.</>
      : <>To request this feature for your enterprise org, contact your admin.</>
}

user 内の情報は、ログイン中のユーザーにのみ利用可能です。ログアウト中のユーザーでは user の値は {} です。ログアウト中のユーザーでページがクラッシュするのを防ぐため、user の各フィールドには常にオプショナルチェイニングを使用してください。例: {user.org?.plan}。

apiPlaygroundInputs · object

APIプレイグラウンドのフィールドに事前入力される、ユーザー固有の値。APIをテストする際にユーザーのデータを自動入力し、作業時間を短縮します。

例:

{
  "header": { "X-API-Key": "user_api_key_123" },
  "server": { "subdomain": "foo" },
  "query": { "org_id": "12345" }
}

ユーザーが特定のサブドメインでリクエストを行う場合は、apiPlaygroundInputs フィールドとして { server: { subdomain: 'foo' } } を送信できます。この値は、subdomain を使用する任意のAPIページで事前入力されます。

header、query、cookie の各フィールドは、あなたの OpenAPI security scheme の一部である場合にのみ事前入力されます。フィールドが Authorization または Server セクションに含まれていれば事前入力されます。Authorization という名前の標準ヘッダーパラメータを作成しても、この機能は有効になりません。

ユーザー データの例

{
  "expiresAt": 1735689600,
  "groups": ["admin", "beta-users"],
  "content": {
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "plan": "Enterprise",
    "region": "us-west"
  },
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer abc123",
      "X-Org-ID": "techcorp"
    },
    "server": {
      "environment": "production",
      "region": "us-west"
    }
  }
}

パーソナライゼーションの設定

設定するハンドシェイク方式を選択してください。

JWT

前提条件

• JWT を生成して署名できるログインシステム
• リダイレクト URL を作成できるバックエンドサービス

実装

1. 秘密鍵を生成する

   1. ダッシュボードで Authentication に移動します。
   2. Personalization を選択します。
   3. JWT を選択します。
   4. 既存のログインフローの URL を入力し、Save changes を選択します。
   5. Generate new key を選択します。
   6. バックエンドからアクセス可能な安全な場所にキーを保管します。
2. Mintlify のパーソナライゼーションをログインフローに統合する

   既存のログインフローに、ユーザーのログイン後に次の手順を追加します:

   • ログイン中のユーザー情報を User 形式で含む JWT を作成します。詳細は上記の User data format セクションを参照してください。
   • ES256 アルゴリズムを使用して、その秘密鍵で JWT に署名します。
   • JWT をハッシュとして含め、ドキュメントに戻るリダイレクト URL を作成します。

例

あなたのドキュメントは docs.foo.com でホストされています。ドキュメントをダッシュボードとは分離したい（またはダッシュボードがない）場合に、パーソナライゼーションを有効にします。

JWT シークレットを生成します。次に、https://foo.com/docs-login にログインエンドポイントを作成し、ドキュメント向けのログインフローを開始します。

ユーザーの認証情報を検証した後:

• Mintlify の形式でユーザーデータを含む JWT を生成します。
• JWT に署名し、https://docs.foo.com#{SIGNED_JWT} にリダイレクトします。

import * as jose from 'jose';
import { Request, Response } from 'express';

const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;

const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'ES256');

export async function handleRequest(req: Request, res: Response) {
  const user = {
    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000),
    groups: res.locals.user.groups,
    content: {
      firstName: res.locals.user.firstName,
      lastName: res.locals.user.lastName,
    },
  };

  const jwt = await new jose.SignJWT(user)
    .setProtectedHeader({ alg: 'ES256' })
    .setExpirationTime('10 s')
    .sign(signingKey);

  return res.redirect(`https://docs.foo.com#${jwt}`);
}

ページアンカーの保持

ログイン後に特定のセクションへユーザーをリダイレクトするには、次の URL 形式を使用します: https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}。

例:

• 元の URL: https://docs.foo.com/quickstart#step-one
• リダイレクト先の URL: https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one