> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Experiment Center et l’intégration d’Auth0 à ACUL
> Comment lire le contexte de l’expérience dans les écrans d’Auth0 Custom Universal Login (ACUL) et ajuster le rendu selon la variation.
> [!WARNING]
>
> **La fonctionnalité Auth0 Experiment Center est en .**
Lorsqu’une expérimentation est active et qu’une variation est attribuée, Experiment Center ajoute la variation attribuée au contexte de votre écran [Advanced Customizations for Universal Login (ACUL)](https://auth0.com/docs/fr-ca/customize/login-pages/advanced-customizations.md) sous le nom d’`experiment`. Vous pouvez y accéder avec la [trousse SDK ACUL JS](https://auth0.com/docs/fr-ca/libraries/acul/js-sdk.md) ou la [trousse SDK ACUL React](https://auth0.com/docs/fr-ca/libraries/acul/react-sdk.md).
Le contexte de l’expérience est transmis uniquement aux écrans pour lesquels vous avez activé cette option. Vous l’activez écran par écran en ajoutant `"experiment"` au tableau `context_configuration` de cet écran.
Pour qu’un écran reçoive le contexte de l’expérience, effectuez un appel au [terminal `PATCH /v2/prompts/{prompt}/screen/{screen}/rendering`](https://auth0.com/docs/fr-ca/api/management/v2/prompts/patch-rendering) en incluant les éléments suivants dans le corps de la requête :
```json Example wrap lines theme={null}
{
"context_configuration": ["experiment"]
}
```
Remplacez `{prompt}` par le nom du prompt (par exemple, `login`) et `{screen}` par le nom de l’écran (par exemple, `login`).
La résolution de l’expérimentation et l’enrichissement du journal du locataire s’exécutent toujours, qu’un écran ait fait l’objet d’une activation explicite ou non. L’activation explicite détermine uniquement si les propriétés `experiment` sont transmises à votre composant ACUL. Il s’agit d’une mesure de minimisation des données : n’activez pas explicitement les écrans qui n’ont pas besoin du contexte de l’expérience.
## Accéder au contexte de l’expérimentation avec les SDK ACUL
Vous pouvez accéder au contexte de l’expérimentation avec la version 1.9.0 ou une version ultérieure du SDK JS ACUL (`@auth0/auth0-acul-js`) ou du SDK React ACUL (`@auth0/auth0-acul-react`).
Utilisez le SDK qui correspond à votre façon de créer vos écrans ACUL :
**SDK React**
Utilisez le hook `useExperiment()`, disponible dans chaque point d’entrée d’écran de `@auth0/auth0-acul-react`.
```tsx wrap lines theme={null}
import { useExperiment } from '@auth0/auth0-acul-react/login';
const experiment = useExperiment();
```
**SDK JS**
Lisez la propriété `experiment` de n’importe quelle instance d’écran de `@auth0/auth0-acul-js`.
```typescript wrap lines theme={null}
import Login from '@auth0/auth0-acul-js/login';
const experiment = new Login().experiment;
```
Les SDK renvoient `null` lorsqu’aucune expérimentation n’est active ou que l’écran n’a pas été configuré pour y participer.
## La structure du contexte de l’expérience
Le [contexte de l’expérience](https://auth0.com/docs/fr-ca/libraries/acul/js-sdk/Screens/interfaces/ExperimentMembers) présente la structure suivante :
```typescript wrap lines theme={null}
interface ExperimentMembers {
experimentId: string; // L'ID d'expérience actif
variationId: string; // L'ID de variation attribué
variationName: string | null; // Le nom de la variation attribuée
variationDescription: string | null; // La description de la variation attribuée
config: { // Configuration fusionnée : baseline + overrides
[paramName: string]: unknown; // Chaque entrée est un objet { value }
};
isControl: boolean; // True lorsqu'il s'agit de la variation témoin
}
```
Les SDK ACUL attribuent la valeur `null` à `variationName` et à `variationDescription` lorsque celles-ci ne sont pas définies, et attribuent un objet vide (`{}`) à `config` lorsque le serveur n’envoie pas de configuration.
La propriété `config` contient la configuration fusionnée pour la variation attribuée. Experiment Center prend les paramètres de référence du feature flag et y fusionne les valeurs de remplacement de la variation attribuée. Lorsque le serveur envoie une configuration, chaque paramètre défini dans le feature flag a une valeur dans `config`.
Par exemple, si votre feature flag a un paramètre `button_label` avec une valeur de référence de `"Sign in"` et que la variation attribuée la remplace par `"Continue"`, alors `config.button_label.value` est `"Continue"`.
Pour la variante témoin (sans valeurs de remplacement), `config.button_label.value` est `"Sign in"`.
## Lire la valeur d'un paramètre
Chaque entrée de `config` est un objet qui encapsule la valeur résolue, par exemple `{ value: "Continue" }`. Récupérez la valeur résolue dans `config[paramName].value` :
```typescript wrap lines theme={null}
const label = experiment?.config?.button_label?.value;
```
Lisez toujours `.value` plutôt que de tester l'entrée elle-même. L'objet enveloppe est toujours évalué comme vrai, même si la valeur résolue est `false` :
```typescript wrap lines theme={null}
// Incorrect : { value: false } reste un objet évalué comme vrai; cette branche s'exécute donc toujours.
if (experiment?.config?.show_passkey_banner) { /* ... */ }
// Correct : lisez la valeur résolue.
if (experiment?.config?.show_passkey_banner?.value === true) { /* ... */ }
```
Dans les SDK ACUL, les valeurs `config` sont typées `unknown`, car les types de paramètres sont définis pour chaque expérimentation. En TypeScript, restreignez le type de l'entrée avant d'en faire la lecture :
```typescript wrap lines theme={null}
const entry = experiment?.config?.show_passkey_banner as { value?: boolean } | undefined;
const showBanner = entry?.value ?? false;
```
Utilisez systématiquement le chaînage optionnel (`?.`). La propriété `experiment` vaut `null` lorsqu'aucune expérimentation n'est active.
## Utiliser isControl
La propriété `isControl` est `true` lorsque l’utilisateur fait partie du groupe témoin (il a reçu la version de référence, sans aucunes valeurs de remplacement appliquées). Utilisez-la lorsque vous devez repérer les utilisateurs qui ont vu l’expérience non modifiée, ou si vous voulez ignorer le traitement optionnel pour les utilisateurs du groupe témoin.
```typescript wrap lines theme={null}
if (experiment && !experiment.isControl) {
// S'exécute uniquement pour les utilisateurs du traitement
trackExperimentImpression(experiment.experimentId, experiment.variationId);
}
```
Vérifiez que `experiment` existe avant de vérifier `isControl`. Lorsqu’aucune expérimentation n’est active, `!experiment?.isControl` est évalué à `true`, ce qui exécute la branche de traitement pour les utilisateurs qui ne font partie d’aucune expérimentation.
Pour le rendu conditionnel, vérifiez directement la valeur du paramètre (`config.my_param.value`) plutôt que `isControl`.
Les vérifications fondées sur les paramètres sont plus faciles à lire et fonctionnent correctement, même si vous changez plus tard la variation utilisée comme contrôle statistique dans une autre expérimentation.
## Exemple : expérimentation sur des variantes de texte
Cet exemple présente un Feature flag comportant deux variations qui modifient le texte d'un bouton. La variante témoin utilise l'étiquette standard, tandis que la variation de traitement utilise une étiquette différente.
**Paramètres du Feature flag :**
```json wrap lines theme={null}
{
"button_label": {
"type": "string",
"value": "Sign in",
"description": "Label for the primary login button"
}
}
```
**Variante témoin :** aucune valeur de remplacement (hérite de `button_label: "Sign in"`)
**Variation de traitement :**
```json wrap lines theme={null}
{
"overrides": {
"button_label": { "value": "Continue to your account" }
}
}
```
**Composant ACUL qui lit le paramètre :**
```tsx wrap lines theme={null}
// LoginScreen.tsx
import { useExperiment } from '@auth0/auth0-acul-react/login';
export default function LoginScreen() {
const experiment = useExperiment();
const entry = experiment?.config?.button_label as { value?: string } | undefined;
const buttonLabel = entry?.value ?? "Sign in";
return (
Welcome back
);
}
```
La valeur de repli `?? "Sign in"` couvre le cas où aucune expérimentation n'est active (`experiment` vaut alors `null` et `entry` vaut `undefined`). Si vous le préférez, vous pouvez plutôt effectuer une vérification de nullité distincte :
```typescript wrap lines theme={null}
const buttonLabel = experiment
? (experiment.config.button_label as { value: string }).value
: "Sign in"; // Aucune expérimentation active; utiliser la valeur par défaut
```
## Exemple : déploiement progressif d’une fonctionnalité booléenne
Cet exemple utilise un paramètre booléen pour afficher ou non un nouvel élément de l’interface utilisateur.
```tsx wrap lines theme={null}
// LoginScreen.tsx
import { useExperiment } from '@auth0/auth0-acul-react/login';
export default function LoginScreen() {
const experiment = useExperiment();
const entry = experiment?.config?.show_passkey_banner as { value?: boolean } | undefined;
const showPasskeyBanner = entry?.value === true;
return (
{/* Votre formulaire de connexion existant */}
{showPasskeyBanner && (
Set up a passkey for faster sign-in next time.
)}
);
}
```
Le test `=== true` (plutôt qu’un simple test de vérité) est intentionnel : il garantit que la bannière ne s’affiche que lorsque le paramètre vaut explicitement `true`, et non lorsque `experiment` est `null` ou que `config` est vide.
## Exemple : groupe témoin et traitement dans le SDK JS
Cet exemple utilise le SDK JS pour afficher l'expérience par défaut aux utilisateurs qui ne font partie d'aucune expérimentation ou qui appartiennent au groupe témoin, et pour n'afficher l'expérience de traitement que lorsque le paramètre se résout à `true`.
```typescript wrap lines theme={null}
import Login from '@auth0/auth0-acul-js/login';
const experiment = new Login().experiment;
if (!experiment || experiment.isControl) {
renderDefaultLoginUI();
} else {
const entry = experiment.config?.show_passkey as { value?: boolean } | undefined;
if (entry?.value) {
renderTreatmentLoginUI();
} else {
renderDefaultLoginUI();
}
}
```
`renderDefaultLoginUI()` et `renderTreatmentLoginUI()` sont vos propres fonctions de rendu. Lorsqu'une expérimentation comporte plus de deux variations, vous pouvez aussi créer des branches conditionnelles en fonction de `experiment.variationId`.
## Dépannage
La propriété `experiment` est `null` dans trois situations :
1. Aucune expérimentation n’est actuellement active pour le locataire.
2. L’écran n’a pas été activé au moyen de `context_configuration`.
3. Experiment Center n’est pas activé pour le locataire.
Si `experiment` est présent, mais que `config` est vide (`{}`), le serveur n'a envoyé aucune configuration pour la variation. Lisez les paramètres avec le chaînage optionnel et une valeur par défaut pour que votre écran s’affiche quand même.
Partez toujours du principe que `experiment` peut être `null`. Voici le modèle le plus sûr :
```typescript wrap lines theme={null}
const experiment = useExperiment(); // ou new Login().experiment
const entry = experiment?.config?.my_param as { value?: string } | undefined;
const myParam = entry?.value ?? "your-default";
```
Ne présumez jamais que la propriété `experiment` est présente. Tout code qui suppose que `experiment` est défini générera des erreurs lorsqu'aucune expérimentation n'est en cours.