cja-segment-performance-comparator

セグメントパフォーマンス比較（カスタマージャーニー分析）

一連の主要指標について、2～5 個のオーディエンスセグメントを並べて比較します。出力では、各セグメント単体の特徴だけでなく、各指標でどのセグメントが優れているか、劣っているか、そしてどの程度の差があれば対応すべきかも示します。

このスキルは、データに基づいて「どのオーディエンスに注力すべきか」という疑問に答えます。セグメント比較は、製品に関する意思決定、パーソナライズ戦略、予算配分に役立つため、網羅的なデータよりも、わかりやすさと実用性が重要です。

---

使用する CJA MCP ツール

• findSegments — 名前またはキーワードでセグメントを検索します
• describeSegment — 候補のセグメントを使用する前に、そのロジックを確認します
• findMetrics — 基本指標 ID を特定します
• findCalculatedMetrics — カスタム KPI を比較対象に含めます
• listComponentUsage — 最もよく使われる指標を特定し、デフォルトの比較対象にします
• runReport（segmentIds または adhocSegments を指定）— セグメントごとの指標値を取得します

---

フェーズ 0 — セットアップ

1. findDataViews を呼び出して、利用可能なデータビューを一覧表示します。
2. ユーザーがデータビューを指定していない場合は、一覧を表示してどれを使うか尋ねます。
3. 選択された ID を指定して setDefaultSessionDataViewId を呼び出します。
4. 比較するセグメントがまだ指定されていない場合は、どのセグメントを比較するかユーザーに尋ねます。比較する指標も確認します。

---

フェーズ 1 — 比較するセグメントを特定する

1.1 ユーザーの説明から特定する

ユーザーが具体的なセグメント名を挙げた場合は、該当するものを特定します。

findSegments(search: "<segment name>")

一致する候補ごとに describeSegment を呼び出して、正しいセグメントか確認します。

describeSegment(segmentId: "<id>")

候補が複数ある場合は、セグメントの定義の概要をユーザーに示します。

「『モバイルユーザー』に一致するセグメントが 2 つ見つかりました。モバイル訪問者（全デバイス） と モバイルアプリユーザー です。どちらを比較しますか？」

1.2 平易な言葉での説明から特定する

ユーザーが「モバイルユーザーとデスクトップユーザーを比較して」と言っても一致するセグメントがない場合は、比較用のアドホックセグメントをその場で作成することを提案します。

「モバイル用とデスクトップ用の既成セグメントが見つかりません。デバイスタイプを使って、この比較用の一時的なアドホックセグメントを作成できます。アドホックセグメントで進めますか？それとも、先に恒久的なセグメントを作成しますか？」

アドホックセグメントは runReport の adhocSegments を使って作成します。比較自体に保存は不要です。

1.3 セグメント数の上限

1 回の比較で扱えるセグメントは最大 5 つです。5 つを超えると、マトリックスが広くなりすぎて、意味のある形で読み取れなくなります。ユーザーがそれ以上を希望する場合は、次のように伝えます。

「読みやすさを保つため、最も関連性の高い 5 つに絞ります。使用数に基づいて優先するか、リストの順序どおりにしますか？」

---

フェーズ 2 — 比較する指標を特定する

2.1 ユーザーの指定から特定する

指定された指標名を findMetrics と findCalculatedMetrics で特定します。

2.2 デフォルト指標の検出

ユーザーが指標を指定していない場合は、使用数上位の指標を取得します。listComponentUsage ツールは limit パラメーターをサポートしていません。使用数の順に並んだすべてのコンポーネントが返されるため、結果から上位 6～8 件を選びます。

listComponentUsage(componentType: "metric")
listComponentUsage(componentType: "calculatedMetric")

同じ内容を測定する指標では、基本指標より計算指標を優先します。計算指標は、意図的に定義された KPI を反映するためです。

2.3 比較する指標の選定

比較に適した指標は、すべてのセグメントにとって意味のあるものです。たとえば、「売上高」はモバイルユーザーにもデスクトップユーザーにも意味がありますが、「アプリのインストール数」はモバイルユーザーにしか意味がありません。あるセグメントで必ずゼロになる指標は除外します。

判断に迷う場合は、「標準の KPI セットを使いますか？それとも、コンバージョン率、売上高、エンゲージメントなどの特定の指標に絞りますか？」と尋ねます。

---

フェーズ 3 — 比較を実行する

各セグメントを適用し、すべての比較指標を含めて runReport を実行します。runReport では、metricIds はカンマ区切りの文字列、startDate／endDate（dateRange ではありません）、および dimensionIds を指定します（サマリーのみのレポートでも必須です。variables/daterangeday や variables/web.webPageDetails.name など、カーディナリティの低いディメンションを使用してください）。 すべての指標のサマリー合計は summaryData.filteredTotals にあります。

runReport(
  dimensionIds: "variables/web.webPageDetails.name",
  metricIds: "metrics/visits,metrics/revenue_1,metrics/orders_1_1",
  startDate: "<period start>T00:00:00",
  endDate: "<period end>T23:59:59",
  page: 0,
  limit: 1,
  segmentIds: "<segment id>"
)

アドホックセグメントには、完全な CJA セグメント定義オブジェクトを使用します。

runReport(
  dimensionIds: "variables/web.webPageDetails.name",
  metricIds: "metrics/visits,metrics/orders_1_1",
  startDate: "<period start>T00:00:00",
  endDate: "<period end>T23:59:59",
  page: 0,
  limit: 1,
  adhocSegments: [{
    "func": "segment",
    "version": [1, 0, 0],
    "container": {
      "func": "container",
      "context": "visitors",
      "pred": {
        "func": "streq",
        "val": { "func": "attr", "name": "variables/device_type" },
        "str": "Mobile Phone"
      }
    }
  }]
)

指標の合計値は、metricIds 文字列内での指標の 0 から始まるインデックスを i として、summaryData.filteredTotals[i] から読み取ります。

セグメントごとに 1 つのレポートを実行します。すべての結果を次のマトリックスにまとめます。

• 行 = 指標
• 列 = セグメント

---

フェーズ 4 — 比較マトリックスを作成する

各セル（指標 × セグメント）について：

• value[metric][segment] = runReport から取得した指標の生値

各指標の行について：

• winner = 値が最も高いセグメント（「低いほど良い」指標の場合は最も低いセグメント）
• loser = 値が最も低いセグメント（逆指標の場合は最も高いセグメント）
• range = （最大値 − 最小値）/ 最大値 × 100 — セグメント間の差をパーセンテージで示したもの
• significant = range > 10% の場合は true（対応する価値のある意味のある差）

---

フェーズ 5 — HTML 比較レポートを生成する

レポートをインラインで生成し、次の場所に書き込みます。 /tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html

HTML テンプレート

template.html を読み込み、そのまま使用します。HTML 構造や CSS を独自に変更してはいけません。{PLACEHOLDER} トークン（{ORG_NAME}、 {DATE_RANGE}、{DATA_VIEW}、{GENERATED_DATE}、{SEGMENT_NAMES_SUMMARY}、 {SEGMENT_NAME}、{COLOR}、{VISITOR_COUNT}、{NUM_SEGMENTS}、{NUM_METRICS}、 {NUM_SIGNIFICANT}、{OVERALL_WINNER}、{METRIC_NAME}、{VALUE}、 {WINNER_SEGMENT}、{SPREAD}、{INSIGHT_TEXT}）を埋め、各データ項目につきセグメントチップ、マトリックスの行、インサイトボックスを 1 つずつ繰り返すだけにします。フェーズ 4 の勝者／敗者のルールに従って、cell-winner／cell-loser クラスを使用します。

---

フェーズ 6 — ナラティブ形式のインサイト

マトリックスの作成後、インサイトセクション用に 3～5 個の箇条書きのインサイトを生成します。

1. 全体的な勝者：「リピーターは 7 指標中 5 指標で新規訪問者を上回り、最大の差はセッションあたりの収益（+82%）です。」
2. 最も大きな差：「最大の差はコンバージョン率です。モバイルのコンバージョン率は 1.2%、デスクトップは 3.8% で、優先的に対応する価値のある 68% の差があります。」
3. 意外な同等性：「新規訪問者とリピーターの直帰率はほぼ同じ（42% 対 44%）であり、ランディングページの品質に一貫性があることが示唆されます。」
4. 実行可能なシグナル：「有料検索からの訪問者は、ダイレクトからの訪問者よりセッションあたりの収益が 2.3 倍高いため、有料検索への予算の移行を検討してください。」
5. 異常：「1 つのセグメントで、すべての指標の値がほぼゼロになっています。セグメント定義が正しく、現在のデータビューと一致していることを確認してください。」

インサイトは指標 ID ではなく、平易な英語で記述します。具体的なセグメント名と指標値を記載します。

---

ワークフローの概要

1. 2～5 個のセグメントを解決します（名前またはアドホック定義を使用）。
2. 5～8 個の比較指標を特定します（ユーザー指定または使用状況の上位から選択）。
3. すべての指標を含めてセグメントごとに 1 つの runReport を実行し、結果を収集します。
4. 比較マトリックスを作成します。行 = 指標、列 = セグメント。
5. 各行の勝者／敗者を記録し、差を算出し、重要な差を特定します。
6. マトリックスとインサイトの箇条書きを含む HTML レポートを生成します。
7. /tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html に書き込みます。
8. open /tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html で開きます。
9. インラインの要約を提示します。全体的な勝者、最大の差がある指標、実行可能な推奨事項を 1 つ含めます。

---

重要なガードレール

• 読み取り専用の分析です。 セグメントや計算済みの指標を削除または変更しないでください。
• 実行前に必ずセグメントを確認します。 セグメント名が曖昧な場合（例：「Mobile」は複数のセグメントを指す可能性があります）は、一致したセグメントの ID と定義をユーザーに提示して解決してください。
• すべてのセグメントで同じ日付範囲を使用します。 異なる期間での比較は誤解を招きます。
• セグメント間の重複に注意します。 2 つのセグメントでオーディエンスが大幅に重複している場合は、その旨を伝えてください。「差」が誇張されている可能性があります。
• 比較するセグメント数に上限を設けます。 1 つのレポートで 5～6 個を超えるセグメントを比較すると、出力が読みにくくなるため、ユーザーに優先順位を尋ねてください。
• 統計的有意性と実務上の重要性を区別します。 0.1％の差が実際のアクションにつながることはほとんどありません。ユーザーから別途指定がない限り、5％以上の差に注目してください。

---

やり取りの例

「前四半期のモバイルとデスクトップのセグメントのパフォーマンスを比較してください。」

1. セットアップ： データビューを確認します。findDataViews を呼び出し、ユーザーが選択します。setDefaultSessionDataViewId を呼び出します。
2. セグメントの特定： findSegments を呼び出して、「Mobile Users」と「Desktop Users」のセグメントを見つけます。一致した名前と ID を提示して確認し、ユーザーの承認を得ます。
3. 指標： 「どの指標を比較しますか？」と尋ねます。ユーザー：「セッション数、コンバージョン率、収益、平均注文額です。」
4. 分析： 両方のセグメントを適用して、2026 年第 1 四半期の runReport を実行します。結果を並べて表にまとめます。
5. 調査結果： モバイル：セッション数の 45％、CVR 2.1％、RPV $0.84。デスクトップ：セッション数の 55％、CVR 4.8％、RPV $2.10。デスクトップのコンバージョン率は 2.3 倍です。比較表と、次に推奨する 3 つの対応策を提示します。