Automation API を使用して実験結果を取得する

このチュートリアルでは、Automation API を使用して実験結果をリクエストし、勝者のバリエーションを判断する方法を説明します。これは、実験の作成、バリエーションの変更、ゴールとセグメントの関連付け、および実験の開始に関する以前のチュートリアルに続くものです。

要件

access_token

Automation API にはアクセストークンが必要です。アクセストークン取得セクションの手順に従って、プログラムでトークンを取得します。

experimentId

experimentId は、結果が必要な実験の数値識別子です。実験を表示している間に Kameleoon アプリの URL で見つけることができます（たとえば、https://app.kameleoon.com/.../experiments/188308/...）。フィーチャーフラグ実験の場合、ID は Rollout Planner に表示されます。

ゴール

このチュートリアルでは、以下の例の実験を使用します:

Product Page Redesign と呼ばれるこの実験には、オリジナルバージョンに加えて 2 つのバリエーション Redesign 1 (ID 828220) と Redesign 2 (ID 828221) が含まれます。この実験にはいくつかの目的がありますが、本チュートリアルではメインゴール（クリックトラッキング を通じて 保険の登録 を追跡）のみに焦点を当てます。

このチュートリアルはフィーチャーフラグ実験にも適用されます。ただし、https://api.kameleoon.com/experiments/* の代わりに https://api.kameleoon.com/feature-flags/* エンドポイントを使用してください:

experimentId は Rollout Planner にあります:

結果取得の仕組み

結果の取得は 2 段階のプロセスです:

結果をリクエストする — /experiments/{experimentId}/results に POST します。レスポンスは結果そのものではなく、dataCode ハッシュを返します。
結果をポーリングする — /results?dataCode=<dataCode> に GET リクエストを送信して、実際のデータを取得します。

ステップ 1 の 2 つのケースは、認証方法のみが異なります。アクセストークンで直接認証する（ケース 1）か、または認証されていないユーザーが結果を閲覧できる共有トークンを使用する（ケース 2）かです。

1. データコードを取得する

以下の主要なボディパラメータは、レポートに含める内容を制御します。パラメータの完全なリファレンスについては、Request experiment’s results エンドポイントを参照してください。

フィールド	型	説明
`goalsIds`	integer[]	含めるゴール。特定のゴールを指定するには `[goalId]` を渡し、すべてを除外するには `[]`、すべてを含めるには `null` を渡します。
`referenceVariationId`	string	他のバリエーションと比較する対象のバリエーション。オリジナルバリエーションには `"0"` を使用します。
`visitorData`	boolean	`true` はユニーク訪問者をカウントし、`false`（デフォルト）はすべての訪問をカウントします。
`sequentialTesting`	boolean	`true` にすると、信頼区間のための逐次検定が有効になります。
`conversionType`	string	信頼性計算に使用するカウント。`ALL_CONVERSION` は訪問者ごとにすべてのコンバージョンイベントをカウントします。`CONVERTED_VISITS` は、訪問中に何回コンバージョンイベントが発生したかに関係なく、各訪問を最大 1 回だけカウントします。

ケース 1: 結果を直接取得する

アクセストークンを使用して Request experiment’s results エンドポイントに POST リクエストを送信します。例:

curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
  "visitorData": false,
  "sequentialTesting": true,
  "referenceVariationId": "0",
  "goalsIds": [279599]
}'

レスポンス:

{"dataCode":"14443931880924098266207585267983330260134079899081739889989435434342588016765"}

この dataCode をステップ 2 に渡して、実際の結果を取得します。

ケース 2: 認可なしで結果を共有する

このアプローチは、アクセストークンなしでユーザーが結果を閲覧できるようにするために使用します。たとえば、ステークホルダーとライブ結果ビューを共有する場合などです。

1. SharedToken を取得する

Share experiment results エンドポイントから SharedToken を取得します。このエンドポイントは結果エンドポイントと同じリクエストボディを受け付けます。

curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results/share' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
  "visitorData": false,
  "sequentialTesting": true,
  "referenceVariationId": "0",
  "goalsIds": [279599]
}'

レスポンス:

{
    "method": "POST",
    "url": "https://api.kameleoon.com/experiments/188308/results",
    "path": "/experiments/188308/results",
    "headers": {
        "SharedToken": "eyJhbGciOiJIUzUxMiJ9.eyJleHAiOjE4NDQ5NDI5MTMsInNoYXJlZENvZGUiOiJhZmM1NzRjN2I4MjY4NTY3NzI2YjZhMDRhMTUxMjgyNjA3Zjk1ZGI4YjA1Y2RkZGY1ZDEwM2ExZDg5ZWM0MmZmIn0.oCECNm5mEhgIthc6eejo9BrfB7p8kEIrpoqtNb4JUiHK6nsxWHMvLc4hHYXCg3DgaBlVoKv6eEZHGty9c-VAoA",
        "Content-Type": "application/json"
    },
    "payload": {
        "visitorData": false,
        "sequentialTesting": true,
        "referenceVariationId": "0",
        "goalsIds": [279599]
    }
}

2. SharedToken を使って dataCode を取得する

前のレスポンスの SharedToken をアクセストークンの代わりに使用して、Request experiment’s results エンドポイントに POST リクエストを送信します。

curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'SharedToken: <SHARED_TOKEN>' \
--data-raw '{
  "visitorData": false,
  "sequentialTesting": true,
  "referenceVariationId": "0",
  "goalsIds": [279599]
}'

レスポンス:

{"dataCode":"14443931880924098266207585267983330260134079899081739889989435434342588016765"}

2. 実験結果を取得する

上記のいずれかのケースから dataCode を受け取った後、result エンドポイントを呼び出します。

curl -L -X GET 'https://api.kameleoon.com/results?dataCode=14443931880924098266207585267983330260134079899081739889989435434342588016765'

レスポンスが "status": "PENDING" を返す場合、レポートはまだ生成中です。ステータスが "READY" になるまで、少し待ってからリクエストを再試行してください。

レスポンス:

{
 "status": "READY",
 "data": {
  "dataCode": "14443931880924098266207585267983330260134079899081739889989435434342588016765",
  "variationData": {
   "_reference": {
    "breakdownData": {
     "_reference": {
      "intervalData": {},
      "generalData": {
       "visitCount": 126862,
       "visitorCount": 0,
       "goalsData": {
        "279599": {
         "conversionCount": 1898,
         "convertedVisitCount": 1898,
         "revenueCount": 235352.0,
         "convertedVisitorCount": 0,
         "revenuePerVisit": 1.86,
         "revenuePerVisitor": 0.0,
         "conversionRate": 0.014961138875313333,
         "averageCart": 124.0,
         "ratioValue": 0.0,
         "outlierBounds": {
          "lower": 0.1,
          "upper": 99.0
         }
        }
       }
      }
     }
    }
   },
   "828220": {
    "breakdownData": {
     "_reference": {
      "intervalData": {},
      "generalData": {
       "visitCount": 167938,
       "visitorCount": 0,
       "goalsData": {
        "279599": {
         "conversionCount": 7826,
         "convertedVisitCount": 7826,
         "revenueCount": 986076.0,
         "convertedVisitorCount": 0,
         "revenuePerVisit": 5.87,
         "revenuePerVisitor": 0.0,
         "reliability": 100.0,
         "improvementRange": {
          "min": 193.92,
          "max": 229.03,
          "half": 17.56
         },
         "improvementRate": 211.48,
         "conversionRate": 0.04660053114840001,
         "averageCart": 126.0,
         "ratioValue": 0.0,
         "continuousMetrics": {
          "conversions": {
           "reliability": 1.0,
           "improvementRate": 2.114771645178252,
           "halfInterval": 0.10445147824911348,
           "lowerBound": 2.0103201669291386,
           "upperBound": 2.219223123427365
          },
          "revenuePerVisit": {
           "reliability": 1.0,
           "improvementRate": 2.1650098975198366,
           "halfInterval": 0.10613617951119597,
           "lowerBound": 2.0588737180086407,
           "upperBound": 2.2711460770310326
          },
          "averageCart": null
         },
         "outlierBounds": {
          "lower": 0.1,
          "upper": 99.0
         }
        }
       }
      }
     }
    }
   },
   "828221": {
    "breakdownData": {
     "_reference": {
      "intervalData": {},
      "generalData": {
       "visitCount": 174194,
       "visitorCount": 0,
       "goalsData": {
        "279599": {
         "conversionCount": 1477,
         "convertedVisitCount": 1477,
         "revenueCount": 189056.0,
         "convertedVisitorCount": 0,
         "revenuePerVisit": 1.09,
         "revenuePerVisitor": 0.0,
         "reliability": 100.0,
         "improvementRange": {
          "min": -47.93,
          "max": -38.72,
          "half": 4.6
         },
         "improvementRate": -43.33,
         "conversionRate": 0.00847905209134643,
         "averageCart": 128.0,
         "ratioValue": 0.0,
         "continuousMetrics": {
          "conversions": {
           "reliability": 1.0,
           "improvementRate": -0.4332615877700786,
           "halfInterval": 0.027369693136479373,
           "lowerBound": -0.46063128090655797,
           "upperBound": -0.40589189463359926
          },
          "revenuePerVisit": {
           "reliability": 1.0,
           "improvementRate": -0.41497970350459723,
           "halfInterval": 0.028252586463462577,
           "lowerBound": -0.4432322899680598,
           "upperBound": -0.38672711704113466
          },
          "averageCart": null
         },
         "outlierBounds": {
          "lower": 0.1,
          "upper": 99.0
         }
        }
       }
      }
     }
    }
   }
  },
  "ventilationNames": null,
  "cupedDataByGoalId": {}
 }
}

3. 結果を解釈して勝者バリエーションを判断する

勝者バリエーションは、高い信頼性（95% を超える）と参照バリエーションと比較した正の改善率を示す必要があります。 JSON レスポンスは、Redesign 1 と Redesign 2 の両方が 100% の信頼度を持つことを示しています。ただし、Redesign 1 は +211.48% の改善率を示すのに対し、Redesign 2 は -43.33% の率を示します。したがって、Redesign 1 が勝者です。 Redesign 1

"828220": {
    "breakdownData": {
     "_reference": {
      "intervalData": {},
      "generalData": {
       "visitCount": 167938,
       "visitorCount": 0,
       "goalsData": {
        "279599": {
         "conversionCount": 7826,
         "convertedVisitCount": 7826,
         "revenueCount": 986076.0,
         "convertedVisitorCount": 0,
         "revenuePerVisit": 5.87,
         "revenuePerVisitor": 0.0,
         "reliability": 100.0,
         "improvementRange": {
          "min": 193.92,
          "max": 229.03,
          "half": 17.56
         },
         "improvementRate": 211.48,

Redesign 2

"828221": {
    "breakdownData": {
     "_reference": {
      "intervalData": {},
      "generalData": {
       "visitCount": 174194,
       "visitorCount": 0,
       "goalsData": {
        "279599": {
         "conversionCount": 1477,
         "convertedVisitCount": 1477,
         "revenueCount": 189056.0,
         "convertedVisitorCount": 0,
         "revenuePerVisit": 1.09,
         "revenuePerVisitor": 0.0,
         "reliability": 100.0,
         "improvementRange": {
          "min": -47.93,
          "max": -38.72,
          "half": 4.6
         },
         "improvementRate": -43.33,

4. 実験結果をフィルタする

breakdown パラメータと filters パラメータを使用して、特定の結果を取得します。breakdown パラメータは、単一のディメンション（ブラウザ、オペレーティングシステム、曜日など）でデータを整理します。filters パラメータは、ブレークダウンが適用される前にデータを訪問者のサブセットに制限します。

breakdown パラメータは、リクエストごとに 1 つのオブジェクト のみを受け付けます（配列ではありません）。複数のディメンションを比較するには、ブレークダウンごとに 1 つのリクエストを送信してください。

ブレークダウンの形式

ほとんどのブレークダウンタイプは type フィールドのみを受け取ります。例:

"breakdown": {
  "type": "BROWSER"
}

3 つのブレークダウンタイプは追加のフィールドを必要とします: INTERVAL — 時間間隔で結果を分割します。"type": "INTERVAL" を interval フィールドと組み合わせます:

"breakdown": {
  "type": "INTERVAL",
  "interval": "DAY"
}

interval フィールドは HOUR、DAY、WEEK、MONTH、YEAR を受け付けます。 CUSTOM_DATUM — カスタムデータインデックスで結果を分割します。"type": "CUSTOM_DATUM" を index フィールドと組み合わせます:

"breakdown": {
  "type": "CUSTOM_DATUM",
  "index": 3
}

CROSS_CAMPAIGN — 別の実験またはパーソナライゼーションへの露出で結果を分割します。experiments または personalizations のうち少なくとも 1 つを指定します:

"breakdown": {
  "type": "CROSS_CAMPAIGN",
  "experiments": [188309],
  "personalizations": []
}

フィルタタイプ

各フィルタオブジェクトには type 文字列と include ブール値が必要です。一致する訪問者に結果を制限するには include を true に設定し、除外するには false に設定します。追加のフィールドは type によって異なります:

`type`	追加フィールド	受け付ける値
`BROWSER`	`values` (string[])	`CHROME`、`EDGE`、`FIREFOX`、`SAFARI`、`OPERA`、`OTHERS`
`DEVICE_TYPE`	`values` (string[])	`DESKTOP`、`TABLET`、`PHONE`、`OTHERS`
`OS`	`values` (string[])	`WINDOWS`、`MAC_OS`、`I_OS`、`LINUX`、`ANDROID`、`WINDOWS_PHONE`、`OTHERS`
`NEW_VISITOR`	`visitorsType` (string)	`NEW_VISITORS`、`RETURNING_VISITORS`
`ORIGIN_TYPE`	`values` (string[])	`SEO`、`SEM`、`AFFILIATION`、`EMAIL`、`DIRECT`
`SDK`	`values` (string[])	`JAVA`、`ANDROID`、`GO`、`DOTNET`、`PYTHON`、`RUBY`、`IOS`、`PHP`、`JAVASCRIPT`、`NODEJS`、`REACT`、`RUST`、`ELIXIR`
`DAY_OF_WEEK`	`values` (string[])	`SUNDAY`、`MONDAY`、`TUESDAY`、`WEDNESDAY`、`THURSDAY`、`FRIDAY`、`SATURDAY`
`WEATHER_CODE`	`values` (string[])	`CLEAR_SKY`、`CLOUDS`、`RAIN`、`THUNDERSTORM`、`SNOW`、`HAIL`、`WIND`、`ATMOSPHERIC_DISTURBANCES`
`LANGUAGE`	`values` (string[])	ISO 639-1 言語コード（例: `EN`、`FR`、`DE`）
`CUSTOM_DATUM`	`customDataId` (integer)、`value` (string)	任意のカスタムデータ値
`TARGETING_SEGMENT`	`values` (integer[])	セグメント ID
`GOAL_REACHED`	`goalId` (integer)、`index` (integer)、`value` (string)

例: 新規訪問者にフィルタされたブラウザブレークダウン

次のリクエストは、Request experiment’s results エンドポイントに POST を送信することで、新規訪問者に制限されたブラウザブレークダウンを適用します:

curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
  "visitorData": true,
  "sequentialTesting": true,
  "breakdown": {
    "type": "BROWSER"
  },
  "referenceVariationId": "0",
  "filters": [
    {
      "type": "NEW_VISITOR",
      "visitorsType": "NEW_VISITORS",
      "include": true
    }
  ],
  "goalsIds": [279599]
}'

dataCode を受け取った後、結果を取得します:

curl -L -X GET 'https://api.kameleoon.com/results?dataCode=14443931880924098266207585267983330260134079899081739889989435434342588016765'

成功レスポンスは、ブラウザ別に分割された結果を返します。レスポンスは上記のステップ 2 と同じ構造に従い、breakdownData 内の各ブラウザタイプ（CHROME、FIREFOX、OTHERS など）がキーになります。次のレスポンスはわかりやすさのために省略されています:

{
  "status": "READY",
  "data": {
    "variationData": {
      "828221": {
        "breakdownData": {
          "OTHERS": {
            "intervalData": {},
            "generalData": {
              "visitCount": 0,
              "visitorCount": 587206,
              "goalsData": {
                "279599": {
                  "conversionCount": 5410,
                  "revenueCount": 692480.0,
                  "convertedVisitorCount": 5359,
                  "revenuePerVisitor": 1.18,
                  "reliability": 100.0,
                  "improvementRange": {
                    "min": -53.0,
                    "max": -48.7,
                    "half": 2.15
                  },
                  "improvementRate": -50.85,
                  "conversionRate": 0.009126269145751235,
                  "averageCart": 129.22,
                  "ratioValue": 0.0
                }
              }
            }
          },
          "CHROME": {
            "intervalData": {},
            "generalData": {
              "visitCount": 0,
              "visitorCount": 16,
              "goalsData": {
                "279599": {
                  "conversionCount": 0,
                  "revenueCount": 0.0,
                  "reliability": 50.0,
                  "improvementRate": 0.0,
                  "averageCart": 0.0,
                  "ratioValue": 0.0
                }
              }
            }
          }
        }
      }
    },
    "ventilationNames": null,
    "cupedDataByGoalId": {}
  }
}

​要件

​ゴール

​結果取得の仕組み

​1. データコードを取得する

​ケース 1: 結果を直接取得する

​ケース 2: 認可なしで結果を共有する

​1. SharedToken を取得する

​2. SharedToken を使って dataCode を取得する

​2. 実験結果を取得する

​3. 結果を解釈して勝者バリエーションを判断する

​4. 実験結果をフィルタする

​ブレークダウンの形式

​フィルタタイプ

​例: 新規訪問者にフィルタされたブラウザブレークダウン

要件

ゴール

結果取得の仕組み

1. データコードを取得する

ケース 1: 結果を直接取得する

ケース 2: 認可なしで結果を共有する

1. SharedToken を取得する

2. SharedToken を使って dataCode を取得する

2. 実験結果を取得する

3. 結果を解釈して勝者バリエーションを判断する

4. 実験結果をフィルタする

ブレークダウンの形式

フィルタタイプ

例: 新規訪問者にフィルタされたブラウザブレークダウン