Experiment Center と Auth0 ACUL の連携

Auth0 Custom Universal Login（ACUL）のスクリーンで実験のコンテキストを読み取り、バリエーションに応じてレンダリングを切り替える方法。

エクスペリメントが有効でバリエーションが割り当てられると、Experiment Center は割り当てられたバリエーションを experiment として Advanced Customizations for Universal Login (ACUL) スクリーンのコンテキストに追加します。このデータには ACUL JS SDK または ACUL React SDK でアクセスできます。

実験のコンテキストが配信されるのは、オプトインしたスクリーンだけです。オプトインはスクリーンごとに行い、そのスクリーンの context_configuration 配列に "experiment" を追加します。

スクリーンが実験のコンテキストを受け取るようにオプトインするには、リクエスト本文に以下を含めて PATCH /v2/prompts/{prompt}/screen/{screen}/rendering エンドポイントを呼び出します。

Example

{
    "context_configuration": ["experiment"]
}

{prompt} は prompt 名 (例: login) に、{screen} はスクリーン名 (例: login) に置き換えてください。

エクスペリメントの判定とテナントログの拡充は、スクリーンがオプトインしているかどうかにかかわらず、常に実行されます。オプトインで制御されるのは、experiment プロパティが ACUL コンポーネントに渡されるかどうかだけです。これはデータ最小化のための措置です。実験のコンテキストを必要としないスクリーンはオプトインしないでください。

​

ACUL SDKで実験のコンテキストにアクセスする

実験のコンテキストには、ACUL JS SDK (@auth0/auth0-acul-js) またはACUL React SDK (@auth0/auth0-acul-react) のバージョン1.9.0以降でアクセスできます。

ACULスクリーンの構築方法に応じて、対応するSDKを使用してください。

React SDK

useExperiment() Hooksを使用します。このHooksは、@auth0/auth0-acul-reactのすべてのスクリーンのエントリーポイントから利用できます。

import { useExperiment } from '@auth0/auth0-acul-react/login';

const experiment = useExperiment();

JS SDK

@auth0/auth0-acul-jsの任意のスクリーンインスタンスからexperimentプロパティを読み取ります。

import Login from '@auth0/auth0-acul-js/login';

const experiment = new Login().experiment;

アクティブなエクスペリメントがない場合や、スクリーンがオプトインしていない場合、SDKはnullを返します。

​

実験のコンテキストの構造

実験のコンテキストの構造は次のとおりです:

interface ExperimentMembers {
    experimentId: string;                 // アクティブな実験ID
    variationId: string;                  // 割り当てられたバリエーションID
    variationName: string | null;         // 割り当てられたバリエーションの名前
    variationDescription: string | null;  // 割り当てられたバリエーションの説明
    config: {                             // マージされた設定: ベースライン + オーバーライド
        [paramName: string]: unknown;     // 各エントリは { value } オブジェクトです
    };
    isControl: boolean;                   // コントロールバリエーションの場合はtrue
}

ACUL SDK は、variationName と variationDescription が定義されていない場合はそれらを null に設定し、サーバーが設定を送信しない場合は config を空のオブジェクト ({}) に設定します。

config プロパティには、割り当てられたバリエーションに対するマージ済みの設定が含まれます。Experiment Center は、機能フラグのベースラインパラメーターを取得し、その上に割り当てられたバリエーションのオーバーライドをマージします。サーバーが設定を送信する場合、機能フラグで定義されたすべてのパラメーターは config 内に値を持ちます。

たとえば、機能フラグにベースライン値が "Sign in" の button_label パラメーターがあり、割り当てられたバリエーションでそれが "Continue" にオーバーライドされている場合、config.button_label.value は "Continue" になります。 コントロールバリエーションの場合 (オーバーライドなし) 、config.button_label.value は "Sign in" です。

​

パラメーター値を読み取る

config の各エントリは、解決済みの値をラップしたオブジェクトです (例: { value: "Continue" }) 。解決済みの値は config[paramName].value から読み取ります。

const label = experiment?.config?.button_label?.value;

エントリ自体を真偽判定するのではなく、必ず .value を読み取ってください。解決された値が false の場合でも、ラッパーオブジェクト自体は常に truthy と評価されます。

// 誤り: { value: false } も truthy なオブジェクトなので、この分岐は常に実行されます。
if (experiment?.config?.show_passkey_banner) { /* ... */ }

// 正解: 解決された値を読み取ります。
if (experiment?.config?.show_passkey_banner?.value === true) { /* ... */ }

ACUL SDKでは、パラメーターの型はエクスペリメントごとに定義されるため、config の値は unknown 型になっています。TypeScriptでは、エントリーを読み取る前に型の絞り込みを行ってください：

const entry = experiment?.config?.show_passkey_banner as { value?: boolean } | undefined;
const showBanner = entry?.value ?? false;

オプショナルチェーン (?.) は常に使用してください。アクティブなエクスペリメントがない場合、experiment プロパティは null になります。

​

isControl の使用

ユーザーがコントロールグループに属している場合、isControl プロパティは true になります (ベースラインが配信され、オーバーライドは適用されません) 。変更のない体験をどのユーザーが見たかを追跡したい場合や、コントロールユーザーに対する任意の処理をスキップしたい場合に使用します。

if (experiment && !experiment.isControl) {
    // トリートメントユーザーにのみ実行される
    trackExperimentImpression(experiment.experimentId, experiment.variationId);
}

isControl を確認する前に、experiment が存在することを確認してください。アクティブなエクスペリメントがない場合、!experiment?.isControl は true と評価されるため、エクスペリメントに参加していないユーザーに対してトリートメント側の分岐が実行されてしまいます。

分岐レンダリングでは、isControl ではなくパラメーター値 (config.my_param.value) を直接確認してください。 パラメーターに基づくチェックのほうが読みやすく、将来のエクスペリメントでどのバリエーションを統計上の対照群にするかを変更しても正しく機能します。

​

例: 文言バリアントのエクスペリメント

この例では、ボタンの文言を切り替える2つのバリエーションを持つ機能フラグを紹介します。コントロールバリエーションでは標準のラベルを、トリートメントバリエーションでは別のラベルを使用します。

機能フラグのパラメーター:

{
    "button_label": {
        "type": "string",
        "value": "Sign in",
        "description": "Label for the primary login button"
    }
}

コントロールバリエーション： オーバーライドなし (button_label: "Sign in" を継承)

トリートメントバリエーション：

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

パラメーターを読み取るACULコンポーネント：

// 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>
    );
}

?? "Sign in" のフォールバックは、有効なエクスペリメントがない場合(このとき experiment は null、entry は undefined になります)に対処するためのものです。必要であれば、別途 null チェックを行うこともできます:

const buttonLabel = experiment
    ? (experiment.config.button_label as { value: string }).value
    : "Sign in"; // アクティブなエクスペリメントがない場合はデフォルトを使用

​

例: ブール値による機能の段階的ロールアウト

この例では、ブール値のパラメーターを使って、新しいUI要素を条件付きで表示します。

// 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>
            {/* 既存のログインフォーム */}
            {showPasskeyBanner && (
                <div className="banner">
                    <p>Set up a passkey for faster sign-in next time.</p>
                </div>
            )}
        </div>
    );
}

=== true でチェックしているのは (truthy チェックではなく) 意図的です。これにより、experiment が null の場合や config が空の場合ではなく、パラメーターが明示的に true のときにのみバナーが表示されます。

​

例: JS SDK でのコントロールとトリートメント

この例では JS SDK を使用して、エクスペリメントに割り当てられていないユーザーとコントロールグループのユーザーにはデフォルトのエクスペリエンスを表示し、パラメーターが true に resolve された場合にのみトリートメントのエクスペリエンスを表示します。

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() と renderTreatmentLoginUI() は、ご自身で実装するレンダリング関数です。エクスペリメントのバリエーションが3つ以上ある場合は、experiment.variationId で分岐させることもできます。

​

トラブルシューティング

experiment プロパティは、次の3つの状況で null になります。

1. テナントで現在アクティブなエクスペリメントがない。
2. スクリーンが context_configuration でオプトインしていない。
3. テナントで Experiment Center が有効になっていない。

experiment は存在するものの config が空 ({}) の場合は、そのバリエーションの設定がサーバーから送信されていません。スクリーンが問題なくレンダリングされるよう、オプショナルチェーンとデフォルト値を使ってパラメーターを読み取ってください。

experiment は常に null になり得るものとして扱ってください。最も安全なパターンは次のとおりです。

const experiment = useExperiment(); // または new Login().experiment
const entry = experiment?.config?.my_param as { value?: string } | undefined;
const myParam = entry?.value ?? "your-default";

experiment プロパティが常に存在するとは限りません。experiment が定義されていることを前提としたコードは、エクスペリメントが実行されていないときにエラーをスローします。