campaign-analytics

营销活动分析

面向生产环境的营销活动效果分析工具,支持多触点归因建模、漏斗转化分析和 ROI 计算。三个 Python 命令行工具仅使用标准库即可提供确定性、可重复的分析结果——无外部依赖、无 API 调用、无机器学习模型。

---

输入要求

所有脚本都接受一个 JSON 文件作为位置参数。完整示例请参见 assets/sample_campaign_data.json。

归因分析器

{
  "journeys": [
    {
      "journey_id": "j1",
      "touchpoints": [
        {"channel": "organic_search", "timestamp": "2025-10-01T10:00:00", "interaction": "click"},
        {"channel": "email", "timestamp": "2025-10-05T14:30:00", "interaction": "open"},
        {"channel": "paid_search", "timestamp": "2025-10-08T09:15:00", "interaction": "click"}
      ],
      "converted": true,
      "revenue": 500.00
    }
  ]
}

漏斗分析器

{
  "funnel": {
    "stages": ["Awareness", "Interest", "Consideration", "Intent", "Purchase"],
    "counts": [10000, 5200, 2800, 1400, 420]
  }
}

营销活动 ROI 计算器

{
  "campaigns": [
    {
      "name": "Spring Email Campaign",
      "channel": "email",
      "spend": 5000.00,
      "revenue": 25000.00,
      "impressions": 50000,
      "clicks": 2500,
      "leads": 300,
      "customers": 45
    }
  ]
}

输入校验

运行脚本前,请确认 JSON 有效且符合预期结构。常见错误包括:

• 缺少必需键(例如 journeys、funnel.stages、campaigns)→ 脚本以描述性的 KeyError 退出
• 漏斗数据中数组长度不一致(stages 与 counts 长度必须相同)→ 抛出 ValueError
• ROI 数据中的货币值非数字→ 抛出 TypeError

在将文件传给任何脚本之前,可使用 python -m json.tool your_file.json 校验 JSON 语法。

---

输出格式

所有脚本都通过 --format 参数支持两种输出格式:

• --format text(默认):便于人工查阅的表格和摘要
• --format json:供集成和流水线使用的机器可读 JSON

---

典型分析工作流

要完成一次完整的营销活动复盘,请按顺序运行三个脚本:

# Step 1 — Attribution: understand which channels drive conversions
python scripts/attribution_analyzer.py campaign_data.json --model time-decay

# Step 2 — Funnel: identify where prospects drop off on the path to conversion
python scripts/funnel_analyzer.py funnel_data.json

# Step 3 — ROI: calculate profitability and benchmark against industry standards
python scripts/campaign_roi_calculator.py campaign_data.json

先利用归因结果识别表现最佳的渠道,然后将漏斗分析聚焦于这些渠道的细分人群,最后验证 ROI 指标,以确定预算重新分配的优先级。

---

使用方法

归因分析

# Run all 5 attribution models
python scripts/attribution_analyzer.py campaign_data.json

# Run a specific model
python scripts/attribution_analyzer.py campaign_data.json --model time-decay

# JSON output for pipeline integration
python scripts/attribution_analyzer.py campaign_data.json --format json

# Custom time-decay half-life (default: 7 days)
python scripts/attribution_analyzer.py campaign_data.json --model time-decay --half-life 14

漏斗分析

# Basic funnel analysis
python scripts/funnel_analyzer.py funnel_data.json

# JSON output
python scripts/funnel_analyzer.py funnel_data.json --format json

营销活动 ROI 计算

# Calculate ROI metrics for all campaigns
python scripts/campaign_roi_calculator.py campaign_data.json

# JSON output
python scripts/campaign_roi_calculator.py campaign_data.json --format json

---

脚本

1. attribution_analyzer.py

实现五种业界通用的归因模型,用于将转化功劳分配到各营销渠道:

模型	说明	适用场景
首次触点	首次互动获得 100% 功劳	品牌认知类营销活动
末次触点	末次互动获得 100% 功劳	直接响应类营销活动
线性	所有触点均分功劳	多渠道均衡评估
时间衰减	越近的触点获得越多功劳	销售周期较短的场景
位置加权	首次/中间/末次按 40/20/40 分配	全漏斗营销

2. funnel_analyzer.py

分析转化漏斗,识别瓶颈与优化机会:

• 阶段间转化率与流失百分比
• 自动识别瓶颈(绝对流失量与相对流失率最大的环节)
• 整体漏斗转化率
• 提供多个细分人群时进行细分对比

3. campaign_roi_calculator.py

计算全面的 ROI 指标,并附带行业基准对比:

• ROI:投资回报率百分比
• ROAS:广告支出回报率
• CPA:单次获客成本
• CPL:单条线索成本
• CAC:客户获取成本
• CTR:点击率
• CVR:转化率(线索到客户)
• 依据行业基准标记表现不佳的营销活动

---

参考指南

指南	位置	用途
归因模型指南	references/attribution-models-guide.md	深入解析 5 种模型的公式、优缺点及选择标准
营销指标基准	references/campaign-metrics-benchmarks.md	按渠道和行业划分的 CTR、CPC、CPM、CPA、ROAS 行业基准
漏斗优化框架	references/funnel-optimization-framework.md	分阶段优化策略、常见瓶颈与最佳实践

---

最佳实践

1. 使用多种归因模型 -- 至少比较 3 种模型,以综合判断渠道价值;单一模型无法反映全貌。
2. 设置合适的回溯窗口 -- 让时间衰减的半衰期与平均销售周期长度相匹配。
3. 细分转化漏斗 -- 按渠道、用户群组、地域等维度进行对比,找出影响表现的关键因素。
4. 优先与自身历史数据对比 -- 行业基准可提供参考背景,但历史数据才是最相关的对比对象。
5. 定期开展 ROI 分析 -- 活跃投放活动每周一次,战略复盘每月一次。
6. 计入全部成本 -- 在媒体投放费用之外,还需计入创意、工具和人工成本,才能得出准确的 ROI。
7. 严格记录 A/B 测试 -- 使用提供的模板,确保统计有效性并明确决策标准。

---

局限性

• 不进行统计显著性检验 -- 脚本仅提供描述性指标;p 值计算需借助外部工具。
• 仅使用标准库 -- 不依赖高级统计库。适用于大多数投放规模,但未针对超过 10 万条用户旅程的数据集进行优化。
• 离线分析 -- 脚本分析的是静态 JSON 快照;不支持实时数据连接或 API 集成。
• 单一货币 -- 默认所有金额均为同一种货币;不支持货币换算。
• 简化的时间衰减 -- 基于可配置半衰期的指数衰减;未考虑工作日/周末或季节性规律。
• 不支持跨设备追踪 -- 归因仅基于提供的用户旅程数据原样计算;跨设备身份识别需在上游处理。

相关 Skills

• analytics-tracking:用于配置追踪。不用于分析数据(数据分析由本 Skill 负责)。
• ab-test-setup:用于设计实验,以验证分析所揭示的结论。
• marketing-ops:用于将洞察分发给合适的执行类 Skill。
• paid-ads:用于根据分析结果优化广告投放支出。