La personalizzazione adatta la documentazione a ciascun utente quando è connesso. Ad esempio, puoi precompilare le loro chiavi API, mostrare contenuti specifici per il loro piano o ruolo oppure nascondere sezioni a cui non devono accedere.

​
Funzionalità di personalizzazione

Personalizza i contenuti con queste capacità di personalizzazione.

​
Precompilazione della chiave API

Compila automaticamente i campi dell’API playground con valori specifici per l’utente restituendo, nei dati utente, nomi di campo che corrispondano. I nomi dei campi nei dati utente devono corrispondere esattamente ai nomi presenti nell’API playground affinché la precompilazione automatica funzioni.

​
Contenuti MDX dinamici

Mostra contenuti dinamici in base alle informazioni dell’utente, come nome, piano o organizzazione, utilizzando la variabile user. 
Welcome back, {user.firstName}! Your {user.org?.plan} plan includes...
Vedi la sezione Formato dei dati utente qui sotto per esempi dettagliati e indicazioni di implementazione.

​
Visibilità delle pagine

Limita quali pagine sono visibili ai tuoi utenti aggiungendo il campo groups al frontmatter delle pagine. Per impostazione predefinita, ogni pagina è visibile a qualsiasi utente. Gli utenti vedranno solo le pagine dei groups a cui appartengono. 
---
title: "Managing your users"
description: "Adding and removing users from your organization"
groups: ["admin"]
---

​
Formato dei dati utente

Quando implementi la personalizzazione, il tuo sistema restituisce i dati utente in un formato specifico che abilita la personalizzazione dei contenuti. Questi dati possono essere inviati come oggetto JSON grezzo o all’interno di un JWT firmato, a seconda del metodo di handshake. La struttura dei dati è la stessa in entrambi i casi. 
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
Orario di scadenza della sessione in secondi dall’epoch. Se l’utente carica una pagina dopo questo momento, i suoi dati memorizzati vengono eliminati automaticamente e deve riautenticarsi.
Per gli handshake JWT: Questo campo è diverso dalla claim exp del JWT, che determina quando un JWT è considerato non valido. Imposta la claim exp del JWT su una durata breve (10 secondi o meno) per motivi di sicurezza. Usa expiresAt per la durata effettiva della sessione (da ore a settimane).
​
groups
string[]
Elenco dei gruppi a cui appartiene l’utente. Le pagine con groups corrispondenti nel frontmatter sono visibili a questo utente.Esempio: Un utente con groups: ["admin", "engineering"] può accedere alle pagine etichettate con il gruppo admin o engineering.
​
content
object
Dati personalizzati accessibili nel contenuto MDX tramite la variabile user. Usali per la personalizzazione dinamica in tutta la documentazione.Esempio di base:
{ "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" }
Utilizzo in MDX:
Welcome back, {user.firstName}! Your {user.plan} plan includes...
Con i dati di user dell’esempio, il risultato sarà: Bentornato, Ronan! Il tuo piano Enterprise include…Rendering condizionale avanzato:
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.</>
}
Le informazioni in user sono disponibili solo per gli utenti autenticati. Per gli utenti non autenticati, il valore di user sarà {}. Per evitare errori di runtime per gli utenti non autenticati, utilizza sempre l’optional chaining sui campi di user. Ad esempio, {user.org?.plan}.
​
apiPlaygroundInputs
object
Valori specifici dell’utente che precompilano i campi dell’API playground. Fanno risparmiare tempo popolando automaticamente i dati dell’utente durante il test delle API.Esempio:
{
  "header": { "X-API-Key": "user_api_key_123" },
  "server": { "subdomain": "foo" },
  "query": { "org_id": "12345" }
}
Se un utente effettua richieste da un sottodominio specifico, puoi inviare { server: { subdomain: 'foo' } } come campo apiPlaygroundInputs. Questo valore verrà precompilato in qualsiasi pagina API che utilizza il valore subdomain.
I campi header, query e cookie verranno precompilati solo se fanno parte dello schema di sicurezza OpenAPI. Se un campo è nelle sezioni Authorization o Server, verrà precompilato. Creare un parametro header standard chiamato Authorization non abilita questa funzionalità.

​
Esempio di dati utente

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

​
Configurazione della personalizzazione

Seleziona il metodo di handshake che desideri configurare.

​
Prerequisiti

  • Un sistema di login in grado di generare e firmare JWT
  • Un servizio backend in grado di creare URL di reindirizzamento

​
Implementazione

1

Genera una chiave privata.

  1. Nel tuo dashboard, vai su Authentication.
  2. Seleziona Personalization.
  3. Seleziona JWT.
  4. Inserisci l’URL del flusso di login esistente e seleziona Save changes.
  5. Seleziona Generate new key.
  6. Conserva la chiave in modo sicuro, in un luogo accessibile dal tuo backend.
2

Integra la personalizzazione di Mintlify nel tuo flusso di login.

Modifica il flusso di login esistente per includere questi passaggi dopo l’accesso dell’utente:
  • Crea un JWT contenente le informazioni dell’utente autenticato nel formato User. Consulta la sezione User data format per maggiori informazioni.
  • Firma il JWT con la chiave segreta, utilizzando l’algoritmo ES256.
  • Crea un URL di reindirizzamento alla tua documentazione, includendo il JWT come hash.

​
Esempio

La tua documentazione è ospitata su docs.foo.com. Vuoi tenerla separata dal tuo dashboard (o non hai un dashboard) e abilitare la personalizzazione.Genera un secret per i JWT. Quindi crea un endpoint di login su https://foo.com/docs-login che avvii un flusso di login verso la documentazione.Dopo aver verificato le credenziali dell’utente:
  • Genera un JWT con i dati utente nel formato di Mintlify.
  • Firma il JWT e reindirizza a 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}`);
}

​
Conservare gli anchor di pagina

Per reindirizzare gli utenti a sezioni specifiche dopo il login, usa questo formato di URL: https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}.Esempio:
  • URL originale: https://docs.foo.com/quickstart#step-one
  • URL di reindirizzamento: https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one