Pinterest Conversions API para Shopify: um guia de configuração

A Pinterest Conversions API é a forma do Pinterest de enviar eventos de conversão de servidor para servidor. A sua loja, ou uma ferramenta como o ROASaurus, envia eventos como compras direto para a sua conta de anúncios do Pinterest, em vez de depender só da Pinterest Tag no navegador do comprador. O Pinterest usa os dados para relatórios de conversão, otimização de campanhas e segmentação.

Este guia cobre a API v5 e os eventos que ela aceita, o ID de clique epik, como os dados do cliente passam por hash, como funciona a deduplicação com a Pinterest Tag, como testar e como configurar tudo no Shopify.

O que é a Pinterest Conversions API?

A Pinterest Tag é um script no navegador do comprador. A Conversions API faz o mesmo trabalho a partir de um servidor. Na versão 5 da API, você envia eventos para o endpoint de eventos da sua conta de anúncios, autorizado com um token de acesso de conversões que você cria no Pinterest Ads Manager. Cada evento diz onde aconteceu: para uma loja online, a origem da ação é web.

O Pinterest pede que os anunciantes que também usam a Tag evitem contar uma conversão duas vezes, passando um event_id com cada evento. Ele também pede eventos em tempo real, ou no máximo uma hora depois de acontecerem.

No Shopify, uma conexão de servidor tem uma vantagem clara: as compras vêm do próprio pedido. O Shopify informa cada pedido pago ao ROASaurus por webhook, e o ROASaurus o envia ao Pinterest logo após o pagamento, quer a Tag tenha disparado no navegador ou não. O guia de rastreamento server-side no Shopify explica a ideia com mais profundidade.

Quais eventos a Pinterest Conversions API aceita?

O Pinterest tem uma lista fixa de nomes de eventos padrão, escritos em minúsculas com sublinhados, como page_visit, add_to_cart e checkout. Você também pode definir até 15 tipos de eventos personalizados por anunciante. O ROASaurus mapeia os cinco eventos de compras do Shopify assim:

O nome pode confundir. O checkout do Pinterest é a compra finalizada, não o início do checkout. O início do checkout é um evento separado, initiate_checkout.

Para o evento de checkout, o Pinterest recomenda enviar o valor, a moeda, o ID do pedido, os IDs de conteúdo e o número de itens. O ROASaurus envia os cinco, mais a quantidade e o preço de cada item. O Pinterest pede o valor antes de impostos e frete. No Shopify, o ROASaurus envia exatamente isso: o total do pedido menos impostos e frete, do servidor e da tag do navegador. Quando a plataforma de uma loja online não informa impostos e frete separadamente, o ROASaurus envia o total do pedido.

Como o Pinterest associa um evento a uma pessoa?

Todo evento carrega dados do usuário. O Pinterest exige pelo menos uma de três coisas: um endereço de e-mail com hash, um ID de publicidade móvel com hash ou o endereço IP junto com o user agent. Uma loja online não tem ID de publicidade, então precisa do e-mail ou do endereço IP e user agent. O ROASaurus descarta um evento que não tenha nenhum dos dois, em vez de enviar um que o Pinterest não consegue usar.

O ID de clique epik

O ID de clique do Pinterest pode vir de dois lugares: um parâmetro epik na URL da página de entrada ou o cookie _epik no seu domínio. O guia da API do Pinterest recomenda passar o valor do cookie _epik, porque ele ainda funciona quando o parâmetro da URL falta ou foi removido, o que dá uma cobertura melhor.

O ROASaurus lê os dois na sua loja, usando o parâmetro da URL quando um novo clique traz um e o cookie nos demais casos. Ele armazena o ID de clique junto com o visitante e o envia no campo click_id de cada evento de servidor, inclusive na compra. As visitas com um epik contam como visitas do Pinterest nos relatórios de atribuição do ROASaurus.

POST https://api.pinterest.com/v5/ad_accounts/549755885175/events

{
  "data": [{
    "event_name": "checkout",
    "action_source": "web",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "event_source_url": "https://example-store.com/checkouts/…/thank-you",
    "user_data": {
      "em": ["a3f1…9c2e"],
      "ph": ["7b40…11d8"],
      "external_id": ["e05c…4a7f"],
      "client_ip_address": "203.0.113.24",
      "client_user_agent": "Mozilla/5.0 (iPhone; …)",
      "click_id": "dj0yJnU9…"
    },
    "custom_data": {
      "currency": "USD",
      "value": "84",
      "order_id": "5512345678901",
      "content_ids": ["44123456789"],
      "contents": [{ "id": "44123456789", "quantity": 2, "item_price": "42" }],
      "num_items": 2
    }
  }]
}

Como funciona a deduplicação com a Pinterest Tag?

Se a Tag e a API informam uma compra, o Pinterest recebe dois eventos para um pedido. Para tratá-los como um só, ele precisa do mesmo ID dos dois lados: o ID do evento na Tag deve ser igual ao event_id no evento de servidor. O Pinterest mantém o primeiro evento que recebe e remove os duplicados que chegam em até 48 horas.

O ROASaurus monta o ID da compra a partir do ID do pedido do Shopify. A compra do pedido 5512345678901 tem o ID de evento order-5512345678901, tanto na Tag que dispara no checkout quanto no evento de servidor.

Os cinco eventos são deduplicados

Cada evento de compras no ROASaurus tem um único ID de evento, usado pela Tag no navegador e pelo evento do servidor. A Tag usa os nomes próprios do Pinterest para os mesmos eventos: pagevisit, viewcontent, addtocart, initiatecheckout e checkout, que correspondem a page_visit, view_content, add_to_cart, initiate_checkout e checkout na API. Assim, quando os dois rodam, o Pinterest mantém uma única cópia de cada visita à página, visualização de produto, adição ao carrinho, início de checkout e compra.

Você pode usá-la de duas formas:

• Tag e Conversions API juntas. A Tag acrescenta sinais do navegador, o servidor preenche o que a Tag deixa passar e o Pinterest une as cópias.
• Rodar a API sem a Tag. Deixe o ID da Tag vazio ou desative Also load the browser tag. Cada evento é então enviado uma única vez, só pelo servidor.

O artigo de ajuda sobre contagem em duplicidade traz as mesmas verificações para as outras plataformas de anúncios.

Como testar a Pinterest Conversions API?

A API tem um parâmetro de teste. As requisições enviadas com test=true vão para um sandbox: o Pinterest as trata como dados de teste e não as usa para relatórios nem para otimização.

1. Ative o modo de teste

   No ROASaurus, edite o pixel do Pinterest em Tracking & platforms e marque Test mode (events show under Test events, max 20). Todo evento de servidor é então enviado com test=true. O Pinterest processa no máximo 20 eventos de teste por lote.

2. Faça um pedido de teste

   Visite a sua loja, veja um produto, adicione-o ao carrinho e conclua um pedido.

3. Leia o resultado

   Abra o Event log. O Pinterest pode responder HTTP 200 mesmo que um evento de uma requisição tenha falhado, então o ROASaurus confere o status de cada evento e mostra as falhas ali.

4. Desative o modo de teste

   Desmarque o modo de teste, para que os eventos contem nos relatórios e na otimização.

5. Confira o Events Overview

   No Pinterest Ads Manager, abra a página Events Overview. Ela mostra os eventos que chegam e as conversões deduplicadas. O Pinterest recomenda buscar uma Event Quality Score classificada como Good.

Como configurar a Pinterest Conversions API no Shopify com o ROASaurus

Você precisa de uma loja no Shopify com o app do ROASaurus e de acesso ao Pinterest Ads Manager. A página de integração com o Pinterest lista todos os campos que o ROASaurus envia.

1. Conecte a sua loja do Shopify

   Vá em Add a store › Shopify, clique em Install app e ative o app embed do ROASaurus no editor de temas. Ele captura o epik e o cookie _epik em todas as páginas. O guia de configuração do Shopify mostra cada etapa.

2. Crie um token de acesso de conversões

   No Pinterest Ads Manager, vá em Conversions e crie um token de acesso de conversões. Anote o ID da sua conta de anúncios.

3. Adicione o pixel do Pinterest no ROASaurus

   Vá em Tracking & platforms, clique em Add pixel no card do Pinterest e preencha Ad account ID e Conversion access token.

4. Adicione o ID da sua Tag

   Para a deduplicação com a Tag, preencha Pinterest Tag ID e deixe Also load the browser tag marcado. Sem um Tag ID, o ROASaurus envia só eventos de servidor e não carrega a Tag.

5. Adicione o pixel de checkout

   No Shopify admin › Settings › Customer events, adicione um pixel personalizado chamado ROASaurus e cole o snippet da sua página Tracking & platforms. Ele dispara o evento checkout da Tag no checkout do Shopify, com o ID do pedido como event_id.

6. Escolha os eventos de servidor e depois teste

   Escolha os eventos de servidor que quiser e teste no modo de teste antes de entrar no ar.

Com Respect visitor consent ativado, que é o padrão, o ROASaurus segue a escolha do comprador no banner de cookies do Shopify. Quando um comprador recusa os cookies de marketing, o ROASaurus não carrega a Pinterest Tag para ele, não define um ID de visitante, então os cliques dele não são vinculados a ele, e não envia os eventos de navegação dele ao Pinterest. O pedido pago dele ainda é enviado à Conversions API pelo servidor, com os dados do pedido em hash e com o endereço IP e o user agent do pedido, mas sem um ID de clique. O guia de consentimento e privacidade explica o que é armazenado e enviado.

Conecte sua conta de anúncios do Pinterest em Setup › Ad spend e o ROASaurus busca o investimento das campanhas a cada hora, para você ver o ROAS do Pinterest e o lucro após anúncios na análise de lucro. O guia da TikTok Events API traz a mesma configuração para o TikTok, em que todo evento que vai pelos dois caminhos é deduplicado.

Fontes

1. Pinterest Developers: Track conversion events in the API
2. Pinterest Business help: The Pinterest Conversions API
3. Pinterest Developers: Track conversions with Pinterest Tag

No ROASaurus

• Integração com o Pinterest
• Rastreamento server-side no ROASaurus
• Ajuda: evitar a contagem em duplicidade

Continue lendo