Cookies

Transmettez les données des visiteurs à votre documentation via un cookie public ou signé

Rendez-vous dans nos guides pour trouver un guide complet sur la configuration de contenu adaptatif avec des cookies.

L’utilisation de contenu adaptatif avec des drapeaux de fonctionnalités nécessite d’ajouter du code à votre application.

Cette méthode ne fonctionne que si votre site est servi sous un domaine personnalisé.

Vous pouvez transmettre des données de visiteur à votre documentation via les cookies du navigateur de vos visiteurs. Voici un aperçu des différentes méthodes.

Méthode	Cas d’utilisation	Facilité de configuration	Sécurité	Format
Cookie signé gitbook-visitor-token	Identifiants de test de l’API, identification du client	Nécessite une signature et un domaine personnalisé	✅ Les propriétés ne peuvent être définies que par le backend	JWT
Cookie public gitbook-visitor-public	Drapeaux de fonctionnalités, rôles	Facile à configurer	❌ Le visiteur peut remplacer les propriétés	JSON

Cookie public

Pour transmettre des données à GitBook à partir d’un cookie public, vous devrez envoyer les données depuis votre application en définissant un cookie public gitbook-visitor-public cookie.

Voici un simple exemple en 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',
})

Les données transmises via des cookies publics doivent être définies dans votre schéma de visiteur via un non signé objet.

Cookie signé

Pour transmettre des données à GitBook de manière plus sécurisée, vous devrez envoyer les données sous la forme d’un JSON Web Token depuis votre application dans un cookie nommé gitbook-visitor-token rattaché à votre domaine.

Pour configurer cela, vous devrez adapter le flux de connexion de votre application pour inclure les étapes suivantes :

1

Générer un JWT lorsque les utilisateurs se connectent à votre application

Chaque fois qu’un utilisateur se connecte à votre produit, générez un JWT contenant certains attributs des informations de votre utilisateur authentifié.

2

Signer le JWT à l’aide de la clé de signature des visiteurs du site

Ensuite, veillez à signer le JWT à l’aide de la clé de signature des visiteursdu site, que vous pouvez trouver dans les paramètres d’audience de votre site après avoir activé le contenu adaptatif.

3

Stocker le JWT dans un cookie de session générique

Enfin, vous devez stocker le JWT signé contenant les informations de votre utilisateur dans un cookie de session générique sous le domaine de votre produit.

Par exemple, si votre application est servie derrière le app.acme.org domaine, le cookie devra être créé sous le .acme.org domaine générique.

Voici un simple exemple en 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) {
   // Votre logique métier pour gérer la requête de connexion
   // Par exemple, vérifier les identifiants et authentifier l’utilisateur
   //
   // par ex. :
   // const loggedInUser = await authenticateUser(req.body.username, req.body.password);

   // Après avoir authentifié l’utilisateur, récupérez les informations utilisateur que vous souhaitez
   // transmettre à GitBook depuis votre base de données ou votre service utilisateur.
   const userInfo = await getUserInfo(loggedInUser.id);
      
   // Construisez la charge utile JWT avec les informations de l’utilisateur
   const gitbookVisitorClaims = {
       firstName: userInfo.firstName,
       lastName: userInfo.lastName,
       isBetaUser: userInfo.isBetaUser
       products: userInfo.products.map((product) => product.name),
       featureFlags: await getFeatureFlags({userId: loggedInUser.id})
   }
   
   // Générer un JWT signé à l’aide des revendications
   const gitbookVisitorJWT = await new jose.SignJWT(gitbookVisitorClaims)
     .setProtectedHeader({ alg: 'HS256' })
     .setIssuedAt()
     .setExpirationTime('2h') // expiration arbitraire de 2 heures
     .sign(GITBOOK_VISITOR_SIGNING_KEY);
     
  // Inclure un cookie `gitbook-visitor-token` contenant le JWT encodé dans votre
  // réponse du gestionnaire de connexion
  res.cookie(GITBOOK_VISITOR_COOKIE_NAME, gitbookVisitorJWT, {
     httpOnly: true,
     secure: process.env.NODE_ENV === 'production',
     maxAge: 2 * 60 * 60 * 1000, // expiration arbitraire de 2 heures
     domain: '.acme.org' //
  });
  
  // Reste de la logique de votre gestionnaire de connexion, y compris la redirection de l’utilisateur vers votre application
  res.redirect('/'); // Exemple de redirection
}