The Get Variation Name API を使用すると、特定のフルスタック A/B 実験について、実験を再評価・再アクティブ化することなく、ユーザーに割り当てられているバリエーションを取得できます。

この API は、次のような場合に便利です。

• すでに割り当てられているバリエーションを取得したい場合

• ユーザーフローの後続ステップで、バリエーションごとのロジックを適用したい場合

• 複数の画面や処理間で一貫した動作を保証したい場合
  

この API でできること  

この API を使用すると、次のことができます。

• ユーザーにすでに割り当てられているバリエーションを取得する

• 実験アクティベーション呼び出しの重複を回避する

• アプリ内の異なる箇所で一貫した動作を適用する

• 実験に含まれていないユーザーを安全に処理する

Get Variation Name を使用するタイミング  

次のような場合に、この API を使用してください。

• そのユーザーに対して、すでに実験がアクティブ化されている

• 割り当てられたバリエーションを再度確認したい

• 初回のアクティベーションフロー以外の場所で、バリエーション情報が必要である

実験がこれまでにアクティブ化されていない場合、この API は null を返すことがあります。

ユーザー属性を指定してバリエーション名を取得する  

オーディエンス条件を正しく評価するために、バリエーション名を取得する際にユーザー属性を渡すことができます。

KOTLIN

1. // ユーザー属性を保持するマップを作成
2. val userAttributes = mutableMapOf(
3. 'DeviceType'to'電話番号',
4. 'OS' to 'Android',
5. 'OSVersion'to '14',
6. 'DeviceModel'to'Pixel 8 Pro'
7. )
8. // ユーザーのバリエーション名を取得
9. val variationName = pageSenseClient。getVariationName(
10. experimentName,
11. userId,
12. userAttributes
13. )
14. // バリエーションごとのロジックを処理
15. if (variationName == '元の内容') {
16. // 元の内容バリエーションを処理
17. } else if (variationName == 'Variation 1') {
18. // Variation 1 を処理
19. } else if (variationName == 'Variation 2') {
20. // Variation 2 を処理
21. } else if (variationName == 'Variation 3') {
22. // Variation 3 を処理
23. } else {
24. // ユーザーは実験の対象外
    }

JAVA

1. import java.util.HashMap;
2. // ユーザー属性を保持するマップを作成
3. HashMap<String, String> userAttributes = new HashMap<>();
4. userAttributes.put('DeviceType', '電話番号');
5. userAttributes.put('OS', 'Android');
6. userAttributes.put('OSVersion', '14');
7. userAttributes.put('DeviceModel', 'Pixel 8 Pro');
8. // ユーザーのバリエーション名を取得
9. String variationName = pageSenseClient.getVariationName(
10. experimentName,
11. userId,
12. userAttributes
13. );
14. // バリエーションごとのロジックを処理
15. if ('元の内容'.equals(variationName)) {
16. // 元の内容バリエーションを処理
17. } else if ('Variation 1'.equals(variationName)) {
18. // Variation 1 を処理
19. } else if ('Variation 2'.equals(variationName)) {
20. // Variation 2 を処理
21. } else if ('Variation 3'.equals(variationName)) {
22. // Variation 3 を処理
23. } else {
24. // ユーザーが実験のいずれのバリエーションにも属していない場合の処理
25. }

パラメーター	種類	必須	説明
experimentName	String	はい	PageSense で設定したフルスタック実験の名前。
userId	String	はい	ユーザーを一意に識別する安定した ID。セッションをまたいで一貫している必要があります。
userAttributes	Map<String, String>	いいえ	オーディエンスのターゲティングやセグメントに使用する任意のユーザー属性。

  

activateExperiment() と getVariationName() を使い分けるタイミング

利用シーン	推奨メソッド
初回の評価時	activateExperiment
すでに割り当てられたバリエーションを取得する場合	getVariationName

 

ユーザー属性なしでバリエーション名を取得する  

ユーザー属性が利用できない場合は、実験名とユーザー ID のみを使用してバリエーションを取得できます。
この場合、ターゲットをすべての訪問者に設定している実験のみが対象になります。

1. // ユーザー属性なしでバリエーション名を取得する
2. val variationName = pageSenseClient。getVariationName(
3. experimentName,
4. userId
5. )

API の動作  

activateExperiment() メソッドが呼び出されると、ユーザーにどのバリエーションを割り当てるかを判断するために、次の手順で処理を行います。

1. オーディエンスターゲティング

• ユーザーの属性がオーディエンスターゲティング条件と一致する場合、評価を続行します。

• 一致しない場合、API は直ちに null を返し、そのユーザーが実験の対象外であることを示します。
  
  

2. ユーザーストレージサービス

• 指定されたユーザー ID に対して、実験用のバリエーションがすでに保存されている場合は、そのバリエーションをストレージから取得して返します。

• 保存されていない場合、SDK はハッシュアルゴリズムを使用して新しいバリエーションを割り当てます。
  
  

3. MurmurHash によるハッシュ化

このハッシュ値によって、ユーザーが実験のトラフィック配分範囲内のどの位置に属するかが決まり、その位置に応じてバリエーションが割り当てられます。

• MurmurHash は、同じユーザー ID と実験キーの組み合わせに対して、常に同じハッシュ値を生成します。

• これにより、ユーザーはセッションやブラウザーが異なっても、常に同じバリエーションが一貫して割り当てられます。

4. バリエーションのマッピング

バリエーション	値の範囲
元の内容	0 – 2000
バリエーション 1	2001 – 4000
バリエーション 2	4001 – 6000
バリエーション 3	6001 – 8000

 これらの範囲は互いに重複せず、実験に割り当てられたトラフィックの合計をすべてカバーします。

• ユーザーのハッシュ値が特定のバリエーションの範囲内に入る場合、そのバリエーションがユーザーに割り当てられます。

• ユーザーのハッシュ値が、いずれのバリエーションにも割り当てられている範囲外の場合は、ユーザーにはバリエーションが割り当てられず、そのユーザーは実験の対象外となり、バリエーションとしては NULL が返されます。
  

5. トラッキングと分析

6. 返される値  

結果	返される値
ユーザーが条件を満たし、バリエーションが割り当てられた場合	バリエーション名を返します
ユーザーがオーディエンスターゲティングルールに一致しない場合	NULL を返します
ユーザーがトラフィック配分の範囲外にある場合	NULL を返します

重要なメモ  

• この API は実験をアクティブ化しません。

• この API は、すでにユーザーに割り当てられているバリエーションのみを返します。

• ユーザーが条件を満たしていない場合、または実験が一度もアクティブ化されていない場合は、null が返されます。

• 常に null が返されるケースを安全に処理してください。

ベストプラクティス  

• 実験はユーザーセッションごとに 1 回だけアクティブ化します。

• 以降の判定には getVariationName を使用します。

• 結果を一貫させるため、安定したユーザー識別子を使用します。

• ユーザー属性は、利用可能な場合にのみ渡してください。