campaign-analytics

广告系列分析

面向生产环境的广告系列效果分析，提供多触点归因建模、漏斗转化分析和 ROI 计算。三个 Python CLI 工具仅使用标准库，提供确定且可重复的分析——无需外部依赖、API 调用或 ML 模型。

---

目录

• 功能
• 输入要求
• 输出格式
• 使用方法
• 脚本
• 参考指南
• 最佳实践
• 限制

---

功能

• 多触点归因：提供五种归因模型（首次触点、末次触点、线性、时间衰减、基于位置），并支持配置参数
• 漏斗转化分析：逐阶段转化率、流失识别、瓶颈检测和细分对比
• 广告系列 ROI 计算：提供 ROI、ROAS、CPA、CPL、CAC 指标，以及行业基准对比和表现不佳标记
• A/B 测试支持：结构化 A/B 测试文档和分析模板
• 渠道对比：跨渠道效果对比，并对指标进行归一化
• 高管报告：可直接使用的广告系列效果报告模板

---

输入要求

所有脚本都接受一个 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
    }
  ]
}

---

输出格式

所有脚本都可通过 --format 标志支持两种输出格式：

• --format text（默认）：便于阅读的表格和摘要，供审核使用
• --format json：机器可读的 JSON，适用于集成和流水线

---

请先确认

运行分析前，请确认以下输入。若有任何信息未知或含糊，请先询问——不要自行假设：

• 分析类型——归因、漏斗或 ROI（决定使用哪个工具以及生成哪种报告）
• 源数据——用户旅程触点／漏斗阶段计数／以 JSON 格式提供的广告系列支出和收入（分析所需的输入数据）
• 归因模型和半衰期——应与平均销售周期相匹配（会改变各渠道之间的归因分配）
• 用于基准对比的渠道和垂直行业——决定用于标记表现不佳情况的基准阈值

停止规则：只询问对输出影响最大的 2–3 项。如果用户表示“直接起草”，则继续处理，并在产出内容顶部列出所作假设。

使用方法

归因分析

# 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 分配（首次/中间/末次）	全漏斗营销

**AI 助手渠道：**建模前，如果触点的渠道标签是 GA4 的 ai-assistant 媒介，或者可选的 referrer、source 或 utm_source 字段匹配已知 AI 助手域名（chatgpt.com、chat.openai.com、perplexity.ai、gemini.google.com、claude.ai、copilot.microsoft.com、chat.deepseek.com、grok.com、meta.ai、chat.mistral.ai 等），则会将其重新归类为 ai_assistant。如果发现任何此类触点，摘要会报告 ai_assistant_reclassified。使用 --no-ai-reclassify 可保留原标签。

{"channel": "referral", "referrer": "https://chatgpt.com/", "timestamp": "2026-09-01T10:00:00"}

需注意的 AI 引荐数据缺口（截至 2026 年 9 月）：

• GA4 自 2026 年 5 月起提供默认的 AI Assistant 渠道（媒介为 ai-assistant），但不会追溯处理——较早的会话仍归类为 Referral。导出 referrer/source，以便此脚本重新归类这些会话。
• 来自 Google AI Overviews / AI Mode 的点击来自 google.com，会计入 Organic Search；不会重新归类。AI 功能的展示次数请使用 Search Console。
• 没有引荐来源（应用跳转、复制粘贴）的访问会归入 Direct，无法恢复——这会导致低估，而不是归零。
• campaign_roi_calculator.py 没有 ai_assistant 基准数据；会回退到 default 基准数据。

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 测试 -- 使用提供的模板，确保统计有效性和明确的决策标准。

---

限制

• 无法进行统计显著性检验 -- A/B 测试分析需要借助外部工具计算 p 值。脚本仅提供描述性指标。
• 仅使用标准库 -- 不含高级统计或数据处理库。适用于大多数规模的营销活动，但未针对超过 100K 次用户旅程的数据集进行优化。
• 离线分析 -- 脚本分析静态 JSON 快照，不支持实时数据连接或 API 集成。
• 仅支持单一货币 -- 假设所有货币金额使用同一货币，不支持货币转换。
• 简化的时间衰减 -- 基于可配置的半衰期使用指数衰减，不考虑工作日／周末或季节性模式。
• 不支持跨设备追踪 -- 归因会直接处理提供的用户旅程数据。跨设备身份解析必须在上游完成。

---

典型分析工作流

如需完整的营销活动复盘，请按顺序运行这三个脚本：

# 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 指标，以确定预算重新分配的优先顺序。

---

输入验证

运行脚本前，请确认 JSON 格式有效且符合预期的架构。常见错误：

• 缺少必需的键（例如 journeys、funnel.stages、campaigns）-- 脚本会以描述性 KeyError 退出
• 漏斗数据中的数组长度不匹配（stages 和 counts 长度必须相同）-- 会引发 ValueError
• ROI 数据中的货币值非数值 -- 会引发 TypeError

将文件传递给任何脚本前，请使用 python -m json.tool your_file.json 验证 JSON 语法。

相关技能

• marketing-demand-acquisition：用于规划由分析进行衡量的营销活动。
• social-media-analyzer：用于补充跨渠道分析的社交媒体专项分析。
• marketing-strategy-pmm：用于了解营销活动表现背后的战略背景。
• content-creator：用于根据分析结果优化内容。

---

故障排除

问题	可能原因	解决方案
归因模型将所有功劳都归于一个渠道	在多渠道漏斗中使用首次触点或末次触点归因	切换到线性、时间衰减或位置归因。至少比较 3 种模型，以综合判断渠道的真实价值。GA4 的数据驱动归因（DDA）是 2026 年推荐的默认选项
漏斗转化率高得或低得不切实际	阶段定义或计数不匹配，或计数数组长度错误	确认 stages 和 counts 数组长度相同，并按从上到下的顺序排列（计数最多的阶段在前）。确保计数代表各阶段的独立用户数，而非累计事件数
ROI 计算器将所有营销活动都标记为表现不佳	JSON 中的渠道名称与内置基准键不匹配	使用准确的渠道名称：email、paid_search、paid_social、display、organic_search、organic_social、referral、direct。无法识别的渠道会回退到 default 基准
时间衰减模型产生意外的功劳分配	半衰期参数与销售周期不匹配	将 --half-life 设为平均销售周期长度的一半左右。对于 B2B SaaS（周期为 60-90 天），使用 --half-life 30。对于电商（周期为 1-7 天），使用 --half-life 3
脚本执行时出现 JSON 解析错误	JSON 格式错误、存在尾随逗号或编码问题	在将 JSON 传递给任何脚本之前，使用 python -m json.tool your_file.json 验证。确保采用 UTF-8 编码且不含 BOM 字符
GA4 归因数据与脚本输出不一致	回溯窗口和模型默认值不同	GA4 默认使用 30 天的获客回溯窗口和 90 天的互动回溯窗口。当某个关键事件的转化次数少于 400 次时，DDA 会回退到末次点击归因。调整脚本的 --half-life 和数据窗口，使其与 GA4 设置一致
营销活动支出数据显示 ROI 为零，但有转化	输入 JSON 中缺少收入字段或该字段值为零	确保每个营销活动对象都包含 revenue 字段，并填入实际归因收入。如果没有收入归因数据，请根据平均交易金额乘以客户数估算收入

---

成功标准

• 归因模型覆盖率：每个分析周期至少运行 3 种归因模型，以综合判断渠道价值。对于混合型 PLG/销售主导模式，建议将位置归因（40/20/40）或 GA4 数据驱动归因作为主要模型
• 漏斗转化率：B2B SaaS 的整体漏斗转化率（从顶部到底部）目标为 2-5%，B2C 为 5-15%。将任何流失率 >60% 的单一阶段识别为关键瓶颈并加以解决
• 营销活动 ROAS：付费搜索的 ROAS 至少达到 4:1，付费社交至少达到 3:1，邮件渠道至少达到 30:1（2026 年行业目标）。将 ROAS 低于 2:1 的营销活动标记出来，立即进行优化或重新分配预算
• 单次获客成本：将各渠道的综合 CPA 控制在 $45 以下（2026 年 B2B SaaS 中位数）。渠道目标：邮件 <$15、付费搜索 <$50、付费社交 <$40、展示广告 <$75
• UTM 合规性：所有付费媒体和自有媒体链接的 UTM 参数覆盖率达到 100%。使用小写字母和标准化命名（GA4 区分大小写）。采用标准化 UTM 规范的团队，其归因准确率可提高 29%
• 分析频率：活跃营销活动每周进行 ROI 分析，战略审查每月进行。随着渠道组合的变化，每季度更新归因模型
• 基准准确性：所有营销活动都应根据渠道专属基准评估，而非通用平均值。内置基准表按渠道提供 CTR、ROAS 和 CPA 的低位、目标和高位范围

---

范围与限制

涵盖范围：

• 使用 5 种行业标准模型（首次触达、末次触达、线性、时间衰减、基于位置）进行多触点归因建模
• 漏斗转化分析，包含逐阶段指标、瓶颈检测和细分比较
• 营销活动 ROI 计算，包含 10 多项指标（ROI、ROAS、CPA、CPL、CAC、CTR、CVR、CPC、CPM、潜在客户转化率）
• 按渠道进行行业基准对比，并标记表现不佳的渠道
• 提供包含渠道细分的整体汇总

不在范围内：

• 实时数据连接或 API 集成（脚本分析静态 JSON 快照）
• A/B 测试的统计显著性检验（仅提供描述性指标；如需计算 p 值，请使用专用的 A/B 测试工具）
• 跨设备身份解析（必须由上游的 CDP 或分析平台处理）
• 货币转换（假设所有货币值使用相同币种）
• 预测建模或预测（当前分析基于历史数据）
• 直接集成 GA4 或 HubSpot（请从这些平台导出数据为 JSON 格式进行分析）
• 超过 100K 条旅程的数据集（使用标准库实现，未针对超大型数据集优化）

---

集成点

集成	用途	连接方式
Google Analytics 4 (GA4)	旅程和转化数据源	导出 GA4 Exploration 报告，或使用 BigQuery 导出生成旅程 JSON。GA4 的 DDA 模型（2026 年的默认模型）可与此工具的 5 种模型互为补充。统一回溯窗口：GA4 默认采用 30 天获客窗口 / 90 天互动窗口
HubSpot	CRM 归因、潜在客户评分、交易数据	将带有 UTM 参数的 HubSpot 联系人旅程数据导出为 JSON 输入。对于混合 PLG/销售模式，请使用 W 型（40-20-40）归因。将 HubSpot 生命周期阶段映射到漏斗分析器阶段
UTM 参数标准	统一营销活动标记	统一使用小写 UTM 值：utm_source={channel}、utm_medium={type}、utm_campaign={campaign-id}、utm_content={variant}、utm_term={keyword}。GA4 会将 Email 和 email 视为不同条目
social-media-analyzer skill	社交渠道表现数据	将 calculate_metrics.py 中的社交媒体营销活动指标输入 campaign_roi_calculator.py，以比较跨渠道 ROI
marketing-demand-acquisition skill	需求生成营销活动规划	使用归因结果识别表现最佳的渠道，再将洞察用于需求生成预算分配决策
商业智能工具（Looker、Tableau、Power BI）	仪表板可视化	使用这三个脚本的 --format json 输出，直接导入 BI 工具。JSON 输出采用结构化格式，便于转换
电子表格工具（Excel、Google Sheets）	手动分析和报告	使用 --format text 输出可读报告。将 JSON 输出复制到电子表格中，进行自定义透视分析

---

工具参考

attribution_analyzer.py

类型： 使用 argparse 的 CLI 脚本

用法：

python attribution_analyzer.py <input_file> [--model MODEL] [--half-life DAYS] [--format FORMAT]

标志	必填	默认值	描述
input_file	是	--	包含旅程/触点数据的 JSON 文件路径。必须包含顶层 journeys 数组
--model	否	全部 5 种模型	运行指定模型：first-touch、last-touch、linear、time-decay、position-based
--half-life	否	7.0	时间衰减模型的半衰期（天）。设为接近平均销售周期一半的值
--format	否	text	输出格式：text（人类可读的表格）或 json（机器可读）

输入模式： {"journeys": [{"journey_id": "str", "touchpoints": [{"channel": "str", "timestamp": "ISO-8601", "interaction": "str"}], "converted": bool, "revenue": float}]}

输出： 汇总统计信息（旅程总数、转化率、总收入、观测到的渠道），以及按模型划分的渠道归因分配，包括收入和占比。当运行所有模型时，还会提供跨模型比较表。

funnel_analyzer.py

类型： 使用 argparse 的 CLI 脚本

用法：

python funnel_analyzer.py <input_file> [--format FORMAT]

标志	必填	默认值	描述
input_file	是	--	包含漏斗数据的 JSON 文件路径。必须包含 funnel（单个漏斗）或 segments（多个细分）键
--format	否	text	输出格式：text 或 json

单个漏斗输入： {"funnel": {"stages": ["Stage1", "Stage2", ...], "counts": [10000, 5200, ...]}}

多个细分输入： {"stages": ["Stage1", "Stage2", ...], "segments": {"segment_a": {"counts": [...]}, "segment_b": {"counts": [...]}}}

输出： 各阶段转化率、流失数量和百分比、累计转化率、瓶颈识别（包括绝对值和相对值），以及比较多个细分时的细分排名。

campaign_roi_calculator.py

类型： 使用 argparse 的 CLI 脚本

用法：

python campaign_roi_calculator.py <input_file> [--format FORMAT]

标志	必填	默认值	描述
input_file	是	--	包含营销活动数据的 JSON 文件路径。必须包含顶层 campaigns 数组
--format	否	text	输出格式：text 或 json

输入模式： {"campaigns": [{"name": "str", "channel": "str", "spend": float, "revenue": float, "impressions": int, "clicks": int, "leads": int, "customers": int}]}

用于基准比较的可识别渠道： email、paid_search、paid_social、display、organic_search、organic_social、referral、direct。无法识别的渠道使用 default 基准。

计算指标： ROI %、ROAS、CPA、CPL、CAC、CTR %、CVR %（潜在客户到客户）、CPC、CPM、点击到潜在客户转化率 %、利润。每个营销活动都会根据渠道专属基准（低/目标/高）进行评估，并提供绩效标记和建议。

输出： 投资组合摘要（总计、综合指标、表现最佳者、已标记的营销活动、渠道明细），以及每个营销活动的详细信息，包括基准评估、警告标记和可执行建议。