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

A Conversions API do Pinterest é a forma que o Pinterest tem de enviar eventos de conversão de servidor para servidor. A sua loja, ou uma ferramenta como a ROASaurus, envia eventos como compras diretamente para a sua conta de anúncios do Pinterest, em vez de depender apenas 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 aborda a API v5 e os eventos que aceita, o ID de clique epik, como os dados do cliente recebem hash, como funciona a eliminação de duplicados com a Pinterest Tag, como testar e como configurar tudo no Shopify.

O que é a Conversions API do Pinterest?

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, envia os eventos para o endpoint de eventos da sua conta de anúncios, autorizado com um token de acesso de conversões que cria no Pinterest Ads Manager. Cada evento indica onde aconteceu: numa loja online, a origem da ação é web.

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

No Shopify, uma ligação de servidor tem uma vantagem clara: as compras vêm da própria encomenda. O Shopify comunica cada encomenda paga à ROASaurus por webhook, e a ROASaurus envia-a ao Pinterest pouco depois do pagamento, tenha a Tag disparado ou não no navegador. O guia de tracking server-side no Shopify explica a ideia com mais pormenor.

Que eventos aceita a Conversions API do Pinterest?

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

O nome pode confundir. O checkout do Pinterest é a compra terminada, 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 da encomenda, os IDs de conteúdo e o número de artigos. A ROASaurus envia os cinco, mais a quantidade e o preço de cada artigo. O Pinterest pede o valor antes de impostos e de envio. No Shopify, a ROASaurus envia exatamente isso: o total da encomenda menos impostos e envio, a partir do servidor e da tag do navegador. Quando a plataforma de uma loja online não comunica os impostos e o envio em separado, a ROASaurus envia o total da encomenda.

Como é que o Pinterest associa um evento a uma pessoa?

Cada evento traz dados do utilizador. O Pinterest exige pelo menos uma de três coisas: um endereço de email com hash, um ID publicitário móvel com hash, ou o endereço IP juntamente com o user agent. Uma loja online não tem ID publicitário, por isso precisa do email ou do endereço IP e do user agent. A ROASaurus ignora 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 sítios: um parâmetro epik no 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 continua a funcionar quando o parâmetro do URL falta ou foi removido, o que dá melhor cobertura.

A ROASaurus lê ambos na sua loja, usando o parâmetro do URL quando um novo clique o traz e o cookie nos restantes casos. Guarda o ID de clique com o visitante e envia-o no campo click_id de cada evento do servidor, incluindo a compra. As visitas com um epik contam como visitas do Pinterest nos relatórios de atribuição da 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 eliminação de duplicados com a Pinterest Tag?

Se a Tag e a API comunicarem ambas uma compra, o Pinterest recebe dois eventos para uma encomenda. Para os tratar como um só, precisa do mesmo ID nos dois lados: o ID de evento na Tag tem de coincidir com o event_id no evento do servidor. O Pinterest mantém o primeiro evento que recebe e remove os duplicados que cheguem dentro de 48 horas.

A ROASaurus constrói o ID da compra a partir do ID da encomenda do Shopify. A compra da encomenda 5512345678901 tem o ID de evento order-5512345678901, na Tag que dispara no checkout e no evento do servidor.

Os cinco eventos têm eliminação de duplicados

Cada evento de loja na 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 ambos estão ativos, o Pinterest fica com uma única cópia de cada visita de página, visualização de produto, adição ao carrinho, início de checkout e compra.

Pode usá-la de duas formas:

• Tag e Conversions API em conjunto. A Tag acrescenta sinais do navegador, o servidor preenche o que a Tag não apanha e o Pinterest junta as cópias.
• Usar a API sem a Tag. Deixe o ID da Tag vazio ou desative Also load the browser tag. Cada evento é então enviado uma só vez, apenas a partir do servidor.

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

Como se testa a Conversions API do Pinterest?

A API tem uma flag de teste. Os pedidos enviados com test=true vão para uma sandbox: o Pinterest trata-os como dados de teste e não os usa para relatórios nem otimização.

1. Ative o modo de teste

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

2. Faça uma encomenda de teste

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

3. Leia o resultado

   Abra o Event log. O Pinterest pode responder HTTP 200 mesmo que um evento de um pedido tenha falhado, por isso a ROASaurus verifica o estado de cada evento e mostra aí as falhas.

4. Desative o modo de teste

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

5. Verifique o Events Overview

   No Pinterest Ads Manager, abra a página Events Overview. Mostra os eventos que chegam e as conversões depois da eliminação de duplicados. O Pinterest recomenda procurar um Event Quality Score de nível Good.

Como configurar a Conversions API do Pinterest no Shopify com a ROASaurus

Precisa de uma loja Shopify com a app ROASaurus e de acesso ao Pinterest Ads Manager. A página da integração com o Pinterest lista todos os campos que a ROASaurus envia.

1. Ligue a sua loja Shopify

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

2. Crie um token de acesso de conversões

   No Pinterest Ads Manager, vá a 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 na ROASaurus

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

4. Adicione o ID da sua Tag

   Para a eliminação de duplicados com a Tag, preencha Pinterest Tag ID e mantenha Also load the browser tag assinalado. Sem um ID da Tag, a ROASaurus envia apenas eventos do servidor e não carrega a Tag.

5. Adicione o pixel de checkout

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

6. Escolha os eventos do servidor e depois teste

   Escolha os eventos do servidor que quer e teste com o modo de teste antes de ativar em produção.

Com Respect visitor consent ativado, que é a predefinição, a ROASaurus segue a escolha do comprador no banner de cookies do Shopify. Quando um comprador recusa os cookies de marketing, a ROASaurus não carrega a Pinterest Tag para ele, não define nenhum ID de visitante, pelo que os seus cliques não ficam associados a ele, e não envia os seus eventos de navegação ao Pinterest. A sua encomenda paga continua a ser enviada para a Conversions API a partir do servidor, com os dados da encomenda com hash e o endereço IP e o user agent da encomenda, mas sem ID de clique. O guia de consentimento e privacidade explica o que é guardado e enviado.

Ligue a sua conta de anúncios do Pinterest em Setup › Ad spend e a ROASaurus obtém o investimento das campanhas todas as horas, para que veja o ROAS do Pinterest e o lucro depois dos anúncios na análise de lucro. O guia da Events API do TikTok cobre a mesma configuração para o TikTok, onde todos os eventos que seguem pelos dois caminhos têm eliminação de duplicados.

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

Na ROASaurus

• Integração com o Pinterest
• Tracking server-side na ROASaurus
• Ajuda: evitar a contagem em duplicado

Continue a ler