campaign-analytics

name	campaign-analytics
description	Analisa a performance de campanhas com atribuição multi-touch, análise de conversão do funil e cálculo de ROI para otimização de marketing. Use ao analisar campanhas de marketing, performance de anúncios, modelos de atribuição, taxas de conversão ou ao calcular ROI, ROAS, CPA e métricas de campanha entre canais.
license	MIT
metadata	{"version":"1.0.0","author":"Ric Neves - Flowgrammers","category":"marketing","domain":"campaign-analytics","updated":"2026-02-06T00:00:00.000Z","tech-stack":"marketing-analytics, attribution-modeling"}
agents	["claude-code"]

Analytics de Campanha

Análise de performance de campanhas com modelagem de atribuição multi-touch, análise de conversão do funil e cálculo de ROI de nível produção. Três ferramentas Python CLI fornecem analytics determinísticos e repetíveis usando apenas a biblioteca padrão — sem dependências externas, sem chamadas de API, sem modelos de ML.

---

Requisitos de Entrada

Todos os scripts aceitam um arquivo JSON como argumento de entrada posicional. Veja assets/sample_campaign_data.json para exemplos completos.

Attribution Analyzer

{
  "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 Analyzer

{
  "funnel": {
    "stages": ["Consciência", "Interesse", "Consideração", "Intenção", "Compra"],
    "counts": [10000, 5200, 2800, 1400, 420]
  }
}

Campaign ROI Calculator

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

Validação de Entrada

Antes de executar os scripts, verifique se seu JSON é válido e corresponde ao schema esperado. Erros comuns:

• Chaves obrigatórias ausentes (ex.: journeys, funnel.stages, campaigns) → script sai com um KeyError descritivo
• Comprimentos de array incompatíveis nos dados do funil (stages e counts devem ter o mesmo comprimento) → levanta ValueError
• Valores monetários não numéricos nos dados de ROI → levanta TypeError

Use python -m json.tool seu_arquivo.json para validar a sintaxe JSON antes de passar para qualquer script.

---

Formatos de Saída

Todos os scripts suportam dois formatos de saída via flag --format:

• --format text (padrão): Tabelas e resumos legíveis por humanos para revisão
• --format json: JSON legível por máquina para integrações e pipelines

---

Fluxo de Trabalho Típico de Análise

Para uma revisão completa de campanha, execute os três scripts em sequência:

# Passo 1 — Atribuição: entender quais canais impulsionam conversões
python scripts/attribution_analyzer.py campaign_data.json --model time-decay

# Passo 2 — Funil: identificar onde os prospects desistem no caminho para a conversão
python scripts/funnel_analyzer.py funnel_data.json

# Passo 3 — ROI: calcular lucratividade e comparar com benchmarks do setor
python scripts/campaign_roi_calculator.py campaign_data.json

Use os resultados de atribuição para identificar os canais de melhor desempenho, depois concentre a análise do funil nos segmentos desses canais, e por fim valide as métricas de ROI para priorizar a realocação de budget.

---

Como Usar

Análise de Atribuição

# Execute todos os 5 modelos de atribuição
python scripts/attribution_analyzer.py campaign_data.json

# Execute um modelo específico
python scripts/attribution_analyzer.py campaign_data.json --model time-decay

# Saída JSON para integração com pipeline
python scripts/attribution_analyzer.py campaign_data.json --format json

# Meia-vida personalizada para time-decay (padrão: 7 dias)
python scripts/attribution_analyzer.py campaign_data.json --model time-decay --half-life 14

Análise de Funil

# Análise básica do funil
python scripts/funnel_analyzer.py funnel_data.json

# Saída JSON
python scripts/funnel_analyzer.py funnel_data.json --format json

Cálculo de ROI de Campanha

# Calcular métricas de ROI para todas as campanhas
python scripts/campaign_roi_calculator.py campaign_data.json

# Saída JSON
python scripts/campaign_roi_calculator.py campaign_data.json --format json

---

Scripts

1. attribution_analyzer.py

Implementa cinco modelos de atribuição padrão do setor para alocar crédito de conversão entre canais de marketing:

Modelo	Descrição	Melhor Para
First-Touch	100% de crédito para a primeira interação	Campanhas de conscientização de marca
Last-Touch	100% de crédito para a última interação	Campanhas de resposta direta
Linear	Crédito igual para todos os pontos de contato	Avaliação equilibrada multi-canal
Time-Decay	Mais crédito para pontos de contato recentes	Ciclos de vendas curtos
Position-Based	Divisão 40/20/40 (primeiro/meio/último)	Marketing de funil completo

2. funnel_analyzer.py

Analisa funis de conversão para identificar gargalos e oportunidades de otimização:

• Taxas de conversão estágio a estágio e porcentagens de abandono
• Identificação automática de gargalos (maiores quedas absolutas e relativas)
• Taxa de conversão geral do funil
• Comparação de segmento quando múltiplos segmentos são fornecidos

3. campaign_roi_calculator.py

Calcula métricas abrangentes de ROI com benchmarking do setor:

• ROI: Porcentagem de retorno sobre investimento
• ROAS: Razão de retorno sobre o gasto em anúncios
• CPA: Custo por aquisição
• CPL: Custo por lead
• CAC: Custo de aquisição de cliente
• CTR: Taxa de cliques
• CVR: Taxa de conversão (leads para clientes)
• Sinaliza campanhas com desempenho abaixo dos benchmarks do setor

---

Guias de Referência

Guia	Local	Propósito
Guia de Modelos de Atribuição	references/attribution-models-guide.md	Mergulho profundo nos 5 modelos com fórmulas, prós/contras, critérios de seleção
Benchmarks de Métricas de Campanha	references/campaign-metricas-benchmarks.md	Benchmarks do setor por canal e vertical para CTR, CPC, CPM, CPA, ROAS
Framework de Otimização de Funil	references/funil-optimization-framework.md	Estratégias de otimização estágio por estágio, gargalos comuns, melhores práticas

---

Melhores Práticas

1. Use múltiplos modelos de atribuição — Compare pelo menos 3 modelos para triangular o valor do canal; nenhum modelo único conta a história completa.
2. Defina janelas de lookback apropriadas — Combine sua meia-vida de time-decay com o comprimento médio do seu ciclo de vendas.
3. Segmente seus funis — Compare segmentos (canal, coorte, geografia) para identificar drivers de performance.
4. Avalie o desempenho contra seu próprio histórico primeiro — Benchmarks do setor fornecem contexto, mas dados históricos são a comparação mais relevante.
5. Execute análise de ROI em intervalos regulares — Semanalmente para campanhas ativas, mensalmente para revisão.
6. Inclua todos os custos — Considere custos de criativo, ferramentas e mão-de-obra junto com o gasto em mídia para um ROI preciso.
7. Documente testes A/B rigorosamente — Use o template fornecido para garantir validade estatística e critérios de decisão claros.

---

Limitações

• Sem testes de significância estatística — Scripts fornecem apenas métricas descritivas; cálculos de valor-p requerem ferramentas externas.
• Somente biblioteca padrão — Sem bibliotecas estatísticas avançadas. Adequado para a maioria dos tamanhos de campanha, mas não otimizado para datasets acima de 100K jornadas.
• Análise offline — Scripts analisam snapshots JSON estáticos; sem conexões de dados em tempo real ou integrações de API.
• Moeda única — Todos os valores monetários assumidos na mesma moeda (BRL por padrão); sem suporte a conversão de moeda.
• Time-decay simplificado — Decaimento exponencial baseado em meia-vida configurável; não considera padrões de dia de semana/fim de semana ou sazonais.
• Sem rastreamento entre dispositivos — Atribuição opera nos dados de jornada fornecidos como estão; resolução de identidade entre dispositivos deve ser tratada upstream.

Skills Relacionadas

• analytics-tracking: Para configurar rastreamento. NÃO para analisar dados (isso é esta skill).
• ab-test-setup: Para projetar experimentos para testar o que o analytics revela.
• marketing-ops: Para rotear insights para a skill de execução correta.
• paid-ads: Para otimizar o gasto em anúncios com base nas descobertas do analytics.