Acompanhamento de conversões

Observação: o acompanhamento de conversões foi atualizado em 2 de fevereiro de 2024. Se tiver dúvidas sobre as mudanças, entre em contato com seu representante do Google.

Aviso: verifique se as informações de identificação pessoal (PII) do usuário não são enviadas ao Google como parte dos dados de conversão.

Implementação

Resumo

A implementação do acompanhamento de conversões tem três partes:

• Coletar o rwg_token e o merchant_id da página de destino ou do ponto de entrada do app.
• Manter rwg_token e merchant_id para a janela de atribuição adequada.
• Compare merchant_id e merchant_id persistidos no momento da conversão (reserva concluída).
• Enviar um evento de conversão no momento da conversão (reserva concluída).

Essa implementação do acompanhamento de conversões não requer o uso do Google Analytics ou de qualquer outro JavaScript de terceiros.

Importante :há dois níveis diferentes em que é possível implementar o acompanhamento de conversões, no nível do dispositivo e do usuário. Ambos são compatíveis durante essa integração, e você pode escolher com base na arquitetura do produto.

Antes de começar a implementar o acompanhamento de conversões, decida se você vai acompanhar as conversões no nível do dispositivo ou do usuário:

• O nível do dispositivo inclui o uso de cookies do navegador, armazenamento local, armazenamento local do app ou qualquer outro método que possa manter o token na janela de atribuição de 30 dias. Como o token seria armazenado localmente no dispositivo do usuário, se ele mudar o dispositivo que está usando, limpar o armazenamento local ou os cookies ou estiver usando uma navegação privada ou o modo de navegação anônima, o evento de conversão pode não ser atribuído corretamente. Ao usar o acompanhamento de conversões no nível do dispositivo, é necessário implementá-lo novamente em todas as plataformas compatíveis (incluindo dispositivos móveis).
• O nível do usuário inclui a persistência no banco de dados do aplicativo, por meio de um sistema de análise do lado do servidor ou de outros sistemas do lado do servidor. Como o token seria armazenado no servidor, se o usuário mudar o dispositivo que está usando, limpar o armazenamento local ou os cookies ou estiver usando uma navegação privada ou modo de navegação anônima, o evento de conversão ainda será atribuído quando o usuário fizer login novamente. Ao usar o acompanhamento de conversões no nível do usuário, dependendo da arquitetura do sistema, você poderá implementar isso uma vez no lado do servidor e reutilizá-lo em todas as plataformas compatíveis.

Como coletar o rwg_token

Sempre que o Google mostra um action_link que você forneceu por meio dos feeds, esse URL é modificado para incluir um parâmetro de consulta exclusivo: rwg_token. O valor rwg_token é uma string codificada que contém alguns metadados sobre o link em que o usuário clicou, mas sem dados do usuário. Armazene esse token e transmita-o de volta como parte do evento de conversão.

Em cada página de destino / ponto de entrada do app, você precisa analisar o valor definido para o parâmetro de consulta rwg_token e armazená-lo. Os requisitos para armazenar esse parâmetro são descritos na etapa "Como manter o rwg_token".

Um exemplo de como esse token pode ser analisado para rastreamento no nível do dispositivo pelo navegador está incluído abaixo. Como alternativa, você pode coletar esse token no lado do servidor ao responder à solicitação:

var query = location.search.substring(1);
var params = query.split('&');
var rwgToken = undefined;
for (var i = 0; i < params.length; ++i) {
  var pair = params[i].split('=');
  if (pair[0] == 'rwg_token') {
    rwgToken = decodeURIComponent(pair[1]);
    break;
  }
}

Como coletar o merchant_id

Se você implementar a lógica de acompanhamento de conversões no front-end, será necessário implementar um script personalizado na página de destino que encontre e capture o merchant_id. Normalmente, o merchant_id já pode estar presente na página de destino ou no URL para que você possa capturá-lo de lá. Caso contrário, você precisará encontrar uma maneira de expô-lo em algum lugar para que possa ser capturado, o que provavelmente implicaria mudanças de back-end.

Se você implementar a lógica de acompanhamento de conversões no back-end, poderá encontrar o merchant_id ao lado dos dados que consultam seu sistema interno para gerar a página de front-end.

Esse merchant_id precisa ser o mesmo que você compartilhou com o Google no seu feed.

Observação :no caso raro de sua experiência de front-end não permitir que o usuário alterne entre comerciantes (pode acontecer em sites com etiqueta em branco que não têm um botão "página inicial" para retornar a uma seleção de comerciantes). Você pode pular a captura de merchant_id e presumir que merchant_id não mudou ("merchant_changed": 2), já que é impossível para os usuários alternar entre comerciantes na jornada de reserva.

Manter o rwg_token e o merchant_id

Observação: manter a rwg_token é essencial para implementar corretamente a janela de atribuição necessária. Para mais detalhes sobre os requisitos de atribuição, consulte a seção "Requisitos de atribuição de conversão" abaixo.

Será necessário manter o parâmetro de URL rwg_token, que será anexado a todos os links de ação fornecidos por você, por um período total de 30 dias. O valor de rwg_token precisa ser armazenado e retornado sem nenhuma edição.

Junto com o rwg_token, você precisará armazenar o merchant_id associado ao link de ação.

Se houver um token de um acesso anterior, os rwg_token e merchant_id anteriores precisarão ser substituídos, e a janela de 30 dias para armazenamento precisará ser redefinida.

Ao manter o par acima, você pode armazenar os valores no nível do dispositivo ou do usuário:

• O nível do dispositivo inclui o uso de cookies do navegador, armazenamento local, armazenamento local do app ou qualquer outro método que possa manter o token na janela de atribuição de 30 dias.
• O nível do usuário inclui a persistência no banco de dados do aplicativo, por meio de um sistema de análise do lado do servidor ou de outros sistemas do lado do servidor.

Veja abaixo um exemplo de acompanhamento de conversões no nível do dispositivo, armazenando esses valores em um navegador da Web usando um cookie primário. Neste exemplo, presumimos que você analisou o valor do token em uma variável, como no exemplo acima. Para usar este exemplo, você precisa atualizar rootdomain.com para seu domínio.

if (typeof rwg_token !== 'undefined') {
  document.cookie =
  "_rwg_token=" + rwg_token + ";_merchant_id=" + merchantid + ";max-age=2592000;domain=rootdomain.com;path=/";
}

Ao usar o acompanhamento de conversões no nível do usuário, rwg_token + merchant_id precisam ser armazenados no servidor e associados ao usuário.

Enviar dados de conversão

Quando um usuário conclui uma transação que pode ser atribuída a um link de ação do Google Place, você precisa enviar uma solicitação HTTP POST para o endpoint de conversão. Há dois endpoints, um para o ambiente de produção e outro para o ambiente de sandbox.

• Produção: https://www.google.com/maps/conversion/collect
• Sandbox: https://www.google.com/maps/conversion/debug/collect

O corpo da postagem deve ser um objeto codificado JSON no formato:

{
  "conversion_partner_id": <partnerId>,
  "rwg_token": <rwg_token_val>,
  "merchant_changed": 1|2
}

Exemplo (comerciante inalterado com o token de teste do parceiro 20123456):

{
  "conversion_partner_id": 20123456,
  "rwg_token": "AJKvS9WeONmWKEwjG0--HdpzMq0yAVNL8KMxbb44QtbcxMhSx_NUud5b8PLUBFehAIxOBO-iYRIJOknEFkIJmdsofdVJ6uOweQ",
  "merchant_changed": 2
}

O valor merchant_changed é usado para determinar se o comerciante foi alterado desde o redirecionamento inicial. Há dois valores que podem ser passados

Valor da mudança do comerciante	Requisito
1	Esse valor deve ser usado quando um usuário sair do site do comerciante original e concluir uma compra na sua plataforma com um comerciante diferente.
2	Use esse valor quando o cliente concluir uma transação por meio da entidade original (comerciante).

Nos ambientes de sandbox e de produção, é necessário informar um rwg_token válido ao enviar um evento de conversão. Para fins de teste, use o seguinte token de teste nos dois ambientes até o lançamento:

AJKvS9WeONmWKEwjG0--HdpzMq0yAVNL8KMxbb44QtbcxMhSx_NUud5b8PLUBFehAIxOBO-iYRIJOknEFkIJmdsofdVJ6uOweQ==

Atenção :na produção, não envie eventos de conversão que não sejam atribuídos a essa integração. Verifique se há um valor de rwg_token válido e não expirado antes de enviar o evento.

Confira abaixo um exemplo completo de acompanhamento de conversões no dispositivo (usando um cookie no dispositivo do usuário) em JavaScript sobre como fazer essa solicitação de postagem:

const partnerId = XXXXXXXXXX;

const endpoint = `https://www.google.com/maps/conversion/collect`;

const rwgTokenCookie = document.cookie
  .split('; ')
  .find(row => row.startsWith('_rwg_token='));

if (typeof rwgTokenCookie !== 'undefined') {
  const rwgTokenVal = rwgTokenCookie.split('=')[1];
  fetch(endpoint, {
    method: "POST",
    body: JSON.stringify({
      conversion_partner_id: partnerId,
      rwg_token: rwgTokenVal,
      merchant_changed: merchantChanged
    })
  });
}

Ao usar o acompanhamento de conversões no nível do usuário, recupere o token associado ao usuário (independentemente da superfície em que ele esteja) do mecanismo de armazenamento do lado do servidor e envie o token usando os mesmos endpoints de produção ou sandbox.

Observação :os eventos de conversão podem ser enviados de um cliente da Web ou de app ou do servidor. Você pode tomar essa decisão de acordo com suas necessidades e de acordo com o local de armazenamento do token, desde que um evento de conversão seja enviado exatamente uma vez por conversão e inclua um valor rwg_token válido.

Requisitos de atribuição de conversão

O padrão obrigatório do Google para atribuição de conversões é uma janela de atribuição de 30 dias para qualquer interação com um link de lugar, em qualquer loja.

Observação :esse modelo de atribuição pode ser diferente da forma como seu sistema de análise atribui conversões. Esse sistema foi projetado para funcionar independentemente de qualquer acompanhamento de conversões que você esteja fazendo nos seus sistemas e não deve afetar as análises internas.

Essa janela de atribuição significa que o Google espera que um evento de conversão seja enviado em qualquer um destes cenários:

• Um usuário segue um link de posicionamento de ação e faz um pedido para o mesmo comerciante na mesma sessão. (Valor da mudança do comerciante = 2)
• Um usuário segue um link de posicionamento de ação e retorna de um canal diferente no período de 30 dias para fazer um pedido do mesmo comerciante. (Valor da mudança do comerciante = 2)
• Um usuário segue um link de posicionamento de ação e faz um pedido em uma loja diferente, dentro da mesma sessão ou em uma sessão diferente dentro de 30 dias. ( Valor da mudança do comerciante = 1)

Além disso, o Google espera que os eventos de conversão sejam enviados de todas as plataformas para onde um usuário pode acessar a partir de um link de ação de lugar. Incluindo:

• Aplicativos da Web para computadores ou dispositivos móveis
• Apps para dispositivos móveis, seja por um link direto de app ou uma intent de app registrada para seu domínio

Se o token estiver armazenado no nível do usuário (consulte "Como persistir o token"), você precisa fornecer a atribuição entre dispositivos. Ou seja, um usuário que segue um link de ação no computador e conclui a transação em um dispositivo móvel (usando a mesma conta de usuário), precisa acionar um evento de conversão.

Se o token é armazenado exclusivamente no dispositivo, como nos cookies do navegador, não é esperado que você forneça a atribuição entre dispositivos. Nesse caso, cada dispositivo teria um token separado persistido se o usuário tivesse seguido um link de ação nesse dispositivo, e cada dispositivo seguiria as regras de atribuição separadamente.