campaign-analytics

キャンペーン分析

マルチタッチアトリビューションモデリング、ファネルコンバージョン分析、ROI 計算による、本番環境向けのキャンペーンパフォーマンス分析です。3 つの Python CLI ツールが標準ライブラリのみを使用して、決定論的で再現可能な分析を提供します。外部依存関係、API 呼び出し、ML モデルは不要です。

---

入力要件

すべてのスクリプトは、位置引数として 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 フラグで 2 種類の出力形式をサポートします。

• --format text（デフォルト）：確認用の、人が読みやすい表と要約
• --format json：連携やパイプライン向けの、機械可読な JSON

---

一般的な分析ワークフロー

キャンペーンを包括的にレビューするには、3 つのスクリプトを順に実行します。

# 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

業界標準の 5 つのアトリビューションモデルを実装し、マーケティングチャネル間でコンバージョンの貢献度を配分します。

モデル	説明	最適な用途
First-Touch	最初のインタラクションに 100% の貢献度を割り当てます	ブランド認知キャンペーン
Last-Touch	最後のインタラクションに 100% の貢献度を割り当てます	ダイレクトレスポンスキャンペーン
Linear	すべてのタッチポイントに均等な貢献度を割り当てます	バランスの取れたマルチチャネル評価
Time-Decay	最近のタッチポイントほど多くの貢献度を割り当てます	販売サイクルが短い場合
Position-Based	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連携はありません。
• 単一通貨 -- すべての金額は同一通貨とみなされます。通貨換算には対応していません。
• 簡易的な時間減衰 -- 設定可能な半減期に基づく指数減衰を使用しますが、平日・週末や季節のパターンは考慮しません。
• クロスデバイストラッキングなし -- アトリビューションは提供されたジャーニーデータをそのまま使用します。クロスデバイスのID解決は上流で行う必要があります。

関連スキル

• analytics-tracking：トラッキングの設定に使用します。データの分析には使用しません（その用途にはこのスキルを使用します）。
• ab-test-setup：アナリティクスで明らかになったことを検証する実験の設計に使用します。
• marketing-ops：インサイトを適切な実行スキルに振り分けるために使用します。
• paid-ads：アナリティクスの結果に基づく広告費の最適化に使用します。