Einrichtung der Personalisierung

Ermöglichen Sie Nutzern die Anmeldung für ein personalisiertes Dokumentationserlebnis

Die Personalisierung passt Ihre Dokumentation für jeden Nutzer an, sobald er angemeldet ist. Sie können beispielsweise seine API-Schlüssel vorausfüllen, Inhalte anzeigen, die speziell auf seinen Plan oder seine Rolle zugeschnitten sind, oder Abschnitte ausblenden, auf die er keinen Zugriff benötigt.

Personalisierungsfunktionen

Passen Sie Inhalte mit diesen Personalisierungsoptionen an.

Vorausfüllen von API-Schlüsseln

Fülle die Felder der API-Spielwiese automatisch mit nutzerspezifischen Werten, indem du in deinen Benutzerdaten identische Feldnamen bereitstellst. Die Feldnamen in deinen Benutzerdaten müssen exakt mit den Namen in der API-Spielwiese übereinstimmen, damit das automatische Vorausfüllen funktioniert.

Dynamischer MDX-Inhalt

Zeigen Sie dynamische Inhalte basierend auf Benutzerinformationen wie Name, Tarif oder Organisation mit der Variable user an.

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

Weitere Details und Implementierungsbeispiele finden Sie im Abschnitt Format der Benutzerdaten unten.

Seitensichtbarkeit

Beschränke, welche Seiten für deine Nutzer sichtbar sind, indem du groups-Felder zur Frontmatter deiner Seiten hinzufügst. Standardmäßig ist jede Seite für jeden Nutzer sichtbar.

Nutzer sehen nur Seiten der groups, denen sie angehören.

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

Benutzerdatenformat

Bei der Implementierung von Personalisierung gibt Ihr System Benutzerdaten in einem bestimmten Format zurück, das Inhaltsanpassungen ermöglicht. Diese Daten können je nach Handshake-Methode entweder als Roh-JSON-Objekt oder innerhalb eines signierten JWT gesendet werden. Die Struktur der Daten ist in beiden Fällen identisch.

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

Ablaufzeit der Sitzung in Sekunden seit der Unix-Epoche. Wenn der Nutzer eine Seite nach diesem Zeitpunkt lädt, werden seine gespeicherten Daten automatisch gelöscht und er muss sich erneut authentifizieren.

groups · string[]

Liste der Gruppen, denen der Nutzer angehört. Seiten mit passenden groups im Frontmatter sind für diesen Nutzer sichtbar.

Beispiel: Ein Nutzer mit groups: ["admin", "engineering"] kann auf Seiten zugreifen, die entweder mit der Gruppe admin oder engineering gekennzeichnet sind.

content · object

Benutzerdefinierte Daten, die in Ihrem MDX-Inhalt über die Variable user verfügbar sind. Nutzen Sie dies für dynamische Personalisierung in Ihrer gesamten Dokumentation.

Einfaches Beispiel:

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

Verwendung in MDX:

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

Mit den Beispiel-user-Daten würde dies so gerendert: Welcome back, Ronan! Your Enterprise plan includes…

Erweitertes bedingtes Rendering:

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.</>
}

Die Informationen in user sind nur für angemeldete Nutzer verfügbar. Für abgemeldete Nutzer hat user den Wert {}. Um zu verhindern, dass die Seite für abgemeldete Nutzer abstürzt, verwenden Sie immer Optional Chaining bei Ihren user-Feldern, z. B. {user.org?.plan}.

apiPlaygroundInputs · object

Nutzerspezifische Werte, die Felder der API-Spielwiese vorab ausfüllen. Spart Zeit, indem beim Testen von APIs Daten automatisch übernommen werden.

Beispiel:

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

Wenn ein Nutzer Anfragen über eine bestimmte Subdomain stellt, können Sie { server: { subdomain: 'foo' } } als Feld apiPlaygroundInputs senden. Dieser Wert wird auf jeder API-Seite mit dem subdomain-Wert vorab ausgefüllt.

Die Felder header, query und cookie werden nur vorab ausgefüllt, wenn sie Teil Ihres OpenAPI-Sicherheitsmodells sind. Befindet sich ein Feld in den Abschnitten Authorization oder Server, wird es vorab ausgefüllt. Das Erstellen eines Standard-Header-Parameters namens Authorization aktiviert diese Funktion nicht.

Beispielnutzerdaten

{
  "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"
    }
  }
}

Personalisierung konfigurieren

Wählen Sie die Handshake-Methode aus, die Sie konfigurieren möchten.

JWT

Voraussetzungen

• Ein Login-System, das JWTs erzeugen und signieren kann
• Ein Backend-Service, der Redirect-URLs erstellen kann

Implementierung

1. Privaten Schlüssel erzeugen.

   1. Gehen Sie in Ihrem Dashboard zu Authentication.
   2. Wählen Sie Personalization.
   3. Wählen Sie JWT.
   4. Geben Sie die URL Ihres bestehenden Login-Flows ein und wählen Sie Save changes.
   5. Wählen Sie Generate new key.
   6. Speichern Sie Ihren Schlüssel sicher an einem Ort, auf den Ihr Backend zugreifen kann.
2. Mintlify-Personalisierung in Ihren Login-Flow integrieren.

   Passen Sie Ihren bestehenden Login-Flow an und fügen Sie nach dem Login diese Schritte hinzu:

   • Erstellen Sie ein JWT mit den Informationen des angemeldeten Benutzers im User-Format. Weitere Informationen finden Sie im Abschnitt User data format oben.
   • Signieren Sie das JWT mit dem Secret Key unter Verwendung des ES256-Algorithmus.
   • Erstellen Sie eine Redirect-URL zurück zu Ihren Docs und fügen Sie das JWT als Hash an.

Beispiel

Ihre Dokumentation wird unter docs.foo.com gehostet. Sie möchten Ihre Docs vom Dashboard trennen (oder haben kein Dashboard) und die Personalisierung aktivieren.

Erzeugen Sie ein JWT-Secret. Erstellen Sie anschließend einen Login-Endpunkt unter https://foo.com/docs-login, der einen Login-Flow zu Ihrer Dokumentation startet.

Nach der Verifizierung der Benutzeranmeldedaten:

• Erzeugen Sie ein JWT mit Benutzerdaten im Mintlify-Format.
• Signieren Sie das JWT und leiten Sie weiter zu 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}`);
}

Seitenanker beibehalten

Um Benutzer nach dem Login zu bestimmten Abschnitten weiterzuleiten, verwenden Sie dieses URL-Format: https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}.

Beispiel:

• Ursprüngliche URL: https://docs.foo.com/quickstart#step-one
• Weiterleitungs-URL: https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one