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.

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) sous le nom d’experiment. Vous pouvez y accéder avec la trousse SDK ACUL JS ou la trousse SDK ACUL React.

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 en incluant les éléments suivants dans le corps de la requête :

Example

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

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.

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 présente la structure suivante :

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 :

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 :

// 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 :

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.

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 :

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

{
    "overrides": {
        "button_label": { "value": "Continue to your account" }
    }
}

Composant ACUL qui lit le paramètre :

// 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 (
        <div>
            <h1>Welcome back</h1>
            <form>
                <input type="email" name="email" placeholder="Email" />
                <input type="password" name="password" placeholder="Password" />
                <button type="submit">{buttonLabel}</button>
            </form>
        </div>
    );
}

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 :

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.

// 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 (
        <div>
            {/* Votre formulaire de connexion existant */}
            {showPasskeyBanner && (
                <div className="banner">
                    <p>Set up a passkey for faster sign-in next time.</p>
                </div>
            )}
        </div>
    );
}

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.

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 :

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.