analyzing-experiment-session-replays

実験のセッションリプレイを分析する

このスキルでは、実験の各バリアントにおけるセッション録画を分析し、コントロール群とテスト群の行動の違いを把握する方法を説明します。

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• ユーザーが実験のセッションリプレイの分析を依頼した場合
• ユーザーが実験のバリアントごとのユーザー行動の違いを把握したい場合
• ユーザーがコントロールバリアントとテストバリアントのユーザー行動を比較したい場合
• ユーザーが実験指標を補完する定性的なインサイトを求めている場合
• ユーザーが「実験でユーザーはどのように行動していますか？」や「バリアント X のセッションリプレイを見せてください」のような質問をした場合

前提条件

セッションリプレイを分析する前に、次の条件を満たしていることを確認してください。

1. 実験が開始済みであること（下書き状態ではないこと）
2. プロジェクトでセッションリプレイが有効になっていること
3. ユーザーが実験のバリアントに接触していること
4. 実験に開始日が設定されていること

ワークフロー

1. 実験の詳細とフィーチャーフラグのバリアントを取得する

まず、実験情報とフィーチャーフラグのバリアント（信頼できる情報源）を取得します。

ステップ 1a：実験のメタデータを取得する

次のいずれかを実行できます。

• オプション A：コンテキストから実験 ID をすでに取得している場合は、experiment-get ツールを使用します
• オプション B：HogQL を使用して experiments テーブルにクエリします。

SELECT
    e.id,
    e.name,
    f.key AS feature_flag_key,
    e.start_date,
    e.end_date
FROM system.experiments e
JOIN system.feature_flags f ON f.id = e.feature_flag_id
WHERE e.id = <experiment_id>

実験データから、次の情報を抽出します。

• feature_flag_key：実験を制御するフィーチャーフラグ
• start_date と end_date：実験の期間

ステップ 1b：フィーチャーフラグからバリアントを取得する

重要：バリアントは必ずフィーチャーフラグから取得してください。experiment.parameters.feature_flag_variants から取得してはいけません。 パラメーターは同期されていない場合や、非推奨になっている場合があります。信頼できる情報源はフィーチャーフラグです。

フィーチャーフラグにクエリして、現在のバリアントを取得します。

SELECT filters.multivariate.variants AS variants
FROM system.feature_flags
WHERE key = '<feature_flag_key>'

バリアントのパスを直接選択してください。filters オブジェクト全体を選択すると、ターゲティング設定が大きいフラグでは結果が途中で切り詰められます。 構造の例：[{"key": "control", "name": "Control", "rollout_percentage": 50}, {"key": "test", ...}]

バリアントの key 値（例：「control」、「test」、「variant_a」）を使用して、セッション録画を絞り込みます。

2. 各バリアントのセッション録画フィルターを作成する

実験の各バリアントについて、そのバリアントに接触したユーザーに一致する録画フィルターを作成します。

バリアントのフィルター構造（query-session-recordings-list への入力）：

{
  "date_from": "<experiment.start_date>",
  "date_to": "<experiment.end_date or current time>",
  "filter_test_accounts": true,
  "properties": [
    {
      "type": "event",
      "key": "$feature/<feature_flag_key>",
      "operator": "exact",
      "value": ["<variant_key>"]
    }
  ]
}

重要な点：

• $feature/<flag_key> イベントプロパティには各イベントでのフラグの値が記録されます。この値で絞り込むと、そのバリアントが有効だったときの録画に一致します。ただし、これは接触を近似するものであり、実験の接触イベント（$feature_flag_called、または新しいロールアウトでの $experiment_exposure。どちらも ID ごとに重複排除されます）よりも広い範囲になります。バリアントをまたいだ行動の閲覧には適していますが、分析対象集団を正確に再現するものではありません。正確なフィルターが必要な場合は、scanning-experiments-with-replay-vision スキルで導出してください
• value はバリアントキー文字列の配列（例：["control"]）です。ブール値のフラグには ["true"] または ["false"] を使用します
• バリアントの絞り込みには、type: "flag" / flag_evaluates_to プロパティフィルターを使用しないでください。録画クエリでは受け付けられますが、ひそかに無視され、絞り込みなしの結果が返されます（最終確認日：2026-06-10）。それでも試す場合は、まず実際に絞り込まれることを確認してください。存在しないフラグキーを指定したクエリでは、録画が 0 件返されるはずです
• 日付範囲を実験の開始日と終了日に設定します
• テストユーザーを除外するには、filter_test_accounts: true を有効にします

3. 各バリアントの録画を取得する

ステップ 2 で作成したフィルターを使って、query-session-recordings-list ツールを使用します。

グループごとに録画を取得するため、バリアントごとにツールを 1 回呼び出します。

• バリアント「control」→ control グループの録画
• バリアント「test」→ test バリアントの録画
• 実験に 2 つを超えるバリアントがある場合は、追加のバリアントも同様に取得します

ツールは、次の情報を含む録画のリストを返します。

• distinct_id — ユーザーの個別 ID
• recording_duration、active_seconds、inactive_seconds
• click_count、keypress_count、mouse_activity_count
• console_log_count、console_warn_count、console_error_count
• start_url — 最初に訪問したページの URL
• start_time / end_time、activity_score

4. 比較して分析する

次の点に着目し、バリアント間で録画を比較します。

定量的なパターン：

• セッション時間の違い
• アクティビティのレベル（クリック数、キー入力数）
• コンソールエラー率
• 直帰率

定性的なインサイト：

• ユーザーの混乱や不満を示す兆候
• 異なるナビゲーション経路
• 機能の発見パターン
• エラーからの回復行動

5. 調査結果を提示する

バリアント間の行動の違いを要約し、次の点を明示します。

• バリアントごとの録画総数
• 各バリアントに特有の注目すべき行動パターン
• 観察されたユーザビリティ上の問題や利用時の障壁
• 定性データに基づく推奨事項

6. 観察すれば行動が分かり、質問すればユーザーの考えが分かります

セッションの視聴とユーザーへの質問は、それぞれ異なる手段であり、互いに代替できるものではありません。録画からは変更によってユーザーが何をしたかが分かります。実験対象のフローを完了したときに表示する短いアンケートからは、ユーザーがそれをどう思ったか、つまり評価と任意のコメントが分かり、バリアントごとに確認できます。ユーザー向けの変更が実質的なものであれば、この 2 つを組み合わせることで、どちらか一方だけの場合よりも定性的な状況をより十分に把握できます。そのため、ステップ 4 の行動比較で意見が把握できていない場合や、録画から見つかったパターンが、その行動を取ったユーザーに確認する価値のある仮説である場合は、この選択肢に触れてください。会話ごとに最大 1 回とし、断られた場合はその話題を続けないでください。

デフォルトでは、1 つのバリアントだけでなく、対象となったすべてのユーザーに質問します。片方のグループだけにポップオーバーを表示すること自体がグループ間の差異になり、回答イベントにはバリアントも記録されるため、グループごとの比較は維持されます。

→ [[diagnosing-experiment-health]] の references/qualitative-feedback.md を参照してください

インタラクションの例

User: "How are users behaving in my checkout experiment?"
Agent steps:
1. Query experiment details (ID: 123, feature_flag_key: "checkout-flow-test", date range: 2025-01-01 to 2025-01-31)
2. Query feature flag "checkout-flow-test" to get variants from filters.multivariate.variants
3. Extract variant keys: "control" and "new-checkout"
4. Build filters for control variant:
   - Property filter: { type: "event", key: "$feature/checkout-flow-test", operator: "exact", value: ["control"] }
   - Date range: 2025-01-01 to 2025-01-31
5. Call query-session-recordings-list with control filters → 147 recordings found
6. Build filters for new-checkout variant and call query-session-recordings-list → 152 recordings found
7. Compare patterns:
   - Control: Average 3m 45s session duration, 12% console errors
   - New-checkout: Average 2m 30s session duration, 5% console errors
8. Present findings:
   "I analyzed session replays for your checkout experiment. The new checkout flow shows:
   - 33% faster completion (2m 30s vs 3m 45s)
   - 58% fewer console errors (5% vs 12%)
   - Users in the new variant navigate directly to payment, while control users often backtrack to review cart
   - Recommendation: The new checkout flow reduces friction and errors"

重要な注意事項

推測で判断しないでください：

• 分析する前に、実験に録画があることを必ず確認してください
• 実験が開始されていること（start_date があること）を確認してください
• 録画が見つからない場合は、その旨をユーザーにはっきり伝えてください

フィルターの作成：

• $feature/<flag_key> イベントプロパティを使って、バリアントごとに録画を絞り込みます
• バリアントごとに 1 つのフィルターを使い、各バリアント固有のフィルターでツールを 1 回呼び出します
• ブール値フラグの場合は、バリアントキーではなく ["true"] / ["false"] を値として使います

エラー処理：

• 実験が下書き状態の場合は、まだ開始されていないことをユーザーに伝えてください
• 録画がない場合は、セッションリプレイを有効にするか、ユーザートラフィックが発生するまで待つよう提案してください
• バリアント数が想定と異なる場合は、実験の設定をもう一度確認してください

関連ツール

• query-session-recordings-list：フィルターを使ってセッション録画を取得するための中心的なツール
• experiment-get：実験のメタデータを取得します。統計結果には experiment-results-get を使います
• execute-sql：HogQL を使って experiments テーブルの詳細をクエリします

関連スキル

• diagnosing-experiment-health — 定量的な側面。同じ実験のバイアス確認と有意性の分析
• investigating-replay — いずれかのバリアントから、単一のセッションを詳しく調査
• finding-sessions-to-watch — 実験以外の一般的なセッションの絞り込み