campaign-analytics

キャンペーン分析

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

---

目次

• 機能
• 入力要件
• 出力形式
• 使い方
• スクリプト
• リファレンスガイド
• ベストプラクティス
• 制限事項

---

機能

• マルチタッチアトリビューション：設定可能なパラメーターを備えた 5 つのアトリビューションモデル（ファーストタッチ、ラストタッチ、線形、時間減衰、ポジションベース）
• ファネルコンバージョン分析：段階ごとのコンバージョン率、離脱の特定、ボトルネックの検出、セグメント比較
• キャンペーン 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 フラグで 2 つの出力形式をサポートしています。

• --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

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

モデル	説明	最適な用途
ファーストタッチ	最初の接点に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 値の計算に外部ツールが必要です。スクリプトが提供するのは記述的な指標のみです。
• 標準ライブラリのみ -- 高度な統計ライブラリやデータ処理ライブラリはありません。ほとんどのキャンペーン規模に適していますが、10 万件を超えるジャーニーのデータセット向けには最適化されていません。
• オフライン分析 -- スクリプトは静的な JSON スナップショットを分析します。リアルタイムのデータ接続や API 統合はありません。
• 単一通貨 -- すべての金額は同じ通貨であると仮定されます。通貨換算には対応していません。
• 簡易的な時間減衰 -- 設定可能な半減期に基づく指数減衰を使用します。平日・週末や季節的なパターンは考慮されません。
• デバイス間のトラッキングなし -- アトリビューションは、提供されたジャーニーデータをそのまま使用します。デバイス間の ID 解決は上流で処理する必要があります。

---

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

キャンペーン全体をレビューするには、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 指標を検証して予算再配分の優先順位を決めます。

---

入力の検証

スクリプトを実行する前に、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：分析結果に基づいたコンテンツの最適化に使用します。

---

トラブルシューティング

問題	考えられる原因	解決策
アトリビューションモデルで、すべての貢献度が1つのチャネルに割り当てられる	マルチチャネルのファネルで初回接触または最終接触を使用している	線形、減衰、またはポジションベースのアトリビューションに切り替えてください。実際のチャネル価値を把握するため、少なくとも3つのモデルを比較してください。2026年の推奨デフォルトは、GA4のデータドリブンアトリビューション（DDA）です
ファネルのコンバージョン率が非現実的に高い、または低い	ステージの定義が一致していない、またはカウント配列の長さに誤りがある	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、Eコマース（1～7日のサイクル）では --half-life 3 を使用してください
スクリプトの実行時に JSON の解析エラーが発生する	JSON の形式が正しくない、末尾にカンマがある、またはエンコーディングに問題がある	スクリプトに渡す前に、python -m json.tool your_file.json で 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：有料検索では最低4:1、有料ソーシャルでは3:1、メールチャネルでは30:1以上の ROAS（2026年の業界目標）を達成してください。ROAS が2:1を下回るキャンペーンには、直ちに最適化または予算の再配分が必要であることを明示してください
• 顧客獲得単価：チャネル全体の加重平均 CPA を45ドル未満（2026年の B2B SaaS 中央値）に維持してください。チャネル別の目標は、メールが15ドル未満、有料検索が50ドル未満、有料ソーシャルが40ドル未満、ディスプレイが75ドル未満です
• UTM の準拠状況：有料メディアおよびオウンドメディアのすべてのリンクで、UTM パラメーターの付与率100％を達成してください。小文字で統一された標準的な命名を使用してください（GA4 は大文字と小文字を区別します）。UTM の命名規則を標準化しているチームでは、アトリビューションの精度が29％向上しています
• 分析頻度：実施中のキャンペーンは毎週、戦略レビューは毎月、キャンペーン ROI 分析を実行してください。チャネル構成の変化に応じて、アトリビューションモデルを四半期ごとに更新してください
• ベンチマークの精度：すべてのキャンペーンを、一般的な平均値ではなく、チャネル固有のベンチマークと照らし合わせて評価してください。組み込みのベンチマーク表には、チャネル別の CTR、ROAS、CPA が、低・目標・高の範囲で記載されています

---

対象範囲と制限事項

対象範囲：

• 5 つの業界標準モデル（初回接点、最終接点、線形、時間減衰、ポジションベース）によるマルチタッチアトリビューションモデル
• ステージごとの指標、ボトルネックの検出、セグメント比較を含むファネルコンバージョン分析
• 10 以上の指標（ROI、ROAS、CPA、CPL、CAC、CTR、CVR、CPC、CPM、リードコンバージョン率）によるキャンペーン ROI の計算
• チャネル別の業界ベンチマークと、パフォーマンス不足のフラグ付け
• チャネルの内訳を含むポートフォリオレベルの概要

対象外：

• リアルタイムデータ接続や API 統合（スクリプトは静的な JSON スナップショットを分析します）
• A/B テストの統計的有意性検定（記述統計のみを対象とします。p 値の計算には専用の A/B テストツールを使用してください）
• クロスデバイスでの ID 解決（CDP または分析プラットフォームで事前に処理する必要があります）
• 通貨換算（すべての金額は同一通貨とみなします）
• 予測モデリングや予測（現在の分析は過去を対象とします）
• GA4 または HubSpot との直接統合（分析用に、これらのプラットフォームから JSON 形式でデータをエクスポートしてください）
• 100K 件を超えるジャーニーを含むデータセット（標準ライブラリによる実装であり、非常に大規模なデータセット向けには最適化されていません）

---

統合ポイント

統合	目的	接続方法
Google Analytics 4 (GA4)	ジャーニーおよびコンバージョンデータのソース	GA4 の探索レポートをエクスポートするか、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）	ダッシュボードでの可視化	3 つすべてのスクリプトで --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	time-decay モデルの半減期（日数）です。平均販売サイクルのおよそ半分に設定してください
--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、クリックからリードへの転換率 %、利益。各キャンペーンをチャネル固有のベンチマーク（低・目標・高）と照合し、パフォーマンスフラグと推奨事項を提示します。

出力: ポートフォリオの概要（合計、複合指標、最優秀キャンペーン、フラグ付きキャンペーン、チャネル別内訳）に加え、ベンチマーク評価、警告フラグ、実行可能な推奨事項を含むキャンペーンごとの詳細を表示します。