cja-segment-performance-comparator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Segment Performance Comparator (Customer Journey Analytics)

细分群体性能对比工具（Customer Journey Analytics）

Compare 2–5 audience segments across a set of key metrics in a side-by-side matrix. The output tells the user not just what each segment looks like in isolation, but which segment wins or loses on each metric — and which differences are large enough to act on.

This skill answers the question "which audience should we focus on?" with data. Segment comparisons drive product decisions, personalization strategy, and budget allocation — so clarity and actionability matter more than exhaustive data.

可在并排矩阵中比较2–5个受众细分群体在一组关键指标上的表现。输出内容不仅会展示每个细分群体的独立表现，还会指出每个指标上表现最优和最差的细分群体，以及哪些差异大到足以采取行动。

此技能会用数据回答“我们应该关注哪个受众群体？”的问题。细分群体对比可推动产品决策、个性化策略和预算分配，因此清晰度和可操作性比详尽的数据更重要。

CJA MCP Tools Used

使用的CJA MCP工具

```
findSegments
```
— search for segments by name or keyword
```
describeSegment
```
— understand the logic of candidate segments before using them
```
findMetrics
```
— resolve base metric IDs
```
findCalculatedMetrics
```
— include custom KPIs in the comparison
```
listComponentUsage
```
— identify the most-used metrics as default comparison set
```
runReport
```
(with
```
segmentIds
```
or
```
adhocSegments
```
) — pull metric values per segment

```
findSegments
```
— 按名称或关键词搜索细分群体
```
describeSegment
```
— 在使用候选细分群体前了解其逻辑
```
findMetrics
```
— 解析基础指标ID
```
findCalculatedMetrics
```
— 在对比中纳入自定义KPI
```
listComponentUsage
```
— 识别最常用的指标作为默认对比集合
```
runReport
```
（搭配
```
segmentIds
```
或
```
adhocSegments
```
） — 提取每个细分群体的指标值

Phase 0 — Setup

阶段0 — 准备工作

Call
```
findDataViews
```
to list available data views.
If the user hasn't specified a data view, present the list and ask which to use.
Call
```
setDefaultSessionDataViewId
```
with the chosen ID.
Ask the user which segments to compare if not already specified. Confirm the metrics to compare them on.

调用
```
findDataViews
```
列出可用的数据视图。
如果用户未指定数据视图，列出选项并询问使用哪一个。
使用选定的ID调用
```
setDefaultSessionDataViewId
```
。
如果用户未指定要对比的细分群体，询问具体对象。确认用于对比的指标。

Phase 1 — Identify Segments to Compare

阶段1 — 确定要对比的细分群体

1.1 From user description

1.1 根据用户描述

If the user named specific segments, resolve them:

findSegments(search: "<segment name>")

For each match, call

describeSegment

to verify it is the correct one:

describeSegment(segmentId: "<id>")

Show the segment definition summary to the user if there is ambiguity:

"I found two segments matching 'mobile users': Mobile Visitors (All Devices) and Mobile App Users. Which do you want to compare?"

如果用户指定了具体的细分群体，解析它们：

findSegments(search: "<segment name>")

对于每个匹配结果，调用

describeSegment

验证是否为正确的细分群体：

describeSegment(segmentId: "<id>")

如果存在歧义，向用户展示细分群体定义摘要：

"我找到了两个匹配‘移动端用户’的细分群体：Mobile Visitors (All Devices)和Mobile App Users。您想要对比哪一个？"

1.2 From plain-English descriptions

1.2 根据自然语言描述

If the user says "compare mobile vs desktop users" but there are no matching segments, offer to create ad hoc segments inline for the comparison:

"I don't see pre-built segments for mobile and desktop. I can create temporary ad hoc segments for this comparison using device type. Should I proceed with ad hoc segments, or would you like to create permanent segments first?"

Ad hoc segments are constructed using

adhocSegments

runReport

— no save required for the comparison itself.

如果用户说“对比移动端与桌面端用户”但没有匹配的细分群体，可提供为对比创建临时细分群体的选项：

"我未找到移动端和桌面端的预构建细分群体。我可以使用设备类型为本次对比创建临时的adhoc segments。我应该继续创建临时细分群体，还是您想先创建永久细分群体？"

临时细分群体可通过

runReport

中的

adhocSegments

构建——对比本身无需保存这些细分群体。

1.3 Segment count limit

1.3 细分群体数量限制

Maximum 5 segments for a single comparison. More than 5 creates a matrix that is too wide to read meaningfully. If the user requests more, say:

"I'll limit to the 5 most relevant segments for readability. Would you like me to prioritize by usage count or stick with your list order?"

单次对比最多支持5个细分群体。超过5个会导致矩阵过宽，难以读取有效信息。如果用户请求更多，告知：

"为保证可读性，我将限制为5个最相关的细分群体。您希望按使用次数优先排序，还是保持您提供的列表顺序？"

Phase 2 — Identify Metrics to Compare

阶段2 — 确定要对比的指标

2.1 From user specification

2.1 根据用户指定

Resolve named metrics via

findMetrics

and

findCalculatedMetrics

通过

findMetrics

和

findCalculatedMetrics

解析指定的指标。

2.2 Default metric discovery

2.2 默认指标发现

If the user did not specify metrics, pull the top metrics by usage. The

listComponentUsage

tool does not support a

limit

parameter — it returns all components ranked by usage count; take the top 6–8 from the result:

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

Prefer calculated metrics over raw base metrics when they measure the same thing — calculated metrics reflect intentional KPI definitions.

如果用户未指定指标，提取使用量最高的指标。

listComponentUsage

工具不支持

limit

参数——它会返回所有按使用次数排序的组件；取结果中的前6–8个：

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

当计算指标与原始基础指标测量内容相同时，优先选择计算指标——计算指标反映了明确的KPI定义。

2.3 Metric selection for a comparison

2.3 对比指标选择

Good comparison metrics should be meaningful across all segments. For example, "Revenue" is meaningful for both mobile and desktop users; "App Installs" is only meaningful for mobile. Remove metrics that would be trivially zero for one segment.

If unsure, ask: "Should I use your standard KPI set, or focus on specific metrics like conversion rate, revenue, and engagement?"

优质的对比指标应在所有细分群体中都具有意义。例如，“收入”对移动端和桌面端用户都有意义；“应用安装量”仅对移动端有意义。移除对某个细分群体而言数值明显为零的指标。

如果不确定，询问：“我应该使用您的标准KPI集合，还是专注于转化率、收入和互动率等特定指标？”

Phase 3 — Run the Comparison

阶段3 — 执行对比

For each segment, run a

runReport

with that segment applied and all comparison metrics included. Note that

runReport

takes

metricIds

as a comma-separated string,

startDate

endDate

(not

dateRange

), and a

dimensionIds

(required even for summary-only reports — use a low-cardinality dimension like

variables/daterangeday

variables/web.webPageDetails.name

). The summary totals for all metrics are in

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>"
)

For ad hoc segments, use the full CJA segment definition object:

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"
      }
    }
  }]
)

Read metric totals from

summaryData.filteredTotals[i]

where

is the 0-based index of the metric in the

metricIds

string.

Run one report per segment. Collect all results into a matrix:

Rows = metrics
Columns = segments

针对每个细分群体，运行应用了该细分群体并包含所有对比指标的

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"
      }
    }
  }]
)

从

summaryData.filteredTotals[i]

中读取指标总数，其中

是

metricIds

字符串中指标的从零开始的索引。

为每个细分群体运行一次报表。将所有结果整理成矩阵：

行 = 指标
列 = 细分群体

Phase 4 — Build the Comparison Matrix

阶段4 — 构建对比矩阵

For each cell (metric × segment):

```
value[metric][segment]
```
= raw metric value from
```
runReport
```

For each metric row:

```
winner
```
= segment with the highest value (or lowest, for "lower is better" metrics)
```
loser
```
= segment with the lowest value (or highest, for inverse metrics)
```
range
```
= (max − min) / max × 100 — the spread across segments as a percentage
```
significant
```
= true if range > 10% (a meaningful difference worth acting on)

对于每个单元格（指标 × 细分群体）：

```
value[metric][segment]
```
= 来自
```
runReport
```
的原始指标值

对于每个指标行：

```
winner
```
= 指标值最高的细分群体（对于“越低越好”的指标则取最低值）
```
loser
```
= 指标值最低的细分群体（对于反向指标则取最高值）
```
range
```
= (最大值 − 最小值) / 最大值 × 100 — 细分群体间的差异百分比
```
significant
```
= 如果range > 10%则为true（差异足够大，值得采取行动）

Phase 5 — Generate HTML Comparison Report

阶段5 — 生成HTML对比报告

Generate the report inline and write to

/tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html

在线生成报告并写入

/tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html

。

HTML Template

HTML模板

Read

template.html

and use it verbatim. Do not improvise the HTML structure or CSS — only fill in the

{PLACEHOLDER}

tokens (

{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}

) and repeat segment chips, matrix rows, and insight boxes once per data item. Use the

cell-winner

cell-loser

classes per Phase 4 winner/loser rules.

读取

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}

），并根据数据项重复细分群体标签、矩阵行和洞察框。根据阶段4的胜负规则使用

cell-winner

cell-loser

类。

Phase 6 — Narrative Insights

阶段6 — 叙事性洞察

After building the matrix, generate 3–5 insight bullets for the Insights section:

Overall Winner: "Returning Visitors outperform New Visitors on 5 of 7 metrics, with the largest gap in Revenue per Session (+82%)."
Most Significant Difference: "The biggest gap is Conversion Rate: Mobile converts at 1.2% vs Desktop at 3.8% — a 68% gap worth prioritizing."
Surprising Parity: "New vs Returning Visitors show nearly identical Bounce Rates (42% vs 44%), suggesting landing page quality is consistent."
Actionable Signal: "Paid Search visitors have 2.3× higher Revenue per Session than Direct visitors — consider shifting budget toward Paid Search."
Anomaly: "One segment shows near-zero values across all metrics — verify that the segment definition is correct and matches the current data view."

Insights should be plain English, not metric IDs. Name the specific segments and metric values.

构建矩阵后，为洞察部分生成3–5条要点：

整体赢家：“回访访客在7个指标中的5个上表现优于新访客，其中‘每会话收入’的差距最大（+82%）。”
最显著差异：“最大差距在于转化率：移动端转化率为1.2%，桌面端为3.8%——68%的差距值得优先关注。”
意外持平：“新访客与回访访客的跳出率几乎相同（42% vs 44%），表明着陆页质量保持一致。”
可行动信号：“付费搜索访客的‘每会话收入’是直接访客的2.3倍——考虑将预算向付费搜索倾斜。”
异常情况：“某个细分群体的所有指标值几乎为零——请验证该细分群体的定义是否正确，且与当前数据视图匹配。”

洞察内容应使用通俗易懂的中文，而非指标ID。指明具体的细分群体和指标数值。

Workflow Summary

工作流程总结

Resolve 2–5 segments (by name or ad hoc definition).
Identify 5–8 comparison metrics (from user or top usage).
Run one
```
runReport
```
per segment with all metrics; collect results.
Build comparison matrix: rows = metrics, columns = segments.
Mark winner/loser per row; compute spread; flag significant differences.
Generate HTML report with matrix and insight bullets.

Write to

/tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html

Open with

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

Deliver inline summary: which segment wins overall, biggest gap metric, one actionable recommendation.

解析2–5个细分群体（按名称或临时定义）。
确定5–8个对比指标（来自用户或使用量最高的指标）。
为每个细分群体运行一次包含所有指标的
```
runReport
```
；收集结果。
构建对比矩阵：行 = 指标，列 = 细分群体。
标记每行的胜负方；计算差异幅度；标记显著差异。
生成包含矩阵和洞察要点的HTML报告。

写入

/tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html

。

使用

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

打开报告。

提供在线摘要：哪个细分群体整体表现最优，差距最大的指标，以及一条可行动建议。

Important Guardrails

重要约束规则

Read-only analysis. Never delete or modify segments or calculated metrics.
Always confirm segments before running. Ambiguous segment names (e.g., "Mobile" could be several) should be resolved by showing the user the matched segment IDs and definitions.
Use the same date range for all segments. Comparisons across different time windows are misleading.
Note overlap between segments. If two segments share substantial audience overlap, note it — the "difference" may be exaggerated.
Cap the number of segments compared. Comparing more than 5–6 segments in a single report makes the output unreadable; ask the user to prioritize.
Distinguish statistical significance from practical significance. A 0.1% difference is rarely actionable — focus on differences of 5%+ unless the user specifies otherwise.

只读分析。切勿删除或修改细分群体或计算指标。
运行前始终确认细分群体。名称模糊的细分群体（例如“Mobile”可能对应多个）应通过向用户展示匹配的细分群体ID和定义来解析歧义。
所有细分群体使用相同的日期范围。不同时间窗口的对比具有误导性。
注意细分群体之间的重叠。如果两个细分群体的受众重叠度很高，需注明这一点——“差异”可能被夸大。
限制对比的细分群体数量。单次报告中对比超过5–6个细分群体会导致输出内容难以阅读；请用户优先选择。
区分统计显著性与实际显著性。0.1%的差异几乎不具备可操作性——除非用户指定，否则专注于5%以上的差异。

Example Interaction

示例交互

"Compare our mobile vs. desktop segment performance for last quarter."

Setup: Confirm data view. Call
```
findDataViews
```
, user selects. Call
```
setDefaultSessionDataViewId
```
.
Segment resolution: Call
```
findSegments
```
to locate the "Mobile Users" and "Desktop Users" segments. Show matched names and IDs to confirm. User approves.
Metrics: Ask "Which metrics should I compare?" User: "Sessions, Conversion Rate, Revenue, and Average Order Value."
Analysis: Run
```
runReport
```
for Q1 2026 with both segments applied. Tabulate results side-by-side.
Findings: Mobile: 45% of sessions, 2.1% CVR, $0.84 RPV. Desktop: 55% of sessions, 4.8% CVR, $2.10 RPV. Desktop converts 2.3× better. Present a comparison table and 3 recommended next steps.

“对比我们上一季度移动端与桌面端细分群体的表现。”

准备工作：确认数据视图。调用
```
findDataViews
```
，用户选择后调用
```
setDefaultSessionDataViewId
```
。
细分群体解析：调用
```
findSegments
```
定位“Mobile Users”和“Desktop Users”细分群体。向用户展示匹配的名称和ID以确认。用户批准。
指标：询问“我应该对比哪些指标？”用户：“会话数、转化率、收入和平均订单价值。”
分析：针对2026年第一季度运行应用了两个细分群体的
```
runReport
```
。将结果并排制表。
结论：移动端：45%的会话数，2.1%的转化率，每会话收入0.84美元。桌面端：55%的会话数，4.8%的转化率，每会话收入2.10美元。桌面端转化率是移动端的2.3倍。展示对比表格和3条建议的后续步骤。