configuring-experiment-analytics

実験分析の設定

このスキルでは、分析対象に含まれるユーザーは誰か、影響をどのように測定するかについて説明します。

曝露条件

曝露条件によって、実験分析の対象としてカウントされるユーザーが決まります。

曝露イベント

次の 2 つの方法があります。

1. デフォルトの曝露イベント — 実験のフラグに対するデフォルトの曝露イベント（$feature_flag_called、または新しい実験では$experiment_exposure）が発生すると、ユーザーが対象に含まれます。どちらが適用されるかはサーバー側で解決されます。どちらかの名前を決めつけず、experiment-getからresolved_exposure_eventを確認してください（どちらのイベントにも同じプロパティが含まれます）。$feature_flag_calledの場合は、$experiment_exposureも読み込み（event IN ('$feature_flag_called', '$experiment_exposure')）、行数ではなく人物数をカウントしてください。これは標準的な方法です。コード内でユーザーが実際に機能フラグに遭遇した場合にのみ、そのユーザーが対象に含まれます。
2. カスタム曝露イベント — 特定のカスタムイベントが発生すると、ユーザーが対象に含まれます。分析対象となるユーザーをより厳密に制御したい場合（例：実験が実施されているページを実際に訪問したユーザーのみ）に使用します。

複数バリアントの処理

ユーザーが複数のバリアントに曝露された場合（例：フラグの変更や競合状態による場合）：

• 分析から除外 — これらのユーザーを分析対象から完全に除外します。データはよりクリーンになりますが、サンプル数は少なくなります。
• 最初に確認されたバリアントを使用 — ユーザーを、最初に曝露されたバリアントに割り当てます。すべてのユーザーを分析対象に含められます。ただし、「最初に確認された」バリアントでは、行動を単一のバリアントに明確に帰属させられないため、別のバイアスが生じる可能性があります。必要な場合を除き、推奨されません。

分割比率が不均等な場合のバイアスリスク。 「分析から除外」と不均等なバリアント分割を併用すると、バイアスが生じる可能性があります。複数のバリアントに割り当てられたユーザーは非対称に除外され、割り当て数の少ないバリアントほど、割り当てられたユーザーのうち除外される割合が大きくなります。こうしたユーザーの行動が他のユーザーと異なる場合、割り当て数の少ないバリアントの指標に偏りが生じます。

適切な対策は、実験の状態によって異なります。

• 未公開、またはこれまでに曝露されたユーザーがごく少数の場合 — バリアントの分割を均等にし、全体のロールアウト率を使ってテストバリアントへの曝露を制限します。これにより、バイアスを取り除き、統計的検出力を維持できます。configuring-experiment-rolloutを参照してください。
• 曝露数が十分にある実施中の実験の場合 — 実施中に分割を変更すると、ユーザーがバリアント間で再割り当てされ、ユーザーエクスペリエンスとデータ品質が損なわれます。代わりに、この設定を「最初に確認されたバリアントを使用」に切り替えてください。すでに割り当てられたユーザーは元のバリアントに維持され（再割り当てなし）、非対称な除外もなくなります。

テストアカウントのフィルタリング

exposure_criteria.filterTestAccounts（デフォルト：true）は、社内ユーザーおよびテストユーザーを分析対象から除外します。

実験の特定

指標を変更するには、実験 ID が必要です。ユーザーが実験名や説明（例：「チェックアウトテストに指標を追加」）で実験に言及した場合は、先にfinding-experimentsスキルを読み込み、具体的な ID を特定してください。

指標

指標を実験に追加する方法は 2 つあり、どちらもexperiment-updateを使用します。

• インライン指標 — 実験に直接定義します。metrics配列で送信します。この配列はインライン指標の一覧全体を置き換えるため、既存の指標を保持できるよう、必ず最初にexperiment-getで現在の実験を取得してください。
• 共有（保存済み）指標 — 多数の実験に追加できる再利用可能な指標オブジェクトです。saved_metrics_idsで ID を指定して追加します（このリストも実験に設定済みの保存済み指標へのリンクを置き換えるため、一覧全体を再送信してください。Step 1を参照）。

インラインで重複して作成するより、共有指標の再利用を優先してください。 適切な共有指標が存在しない場合にのみ、新しいインライン指標を作成してください。

ステップ 1：既存の共有指標を確認する（必須 — 名前ではなく定義で照合）

新しいインライン指標を作成する前に、同じ内容を測定する共有（保存済み）指標がプロジェクトにすでに存在するか、必ず確認して再利用してください。すでに共有指標として存在する指標を重複して作成すると、測定が分断されます。これはまさに避けたいことです。

再利用の判断は指標の名前ではなく、指標の 定義（イベントまたはアクションと指標タイプ）に基づきます。 保存済み指標の名前はチームごとの慣習で付けられており、推測できないため、各指標が何を測定するか（その query）を比較してください。タイトルで比較してはいけません。

ワークフロー：

1. まず、これから作成するものを明確にします。 検索する前に、対象のイベント／アクションと指標タイプ（mean / funnel / ratio / retention）を決めます。read-data-schema を使ってイベントの存在を確認する方法については、ステップ 2 を参照してください。具体的なイベント／アクションがわかって初めて重複を見つけられるため、この確認はイベントを特定した後に行い、前には行いません。
2. イベントで検索し、候補ごとの query を比較します。 experiment-saved-metrics-list を ?event=<the event you're measuring> とともに呼び出し、そのイベントを参照する指標を見つけます。直接（EventsNode）参照する指標に加え、指標が参照するアクションのステップイベントを経由して参照する指標も見つかるため、アクションベースの指標も、そのアクションが発生するイベントで見つかります。次に、返された各行の query（name／description ではありません）を確認します。保存済み指標の query が、作成予定の指標と 同じイベントまたはアクションを、同じ metric_type（および互換性のある math）で測定している場合、名前が異なっていても再利用対象です。
   • アクション名ではなくイベントで照合します。 アクションベースの指標は、そのアクションが発生するイベントで見つかります。アクションのラベルではなく、そのイベントを指定してください。
   • この用途で search を使わないでください。 search が照合するのは指標自体の name／description／タグのみであり、基盤となるイベントやアクションは照合しません。そのため、定義が一致する指標は見つけられません。search は、ユーザーが特定の保存済み指標を追加するよう指定した場合にのみ使用してください（定義の照合ではなく、名前の解決に使用します）。
3. 定義が一致する保存済み指標がある場合 — 名前／説明を示して一致をユーザーに確認し、新しい指標を作成する代わりに、その指標を追加します。
   • experiment-get を呼び出し、実験の現在の saved_metrics を読み取ります。
   • experiment-update を呼び出し、saved_metrics_ids に希望する全項目を指定します。これは既存のリンクを置き換えるため、すでに追加されている項目と新しい項目の両方を含めてください。各項目の形式は { "id": <saved-metric id>, "metadata": { "type": "primary" } } です。type は "primary" または "secondary" に設定します。metadata は省略可能で、省略時は primary が既定値になります。
   • セットを作り直す際は ID に注意してください。 直前に読み取った saved_metrics の各項目には、トップレベルの id（リンク ID）と、saved_metric フィールド（指標 ID）があります。saved_metrics_ids に必要なのは saved_metric の値であり、リンクの id ではありません。リンクの id を送ると、誤った指標が追加されるか、検証に失敗します。
   • 共有指標にはイベントがすでに定義されているため、インライン指標を作成する必要はありません。
4. ライブラリに同じイベント／アクションとタイプを測定する指標がない場合 — インライン指標を作成します（ステップ 2 以降）。そのインライン指標が実験間で再利用される可能性が高い場合は、代わりに experiment-saved-metrics-create を使って共有指標として作成することを提案し、前述の手順で追加します。これにより、次の実験で再利用できます。

ステップ 2：利用可能なイベントを確認する（インライン指標を作成する前に必ず実施）

新しいインライン指標を提案または作成する前に、必ず read-data-schema を呼び出して、プロジェクトに実際に存在するイベントを確認してください。この手順を省略してはいけません。プロジェクトで追跡されていると思うイベント名を推測して提案してはいけません。確認済みのイベントのみを使用してください。 （ステップ 1 で既存の共有指標を追加する場合は不要です。共有指標には、使用するイベントがすでに含まれています。）

以下の場合も同様です。

• ユーザーがイベント名を提示した場合 — 実在し、正しく表記されていることを確認するため、検索してください
• ユーザーが「どのような指標がおすすめですか？」と尋ねた場合 — まずイベントを検索し、実際のデータに基づいて提案してください
• コンテキストから特定のイベントが明らかに思える場合 — そのイベントは存在しないか、別の名前で登録されている可能性があります

ワークフロー：

1. read-data-schema を呼び出して、プロジェクトのイベントを取得します
2. 実験の仮説に基づいて、関連するイベントをユーザーに提示します
3. ユーザーが指標に使用するイベントを選びます
4. 確認済みのイベント名を使って指標を設定します

正当な例外 — allow_unknown_events: true： まだ取り込まれていないイベントをユーザーが意図的に計測しようとしている場合（例：コード変更がリリースされる前に実験を設定する場合）に限り、experiment-create／experiment-update でこれを渡してください。ユーザーに確認してください。「イベントの検索結果が期待したものと異なる」ことへの回避策として使用してはいけません。

例：

User: "Let's add some metrics for the checkout experiment"

WRONG: "I'd suggest using purchase_completed as the primary metric..."
  (hallucinated event name — never seen the project's actual events)

RIGHT: *calls read-data-schema* → "Here are the events in your project
  related to checkout: `checkout_step_completed`, `payment_processed`,
  `order_confirmed`. Which of these represents a successful checkout?"

ステップ 3：指標タイプを選択する

references/metric-templates.md のテンプレートを使用します。一般的なリクエスト（「収益を増やす」「ユーザーに再訪してもらう」など）を指標タイプに対応付け、それに設定するデフォルト値（期間単位、ウィンザー化、目標）を示しています。

指標タイプは 4 種類あります。いずれも kind: "ExperimentMetric" を指定します。

metric_type	使用する場面	必須フィールド
"mean"	ユーザーごとの数値プロパティの平均（収益、セッション時間、ユーザーあたりのページビュー数）	source
"funnel"	露出から、順序付けられた 1 つ以上のアクションまでのコンバージョン率	series（1 ステップ以上）
"ratio"	あるイベントを別のイベントと比較した発生率	numerator、denominator — プロパティを集計するには、いずれかの側に math: "sum" と math_property を設定します。フィルターは集計されません
"retention"	露出後にユーザーが再訪するか	start_event、completion_event、retention_window_start、retention_window_end、retention_window_unit、start_handling

ファネル指標と暗黙的な露出ステップ

ファネル指標では、実験の露出イベントが自動的に step_0 として先頭に追加されます。 そのため、series に 1 ステップあるファネルは、有効な 2 ステップのファネルです：露出 → アクション。 「露出したユーザーのうち、X を実行した割合」を測定する場合は、これが適切な選択です。

例：

• 「露出したユーザーのうち、/login に到達した割合は？」→ 1 ステップのファネル（/login にフィルターした $pageview）
• 「露出したユーザーのうち、チェックアウトを完了した割合は？」→ 1 ステップのファネル（checkout_completed）
• 「露出したユーザーのうち、カート → チェックアウト → 購入に進んだ割合は？」→ 3 ステップのファネル

同じイベントに対する平均とファネル

• 平均は、ユーザーあたりの平均回数／値を測定します（例：「ユーザーあたりのページビュー数」「ユーザーあたりの収益」）。
• ファネルは、コンバージョン率を測定します（例：「露出したユーザーのうち、購入した人の割合」）。

どちらも同じイベントを参照できます。違いは、回数や規模を測定するか（平均）、コンバージョンの有無を測定するか（ファネル）です。

リテンション：開始イベントと完了イベントが同じ場合と異なる場合

リテンション期間は開始イベントから測定されるため、選択したイベントによって測定内容が決まります。 開始イベントの発生自体は完了としてカウントされません（後に別のイベントが発生した場合のみカウントされます）。そのため、どちらのパターンも有効です。

• 開始イベントと完了イベントが異なる場合 → コンバージョン型のリテンション（「期間内に目標のアクションに到達したか？」）。
• 開始イベントと完了イベントが同じ場合 → リピート型のリテンション（「そのイベントが もう一度 発生したか？」）。From 0 は同じ期間内のリピート（同日内のリピートを含む）もカウントします。From ≥ 1 は後の期間での発生を必須とします。start_handling: "first_seen" を使用してください。「<event> のリテンション」と言われた場合、通常はリピート型のリテンションを意味します。

4 種類すべての指標タイプと、タイプごとの必須フィールドを含む、レンダリング後の ExperimentMetric スキーマ全体に加え、最もよくある失敗パターン（math: "sum" + math_property の代わりに is_set フィルターを使う ratio、retention_window_start / start_handling を指定しない retention）に対する WRONG/RIGHT JSON ペアについては、references/metric-configuration.md を参照してください。ratio または retention のペイロードを組み立てる前に確認してください。必須フィールドの情報が正となります。

ステップ 4：主要指標と副次指標

• 主要指標 — 実験の主な成功基準です。実験を展開するか終了するかの判断に用います。
• 副次指標 — 状況を把握するための追加の測定項目です。ガードレール指標として役立ちます（例：コンバージョンの改善によってエラー率が上昇しないことを確認する）。

結果の解釈

実験結果の読み方、統計的有意性、実験を展開するか終了するかの判断については、references/interpreting-results.md を参照してください。

関連スキル

• configuring-experiment-rollout — 展開に関する内容：バリアントの割り当てとトラフィックの割合
• diagnosing-experiment-health — 結果に偏りがある場合や、空の場合、異常に見える場合
• analyzing-experiment-session-replays — 定性的な補完：各バリアントのユーザーが実際に何をしたかを確認します