aa-segment-performance-comparator

セグメントパフォーマンスの比較（Adobe Analytics）

主要な指標について、2つ以上のオーディエンスセグメントのパフォーマンスを並べて比較し、訪問者グループごとの行動の違いを把握します。セグメント同士を直接比較して、各指標の勝者、敗者、差を判定し、セグメントの規模を示す別個のコンテキストパネルも表示します。

AA の呼び出し予算： AA の runReport では、1 回の呼び出しにつき segmentId を 1 つだけ指定できます。N 個のセグメント × M 個の指標を比較するには、N×M 回の呼び出しに加え、セグメント規模のコンテキストパネル用にベースライン呼び出しが 1 回必要です。3 セグメント × 5 指標の場合、呼び出し回数は 16 回です。実用的なパフォーマンスを保つため、セグメントは最大 4 個、指標は最大 6 個に制限してください。開始前に、必ずセグメントと指標の一覧をユーザーに確認してください。

---

使用する AA MCP ツール

• findReportSuites — レポートスイートを選択します
• setSessionDefaults — セッションコンテキストを設定します（reportSuiteId + globalCompanyId）
• findSegments — 比較対象のセグメントを検索して選択します
• findMetrics — 指標 ID を解決します
• runReport — セグメントごと、指標ごとに 1 回呼び出し、規模のコンテキスト用にセグメントを指定しない呼び出しを 1 回行います

---

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

1. findReportSuites / setSessionDefaults でレポートスイートを確認します。

findReportSuites(globalCompanyId: "<gcid>", page: 0, limit: 10)
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")

---

フェーズ 1 — セグメントの選択

比較するセグメントをユーザーに尋ねます。指定がない場合は、次のように質問します。

「どの訪問者オーディエンスを比較しますか？ たとえば、モバイルとデスクトップ、新規とリピーター、有料検索とオーガニック、またはライブラリ内の特定の名前付きセグメントなどがあります。」

各セグメントを検索して確認します。

findSegments(page: 0, limit: 50)
# Filter locally by name. Built-in IDs: "Paid_Search", "Purchasers", "Return_Visits"

注： findSegments は searchTerm パラメーターを受け付けません。すべてのセグメントを取得し、名前でローカルに絞り込んでください。組み込みのテンプレートセグメントには "Paid_Search" のような短い ID があり、runReport の segmentIds に直接渡せます。

ユーザーが名前で存在しないセグメントを指定した場合は、まず aa-segment-builder スキルを使って作成するか、検索結果から最も近い既存のセグメントを提案してください。

制限：1 回の比較で使用できるセグメントは最大 4 個です。この制限は事前に伝えてください。

---

フェーズ 2 — 指標の選択

比較する指標をユーザーに尋ねます。バランスの取れた組み合わせを提案してください。

• ボリューム： metrics/visits
• エンゲージメント： metrics/pageviews、metrics/bouncerate、 metrics/pagespervisit
• コンバージョン： metrics/orders、計算指標として算出するコンバージョン率
• 収益： metrics/revenue

findMetrics を呼び出して各指標 ID を解決します。

findMetrics(expansions: "componentType,categories", page: 0, limit: 200)
# Filter locally by name. Key IDs: metrics/visits, metrics/revenue, metrics/orders, metrics/bouncerate

制限：指標は最大 6 個です。最終的な一覧をユーザーに確認します。

「5 つの指標について、3 つのセグメントを比較します。この場合、レポート呼び出しが 16 回必要です（3 セグメント × 5 指標 + 規模算出の呼び出し 1 回）。進めてもよいですか？」

---

フェーズ 3 — 期間の選択

分析期間を尋ねるか、確認します。

• 直近 7 日間（手早く比較する場合に適しています）
• 直近 30 日間（推奨されるデフォルト）
• 直近 90 日間（季節変動を平滑化する場合）
• カスタム期間

---

フェーズ 4 — 比較レポートの実行

4.1 セグメント規模（コンテキストのみ）

セグメントを指定しない metrics/visits の呼び出しを 1 回実行して全体の母集団規模を取得し、その後、各セグメントについて metrics/visits の呼び出しを 1 回ずつ実行し、全体に占める各セグメントの割合を算出します。これらの規模の値はコンテキストパネルに表示するものであり、比較マトリックスには使用しません。

runReport(
  dimensionId: "variables/page",
  metricIds: "metrics/visits",
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# allVisitorVisits = summaryData.totals[0]

runReport(
  dimensionId: "variables/page",
  metricIds: "metrics/visits",
  segmentIds: "<segmentId>",
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# segmentVisits = summaryData.totals[0]; shareOfTotal = segmentVisits / allVisitorVisits × 100

metrics/visits がすでに比較指標に含まれている場合は、その結果を再利用してください。

4.2 セグメントごと、指標ごとの処理

セグメント × 指標の組み合わせごとに、次を実行します。

runReport(
  dimensionId: "variables/page",
  metricIds: "<metricId>",          # note: "metricIds" not "metricId"
  segmentIds: "<segmentId>",        # note: "segmentIds" not "segmentId"
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# Total = summaryData.totals[0]

合計値は rows[] ではなく summaryData.totals[0] から読み取ってください。dimensionId は必須です。集計値を取得するには、limit: 1 を指定して任意のディメンションを使用してください。セグメント ID には findSegments の生の id フィールドを使用します。

進行状況を追跡します。「セグメント 2/3、指標 3/5 を取得中…」

---

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

マトリックスでは、セグメント同士を直接比較します。ベースライン列はありません。

各指標の行について、次の値を計算します。

計算値	数式
セグメント値	runReport の生データ
勝者	この指標で最良の値を持つセグメント
敗者	この指標で最悪の値を持つセグメント
差	(最大値 − 最小値) / 最大値 × 100
有意？	差 > 10% の場合は true

値が低いほど良い指標（直帰率、顧客獲得単価）では、 勝者と敗者の判定を逆にします。最も低い値のセグメントが 勝者です。これらの指標はレポート内で明確に示してください。

5.1 セグメントプロファイルの概要

各セグメントについて、全体的なパフォーマンスプロファイルを計算します。

• 勝利数： このセグメントが1位の指標数
• 敗北数： このセグメントが最下位の指標数
• 最大の優位性： このセグメントが他のセグメントを最も大きな差で上回る指標
• 訪問シェア： コンテキストパネルの総訪問数に占める割合

---

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

比較レポートをインラインで作成し、 /tmp/aa_segment_comparator_report_<YYYY-MM-DD_HHMMSS>.html に書き込みます。

HTML テンプレート

template.html を読み込み、そのまま使用してください。HTML 構造や CSS を独自に変更せず、 {PLACEHOLDER} トークン（{ORG_NAME}、 {DATE_RANGE}、{REPORT_SUITE}、{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}）を埋め込み、セグメントチップ、 マトリックスの行、インサイトボックスをデータ項目ごとに繰り返すだけにしてください。フェーズ 5 の勝者／敗者ルールに従い、 cell-winner／ cell-loser クラスを使用してください。

セクションタイトル — フェーズ番号なし： HTML レポート内のセクション見出しには、フェーズ番号を 含めないでください。セクション名のみを使用してください（例：「フェーズ 2 — セグメント比較」ではなく「セグメント比較」、 「フェーズ 3 — 指標の詳細」ではなく「指標の詳細」）。

/tmp/aa_segment_comparator_report_<YYYY-MM-DD_HHMMSS>.html に書き込み、開きます。

open /tmp/aa_segment_comparator_report_<YYYY-MM-DD_HHMMSS>.html

---

インラインの概要（必ず提示）

HTML レポートの後には、必ずテキストの概要を提示してください。

Segment Comparison — [Date Range] | Report Suite: [Name]

Segment Context:  Mobile 48,200 visits (38.7%)  Desktop 72,400 (58.2%)

                  Mobile   Desktop   Winner     Spread
────────────────  ───────  ────────  ─────────  ──────
Visits            48,200   72,400    Desktop    33%
Bounce Rate       61.4%    40.1% ✓  Desktop    35%  ✦
Conversion Rate    1.2%     3.1% ✓  Desktop    61%  ✦
Revenue           $9,400   $31,200   Desktop    70%  ✦

✦ = spread > 10%  ✓ = winner

Key findings:
- Desktop converts 2.6× better (3.1% vs 1.2%). Prioritize mobile checkout.
- Paid Search (not shown) has highest CVR at 4.8% — most efficient channel.

---

ガードレール

• 開始前に、セグメントと指標をユーザーに確認してください。呼び出し 回数は N×M となり、すぐに増える可能性があります。
• 直帰率などの「値が低いほど良い」指標では、勝者の判定を逆にし、 最も低い値のセグメントを勝者とします。レポート内でこれらの指標を 明確に示してください（例：「↓ 低いほど良い」）。
• セグメントの訪問数が非常に少ない場合（< 1,000）、結果の統計的信頼性が 低い可能性があることを記載してください。
• 比較マトリックスにベースラインとの差分率（セグメント対 All Visitors） を表示しないでください。セグメントは総母集団の一部であるため、 件数指標の差分は常にマイナスとなり、誤解を招きます。セグメントの規模には コンテキストパネルを使用してください。

---

やり取りの例

「コンバージョン指標について、モバイル訪問者とデスクトップ訪問者を比較してください。」

1. レポートスイートを確認します。
2. セグメントを探します：「モバイルデバイス」と「デスクトップ」（または作成を提案します）。
3. 指標を確認します：訪問数、直帰率、注文数、コンバージョン率、売上高。
4. 期間：過去30日間。
5. 事前確認：「2セグメント × 5指標 + 規模確認1回 = レポート11件です。続行しますか？」
6. すべてのレポートを実行し、進捗を知らせます。
7. コンテキスト：モバイル = 訪問数48.2k（38.7%）、デスクトップ = 訪問数72.4k（58.2%）。
8. マトリックス：デスクトップは5指標中3指標で勝利。コンバージョン率の差は61%。
9. HTML レポートを生成して開きます。
10. インサイト：「デスクトップは主要なコンバージョンエンジンです。モバイルは訪問数の 39%を占めますが、コンバージョン率は1.2%で、デスクトップの3.1%に対して61%の差があります。 コンバージョンを最も大きく伸ばせる機会として、モバイルのチェックアウト最適化を優先してください。」