# Google Ads + Retail Partner — runbook de ativação

Atualizado em 24 de agosto de 2026.

## Resultado esperado

O desenho de mensuração usa quatro camadas com responsabilidades diferentes:

1. O portal envia page view, catálogo, produto, carrinho, início do checkout, pedido enviado e lead verificado pelo navegador, sempre sob Consent Mode v2.
2. O app oficial Google & YouTube da Shopify é a fonte de `purchase` para pagamentos Card no checkout hospedado.
3. O backend mantém atribuição consentida e uma fila idempotente para `qualify_lead` e, quando habilitado, `offline_purchase` exclusivamente para ACH, Wire e Invoice no GA4 Measurement Protocol.
4. Enhanced Conversions for Leads deve ser ativado separadamente no Google Ads Data Manager. O evento GA4 `qualify_lead` não substitui esse upload.

Não existe configuração capaz de observar 100% dos usuários. Recusa de consentimento, bloqueadores, ITP e perda de sinal entre dispositivos continuam existindo; o Consent Mode permite sinais sem cookies e modelagem dentro das regras do Google.

## Governança das conversões

| Etapa | Origem | Uso inicial no Google Ads | Regra de deduplicação |
| --- | --- | --- | --- |
| Compra Card paga (`purchase`) | App Google & YouTube da Shopify | Primary | Exclusiva de Card; `transaction_id` nativo da Shopify |
| Compra ACH/Wire/Invoice paga (`offline_purchase`) | GA4 Measurement Protocol do portal | Primary separada após validação | Nunca aceita Card; delivery/event key idempotente e `transaction_id=VM-OFFLINE-{order_id}` |
| Pedido enviado (`order_submitted`) | Portal | Secondary | `event_id`/número do pedido; nunca representa receita paga |
| Lead com e-mail verificado (`generate_lead`) | Portal | Secondary | Uma vez por aplicação verificada |
| Parceiro aprovado (`qualify_lead`) | GA4 MP para análise; Data Manager para Ads | Secondary até ECL ser validado | Chave idempotente da aplicação e decisão atual de consentimento |
| Reembolso (`refund`) | Reconciliação opcional | Secondary/auditoria | Mesmo `transaction_id` da compra; ajuste Ads é uma operação externa |

Não coloque duas etapas do mesmo funil como Primary ao mesmo tempo. Depois de validar volume e qualidade, escolha uma única etapa de otimização: compra paga ou lead realmente qualificado. Microconversões continuam Secondary.

ACH, Wire e Invoice são transformados em pedido Shopify com pagamento pendente pelo backend; o pagamento pode ser confirmado posteriormente sem o comprador abrir a página de agradecimento. Por isso, quando o toggle específico estiver ativo, o evento durável `PaymentConfirmed` gera `offline_purchase`. O ID `VM-OFFLINE-{order_id}` usa apenas a chave primária local imutável, não contém PII, independe do formato privado da Shopify e fica congelado no pedido. A seleção por método é excludente: Card gera somente `purchase`; os outros três métodos geram somente `offline_purchase`.

Antes de habilitar essa rota, crie `offline_purchase` como Key Event no GA4 e importe-o no Google Ads como uma ação de categoria Purchase Primary separada. Mantenha a Purchase Shopify de Card também Primary: não há dupla contagem porque os conjuntos de métodos são disjuntos. Configure contagem **Every** nas duas compras e **One** nas ações de lead. Refunds continuam fora do novo toggle e permanecem sob a reconciliação opcional existente; ajuste de conversão no Ads exige processo próprio.

`offline_purchase` é deliberadamente um evento customizado: ele preserva valor, moeda, itens e transaction ID para análise e bidding, mas não deve ser confundido com o evento recomendado `purchase` nos relatórios padrão de monetização do GA4. Relatórios operacionais devem comparar cada fonte pelo método de pagamento.

## Dados e acessos necessários

- Conta Google Ads e Customer ID.
- Propriedade GA4, fluxo Web e Measurement ID `G-...`.
- Container GTM publicado `GTM-...`, se este for o modo escolhido.
- Google tag/Ads ID `AW-...`.
- Ações de conversão e labels do pedido enviado e lead, quando o modo direto for usado.
- Acesso administrativo ao canal Google & YouTube da loja Shopify.
- Conta Merchant Center vinculada, caso produtos sejam anunciados.
- API secret do GA4 Measurement Protocol, se `qualify_lead` ou `offline_purchase` server-side for habilitado.
- Storefront API public access token de 32 caracteres e checkout em domínio customizado com a mesma raiz, se a Customer Privacy API da Shopify for habilitada.
- URLs públicas HTTPS de Privacy, Terms, Shipping e Returns/Refunds.

Segredos não devem ser enviados por e-mail, Slack ou commitados. O API secret e o token privado do feed são armazenados criptografados pelo painel.

## Configuração no painel Vida Mansa

Acesse **Admin → Settings → Google Ads & Retail**.

1. Preencha os IDs, mas mantenha a chave mestra desligada.
2. Escolha GTM ou Google tag direta. Não instale os dois para os mesmos destinos.
3. Habilite Consent Mode v2.
4. Configure os domínios controlados da jornada, sem protocolo ou caminho.
5. Se Shopify Customer Privacy estiver ativa, informe somente o token Storefront público; nunca um token Admin API.
6. Configure GA4 Measurement Protocol e seu segredo somente depois de criar o fluxo correto.
7. Mantenha a reconciliação de Card/reembolso desligada até descobrir, em um pedido Card pago real, o `transaction_id` exato enviado pela Shopify.
8. Para não-Card, crie/importe a Key Event `offline_purchase` e só então habilite o toggle exclusivo de ACH/Wire/Invoice.
9. Se usar Merchant, escolha uma única fonte: app Shopify ou feed customizado.
10. Revise todos os cartões de diagnóstico e só então ligue a chave mestra.

O contrato de privacidade é fail-closed. `GOOGLE_CONSENT_COLLECTION_ENABLED` controla o consentimento e o beacon interno independentemente da chave das tags; ele exige `GOOGLE_TRACKING_PRIVACY_URL` com uma URL pública HTTPS. Se a coleta estiver desabilitada ou essa URL não for válida, o portal não emite nonce, não registra visita/atribuição e não carrega tags Google. Isso deve ser corrigido na configuração, nunca contornado no GTM.

Em produção, mantenha o scheduler Laravel executando a cada minuto e um worker supervisionado para a fila `default`. Sem esses dois processos, recuperação e entregas server-side permanecem armazenadas, mas não chegam ao GA4. Monitore também falhas e reinícios desses processos.

## Contrato do Google Tag Manager

O portal já inicializa o consentimento como denied antes do GTM e só libera a carga após reconciliar o estado atual. No container:

1. Crie uma única Google tag e um Conversion Linker.
2. Não crie outro comando de Consent Mode default.
3. Configure GA4 com `send_page_view=false`.
4. Dispare exatamente um `page_view` no custom event `vm_consent_ready`.
5. Crie tags GA4 Event para os eventos ecommerce presentes no `dataLayer`.
6. Limpe `ecommerce` antes de cada evento; o portal já envia esse reset.
7. Mapeie `user_data` somente para a tag aplicável de Enhanced Conversions. O portal não o inclui sem consentimento Ads.
8. Configure `order_submitted` e `generate_lead` como conversões Secondary.
9. Não crie uma tag Purchase do portal. A Purchase paga pertence ao canal oficial da Shopify.
10. Crie uma tag **Google Ads Remarketing separada** para eventos de produto, carrinho e checkout. Mapeie `ecommerce.items[].id`, mantenha `google_business_vertical=retail`, envie `value`/moeda quando disponíveis e vincule Ads↔Merchant.
11. Valide essa tag em Preview/Tag Assistant e confirme a fonte em Ads → Audience Manager → Your data sources; ela não deve ser uma tag de conversão Purchase.
12. Vincule GA4↔Google Ads, habilite auto-tagging, importe somente as Key Events deliberadas e revise account-default goals para excluir page views, carrinho, checkout e outras microconversões do Smart Bidding.
13. Configure contagem **Every** para `purchase`/`offline_purchase` e **One** para leads.
14. Publique somente após Preview/Tag Assistant sem tags duplicadas.

Eventos client-side disponíveis: `page_view`, `view_item_list`, `select_item`, `view_item`, `add_to_cart`, `remove_from_cart`, `view_cart`, `wholesale_begin_checkout`, `wholesale_add_payment_info`, `order_submitted` e `generate_lead`. Os dois eventos `wholesale_*` identificam a etapa própria do portal; não os renomeie para eventos nativos da Shopify sem antes provar que isso não duplica o funil do checkout hospedado.

## Shopify, Purchase e cross-domain

1. Instale/conecte o app oficial Google & YouTube na Shopify e vincule as mesmas contas Ads, GA4 e Merchant.
2. Aceite os termos de Customer Data/Enhanced Conversions aplicáveis na conta Google.
3. Use um domínio customizado de checkout sob a mesma raiz do portal.
4. Valide que a escolha de consentimento aparece igual no portal e no checkout.
5. Faça um pedido de teste pago e registre no DebugView/Tag Assistant o `transaction_id` nativo.
6. Confirme uma única Purchase com o valor e moeda corretos.
7. Procure e remova Google tags antigas em theme, custom pixel, GTM ou integrações legadas.
8. Só habilite a reconciliação Card server-side se o ID local selecionado for idêntico ao ID nativo observado. Mantenha essa reconciliação como Secondary.
9. No GA4, marque `offline_purchase` como Key Event. No Ads, importe-a como ação Purchase Primary separada, com Count=Every e inclusão nos goals de compra aplicáveis.
10. Execute um pagamento real controlado por ACH, Wire e Invoice e confirme exatamente um `offline_purchase` com `VM-OFFLINE-{order_id}`, valor, moeda e itens corretos. Confirme também que nenhum pedido Card emite esse evento.

## Enhanced Conversions for Leads / Data Manager

O backend preserva, sob consentimento, GCLID/GBRAID/WBRAID, UTMs, IDs GA e dados normalizados com hash em snapshots imutáveis. O envio atual de `qualify_lead` é GA4 Measurement Protocol e serve para análise no GA4.

Para transformar parceiro aprovado em sinal de bidding:

1. Crie a ação de conversão de lead qualificado no Google Ads.
2. Configure Enhanced Conversions for Leads no Data Manager e aceite os termos.
3. Para integrações novas a partir de 15 de junho de 2026, use a Data Manager API; não inicie uma integração nova no fluxo legado da Google Ads API.
4. Envie dados diariamente e de forma consistente.
5. Respeite as janelas: até 90 dias para GCLID e até 63 dias para dados fornecidos pelo usuário.
6. Use a chave idempotente da aplicação para impedir uploads duplicados.
7. Valide diagnósticos e match rate antes de tornar a ação Primary.
8. Se Purchase tiver volume suficiente, mantenha lead qualificado como Secondary e otimize pela receita paga.

O conector externo não deve ser ativado sem Customer ID, ação de conversão, credenciais OAuth/service account, termos aceitos e autorização formal para os dados utilizados.

O comando diário `google:prune-attribution-identifiers` aplica essas janelas separadamente: `GOOGLE_ATTRIBUTION_IDENTIFIER_RETENTION_DAYS=90` remove identificadores de atribuição e encerra o ledger de consentimento expirado; `GOOGLE_USER_DATA_SNAPSHOT_RETENTION_DAYS=63` suprime entregas ainda pendentes e limpa snapshots/fingerprints potencialmente derivados de `user_data`. Entregas em `sending` nunca são alteradas pelo prune; o sweep deve primeiro encerrá-las em um estado terminal.

## Merchant Center: bloqueio comercial atual

O feed técnico não torna a operação elegível automaticamente. As páginas públicas de produto exibem preço, mas o checkout público permanece fechado por padrão com `OPEN_WHOLESALE_CHECKOUT=false`, e a paridade B2B ainda não foi comprovada de ponta a ponta. Portanto, Shopping/PMax com feed deve permanecer desligado até que elegibilidade, checkout e paridade sejam validados em produção.

Antes do go-live:

- Googlebot e comprador devem ver o mesmo produto, preço, moeda, disponibilidade e condição.
- A landing não pode exigir login para revelar os dados anunciados nem usar preço diferente do feed.
- O checkout anunciado deve estar realmente disponível ao público; habilite `OPEN_WHOLESALE_CHECKOUT=true` somente depois da aprovação comercial e valide a jornada anônima completa.
- Frete, impostos, devolução/reembolso e privacidade precisam estar públicos e coerentes.
- O pedido mínimo de US$ 150 precisa estar configurado no Merchant Center e claro na landing/checkout.
- Confira pelo menos três variantes reais: ID, URL, preço e estoque.
- Use apenas uma fonte primária de catálogo. Não mantenha app Shopify e feed customizado publicando os mesmos itens.

Se o modelo comercial não puder mostrar preço e compra publicamente, use Search/YouTube/PMax sem feed para geração de Retail Partner leads, em vez de tentar contornar a política com cloaking.

## Matriz obrigatória de QA

Execute em produção com usuário/teste controlado:

- Primeira visita sem escolha: tags em denied, banner visível e nenhuma cookie analítica criada.
- Accept all: GA/Ads granted, um page view e eventos ecommerce sem duplicidade.
- Analytics only: GA granted, Ads/user data denied e nenhum click ID persistido para Ads.
- Essential only: cookies GA/Ads removidas e nenhum dado interno de visita materializado.
- Revogação depois de grant: ledger atualizado, entrega pendente suprimida e nenhuma resposta antiga reativa consentimento.
- Navegação para Shopify: `_gl` decorado quando aplicável e consentimento preservado.
- Pedido enviado sem pagamento: apenas `order_submitted`, sem Purchase.
- Pedido Card pago: exatamente uma `purchase` da Shopify, com valor/moeda/transaction ID corretos, e nenhum `offline_purchase`.
- ACH/Wire/Invoice pagos posteriormente: exatamente um `offline_purchase`, sem depender de página de agradecimento, usando `VM-OFFLINE-{order_id}` e sem `purchase` nativa do portal.
- Lead verificado e aprovado: um evento de cada etapa, sem PII em `dataLayer` ou logs.
- Bloqueadores/JavaScript indisponível: jornada comercial continua funcional; mensuração pode ficar ausente.
- Reenvio de webhook, refresh e retry de fila: nenhuma conversão duplicada.
- Dynamic remarketing: tag Ads separada dispara em produto/carrinho/checkout com IDs Merchant compatíveis, vertical retail e value; Audience Source e Tag Assistant não mostram erro.
- Goals: vínculo GA4↔Ads e auto-tagging ativos, compras em Count=Every, leads em Count=One e microconversões fora dos account-default goals de bidding.

Valide também `/debug/mp/collect` com `validation_behavior=ENFORCE_RECOMMENDATIONS`; depois confirme um evento controlado no GA4 Realtime/DebugView. HTTP 2xx confirma transporte, não ingestão.

## Operação e rollback

- Monitore diagnósticos de tag, conversões, Merchant e fila diariamente na primeira semana.
- Compare Card pago versus Purchase Shopify e não-Card pago versus `offline_purchase`, sempre por método, `transaction_id`, valor e moeda.
- Compare aplicações aprovadas versus uploads ECL por chave idempotente.
- Não reenvie automaticamente um evento quando o resultado HTTP ficou desconhecido; reconcilie manualmente para evitar duplicata.
- Em anomalia, desligue a chave mestra do portal. Isso não desliga o app Shopify; pause a ação/tag correspondente também na plataforma que a possui.
- Antes do deploy, faça backup e teste migrations/rollback em clone MySQL/MariaDB, observando locks das tabelas de visitas, pedidos e aplicações.

## Referências oficiais

- [Consent Mode overview](https://developers.google.com/tag-platform/security/concepts/consent-mode)
- [Set up consent mode](https://developers.google.com/tag-platform/security/guides/consent)
- [GA4 ecommerce](https://developers.google.com/analytics/devguides/collection/ga4/ecommerce)
- [GA4 recommended events](https://developers.google.com/analytics/devguides/collection/ga4/reference/events)
- [Google tag for Ads](https://support.google.com/google-ads/answer/2476688?hl=en)
- [Enhanced conversions setup](https://support.google.com/google-ads/answer/13258081?hl=en-0)
- [Shopify checkout_completed pixel event](https://shopify.dev/docs/api/web-pixels-api/standard-events/checkout_completed)
- [Shopify Customer Privacy API](https://shopify.dev/docs/api/customer-privacy)
- [GA4 Measurement Protocol validation](https://developers.google.com/analytics/devguides/collection/protocol/ga4/validating-events)
- [Enhanced Conversions for Leads migration in 2026](https://support.google.com/google-ads/answer/16884284?hl=en)
- [Offline conversion windows](https://support.google.com/google-ads/answer/10029210?hl=en)
- [Merchant Center business-to-business requirements](https://support.google.com/merchants/answer/6323982?hl=en)
- [Merchant minimum order value](https://support.google.com/merchants/answer/16989009?hl=en)