P3.2 · Integrar o Google Ads

Depende de P0.3. Skill: `/google-ads`.

O prompt

Leia a skill /google-ads. Já existe o servidor MCP próprio mcp-google-ads rodando no cluster, com escrita. Reaproveite as credenciais dele, não crie outra integração OAuth.

1. Descoberta

Com list_accessible_customers e run_gaql, levante e grave em ads/google/conta.yaml:

• customer_id, nome, moeda, fuso
• Se é conta gerenciada por MCC e qual
• Ações de conversão já configuradas, com status e contagem recente
• Campanhas existentes, para não colidir
• Orçamentos e estratégias em uso

Se houver mais de uma conta, pergunte.

copiarSELECT customer.id, customer.descriptive_name, customer.currency_code,
       customer.time_zone, customer.manager
FROM customer

SELECT conversion_action.id, conversion_action.name, conversion_action.type,
       conversion_action.category, conversion_action.status,
       conversion_action.primary_for_goal
FROM conversion_action

2. Ampliar o mcp-google-ads

O servidor não tem as ferramentas de conversão. Sem elas o Google otimiza no escuro. Adicione, seguindo o padrão do servidor existente — mesma estrutura de tool, mesmo tratamento de erro, mesmo carregamento de credencial:

create_conversion_action — cria a ação de conversão pela API, em vez de pela interface.

upload_offline_conversion — ConversionUploadService.UploadClickConversions:

• gclid, ou wbraid / gbraid para tráfego iOS
• conversion_action como resource name
• conversion_date_time com fuso, no formato exato que a API exige — este campo é a causa número um de erro aqui
• conversion_value, currency_code
• order_id — o id da assinatura na Stripe, que permite ajuste e estorno depois

upload_enhanced_conversion — para quem chega sem click id. UserIdentifier com e-mail e telefone em hash SHA-256.

adjust_offline_conversion — ConversionAdjustmentUploadService, para estorno e para corrigir valor quando o cliente vira Hub.

Suba pelo pipeline do mcp-google-ads, não manualmente.

3. Ações de conversão a criar

Janela de conversão de 90 dias — o ciclo com vendedor é longo e a janela padrão de 30 dias corta metade das conversões.

Hub assinado precisa ser a conversão primária das campanhas de fundo de funil.

4. Cliente no radar

Módulo ads/google/client.py com a mesma disciplina do cliente da Meta: versão da API fixada, backoff, log estruturado, dry_run de primeira classe, erros traduzidos.

Atenção a cost_micros: é micros. Dividir por 10.000 dá centavos. Escreva o teste com valores de borda — errar isso por um fator de 100 no painel já aconteceu em muito projeto.

5. Tagging nas landings

• Global site tag com o conversion_id da conta
• Conversões aprimoradas ativadas, enviando e-mail e telefone em hash no momento da conversão
• gclid, wbraid e gbraid capturados pelo middleware de P0.3

6. Health check

Comando google_diagnostico: credencial válida, conta ativa, ações de conversão recebendo dados nas últimas 72h, percentual de conversões com click id, campanhas com aprendizado em andamento.

Critérios de aceite

1. ads/google/conta.yaml com dados reais, confirmados comigo
2. As quatro ferramentas novas no mcp-google-ads, com teste unitário cada
3. As três ações de conversão criadas, visíveis na interface do Google Ads
4. Teste de cost_micros para centavos com valores de borda
5. google_diagnostico verde
6. Global site tag e conversões aprimoradas ativas nas três landings