Integração por meio da API do Google Analytics

A integração é um processo de configuração do envio de dados de ações em seu site ao sistema Admitad.

Uma ação é uma compra, cadastro, solicitação concluída ou outra ação realizada por um usuário direcionado ao seu site por um afiliado da Admitad.

Informações gerais: características e recomendações

Você pode iniciar a integração somente se o seu programa:
- já tiver um link de rastreamento gerado na seção General Settings;
- já tiver uma ação adicionada e a taxa correspondente configurada na seção Actions.

Se você não tiver um gestor, crie um link de rastreamento por conta própria (instruções) e adicione pelo menos uma ação e uma taxa (instruções).
Se você tiver um gestor pessoal, ele configurará tudo para você.

A integração é um passo obrigatório para continuar trabalhando. Sem ela, você não pode lançar um programa afiliado na Admitad.
Para acelerar a integração, recomendamos que você peça ajuda ao seu próprio especialista técnico e passe essas instruções para ele.

Quando a integração for concluída, todos os dados de ações (a data da ação, o ID do pedido, seu valor, entre outros) serão enviados para a Admitad automaticamente.

Como funciona a integração por meio da API do Google Analytics

A API do Google Analytics (doravante denominada API do GA) é uma interface de programação do serviço Google Analytics, que permite usar as informações e funcionalidades do Google Analytics por meio de requisições HTTP.

Como funciona

1. O Google Analytics coleta informações sobre as ações de usuários usando um "contador" (código JavaScript) implementado nas páginas do site.
Quando um usuário faz uma ação, o código é acionado, registra as informações relevantes à ação e envia pacotes de dados para o Google Analytics.

2. Em seguida, a Admitad Partner Network envia uma requisição GET para a API do Google Analytics e recebe o número e valor do pedido, além de outros dados relacionados à ação.

3. A Admitad carrega esses dados e acaba exibindo as informações finais na seção Reports da sua conta Admitad.

Observe que o "contador" do Google Analytics pode ser bloqueado por bloqueadores de anúncios e outras extensões. A Admitad Partner Network não fornece suporte técnico para o Google Analytics e não é responsável por programas que foram prejudicados como resultado do uso do Google Analytics para coletar dados de ações.
Portanto, recomendamos o uso da integração padrão via código de rastreamento ou outros métodos de integração disponíveis. Saiba mais

Como fazer uma integração via API do Google Analytics

Para integrar seu site por meio da API do Google Analytics, siga estes passos (confira as instruções para cada um deles):

configure o rastreamento de e-commerce no Google Analytics;
no Google Analytics, conceda a um especialista da Admitad o acesso aos pedidos atribuídos para a Admitad;
configure os parâmetros de integração no Google Analytics e
implemente o código recebido com os valores dos parâmetros necessários nas páginas do seu site;
teste a integração configurada;
opcional: configure a transferência de dados para códigos de promoção personalizados;
opcional: configure a transferência de dados de backup de ações.

Se o seu programa tiver mais de uma ação e taxa, informe o especialista da Admitad sobre isso. Nesse caso, você receberá informações adicionais sobre como configurar a integração.

Se, além da versão web do site, você tiver uma versão móvel e/ou um formulário de pedido rápido ou de compra com um clique, configure a integração com a Admitad Partner Network para eles também. Saiba mais

Como configurar o rastreamento de e-commerce

Configure o rastreamento de e-commerce para seu site usando as instruções do Google Analytics:

Como configurar o rastreamento de e-commerce
Como usar a gtag.js para e-commerce (novo tipo do Google Analytics)
Rastreamento de e-commerce com a analytics.js (antigo tipo do Google Analytics)

Como conceder acesso aos pedidos da Admitad no Google Analytics

Conceda à conta especial Admitad Partner Network acesso a pedidos atribuídos à Admitad no Google Analytics.

1. Faça login na sua conta do Google Analytics e, no canto inferior esquerdo, clique em Administrador.

2. Na aba Administrador, na coluna Vista, selecione um site com relatórios por ações e clique em Configurações da vista da propriedade.

3. Compartilhe o ID da vista da propriedade ao especialista da Admitad.

4. Retorne à seção Administrador.
Se você tiver vários sites, na coluna Vista, selecione um site com os relatórios desejados na lista suspensa e clique em Ver gerenciamento de acesso.

5. No canto superior direito, clique em e selecione Adicionar usuários.

6. No bloco Endereços de e-mail, insira o endereço de e-mail da conta especial Admitad Partner Network, especificado nas instruções de integração.

No bloco Restrições diretas de dados e funções, selecione Leitor e clique em Adicionar.

Pronto. Você concedeu à conta especial Admitad acesso a pedidos atribuídos para a Admitad.

Agora a Admitad pode receber dados de ações via requisição GET para a API do Google Analytics.

Se você pretende usar o modelo Last Non-direct Click, informe o especialista da Admitad de que você:
- configurou o rastreamento de e-commerce e
- concedeu acesso aos pedidos atribuídos à Admitad no Google Analytics.
Você concluiu as etapas de integração necessárias para trabalhar com o modelo Last Non-direct Click.
Agora você também pode configurar a transferência de dados para códigos de promoção personalizados e/ou transferência de dados de backup para o Google Analytics.
Se você pretende usar o modelo Last Paid Click, vá para a próxima etapa: configure os parâmetros de integração e implemente o código de rastreamento no site.

Como configurar os parâmetros de integração e implementar o código de rastreamento no site

Esta etapa da configuração da integração é relevante apenas para o modelo Last Paid Click.

1. Na conta do Google Analytics, no canto inferior esquerdo, clique em Administrador.

2. Na aba Administrador, na coluna Propriedade, clique em Definições personalizadas → Dimensões personalizadas.

3. Na nova página, clique em + NOVA DIMENSÃO PERSONALIZADA e adicione os seguintes parâmetros:

Nome da dimensão personalizada	Escopo
suid	Hit
user_id	Hit
hit_id	Hit
session_id	Sessão
client_id	Sessão
action_code	Hit
tariff_code	Hit

4. Retorne à guia Administrador. Na coluna Propriedade, clique em Informações de acompanhamento → Código de acompanhamento.

5. Copie seu ID de rastreamento. Você precisa adicioná-lo ao código apresentado no próximo parágrafo.

6. Copie o código abaixo e adicione-o a todas as páginas do seu site, exceto à página Obrigado por sua compra.

O código deve ter todos os valores de variáveis necessários.

<!-- Global site tag (gtag.js) - Google Analytics -->
    <script async="" src="https://www.googletagmanager.com/gtag/js?id=UA-XXXXXXXXX-X"></script>
    // substitua UA-XXXXXXXXX-X pelo seu ID de rastreamento do Google Analytics

    <!-- Google Analytics custom dimensions for Admitad -->
    <script>
  function clientid() {
      var match = document.cookie.match('(?:^|;)\\s*_ga=([^;]*)');
      var raw = (match) ? decodeURIComponent(match[1]) : null;
      if (raw) {
          match = raw.match(/(\d+\.\d+)$/);
      }
      var gacid = (match) ? match[1] : null;
      if (gacid) {
          return gacid;
      }
  }

  function getTimeStamp() {
      var now = new Date();
      var tzo = -now.getTimezoneOffset();
      var dif = tzo >= 0 ? '+' : '-';
      var pad = function(num) {
          var norm = Math.abs(Math.floor(num));
          return (norm < 10 ? '0' : '') + norm;
      };
      return now.getFullYear() +
          '-' + pad(now.getMonth() + 1) +
          '-' + pad(now.getDate()) +
          'T' + pad(now.getHours()) +
          ':' + pad(now.getMinutes()) +
          ':' + pad(now.getSeconds()) +
          '.' + pad(now.getMilliseconds()) +
          dif + pad(tzo / 60) +
          ':' + pad(tzo % 60);
  }

  function getSessionId() {
      return new Date().getTime() +
          '.' + Math.random().toString(36).substring(5);
  }

  function uuidv4() {
    return ([1e7] + -1e3 + -4e3 + -8e3 + -1e11).replace(/[018]/g, function(c) {return (c ^ (window.crypto || window.msCrypto).getRandomValues(new Uint8Array(1))[0] & 15 >> c /   4).toString(16)});
  }


  function referrer() {
      if (document.referrer === "") {
          return "direct none"
      } else return document.referrer
  }

  window.dataLayer = window.dataLayer || [];

  function gtag() {
      dataLayer.push(arguments);
  }
  gtag('js', new Date());

  gtag('config', 'UA-XXXXXXXXX-X'); // substitua UA-XXXXXXXXX-X pelo seu ID de rastreamento do Google Analytics aqui e na próxima linha
  gtag('config', 'UA-XXXXXXXXX-X', {
      'custom_map': {
          'dimensionX': 'suid',
          'dimensionX': 'client_id',
          'dimensionX': 'user_id',
          'dimensionX': 'session_id',
          'dimensionX': 'hit_id'
      } // para dimensionX, em vez de X, insira os índices de parâmetros relevantes (coluna Índice)
  });
  gtag('event', 'apv', {
      'suid': uuidv4(),
      'client_id': clientid(),
      'user_id': 'ID do usuário no seu sistema', // e o ID for desconhecido, deixe essa string vazia. Saiba mais sobre as configurações de ID do usuário
      'session_id': getSessionId(),
      'hit_id': getTimeStamp(),
  });
</script>

7. Copie o código abaixo e cole-o na página Obrigado por sua compra.

<!-- Global site tag (gtag.js) - Google Analytics -->
    <script async="" src="https://www.googletagmanager.com/gtag/js?id=UA-XXXXXXXXX-X"></script>
    // substitua UA-XXXXXXXXX-X pelo seu ID de rastreamento do Google Analytics

    <!-- Google Analytics Ecommerce with custom dimensions for Admitad -->
    <script> 
window.dataLayer = window.dataLayer || [];

function gtag() {
    dataLayer.push(arguments);
}
gtag('js', new Date());

gtag('config', 'UA-XXXXXXXXX-X'); // substitua UA-XXXXXXXXX-X pelo seu ID de rastreamento do Google Analytics aqui e na próxima linha
gtag('config', 'UA-XXXXXXXXX-X', {
    'custom_map': {
        'dimensionX': 'suid',
        'dimensionX': 'client_id',
        'dimensionX': 'user_id',
        'dimensionX': 'hit_id',
        'dimensionX': 'action_code',
        'dimensionX': 'tariff_code'
    } // para dimensionX, em vez de X, insira os índices de parâmetros relevantes (coluna Índice)


});

ga_items = [];

var list_position = 1; 

// este trecho de código precisa ser repetido para cada item no carrinho
ga_items.push({
    "id": "{{ item.product_id }}",
    "name": "{{ item.product_title }}",
    "quantity": "{{ item.quantity }}",
    "price": "{{ item.price }}",
    "category": "{{ item.product_type }}",
    "list_position": list_position,
    "variant": "{{ item.variant }}",
    "brand": "{{ item.brand }}",
});
list_position = list_position + 1; 
// fim do trecho de código a ser repetido

function getTimeStamp() {
    var now = new Date();
    var tzo = -now.getTimezoneOffset();
    var dif = tzo >= 0 ? '+' : '-';
    var pad = function(num) {
        var norm = Math.abs(Math.floor(num));
        return (norm < 10 ? '0' : '') + norm;
    };
    return now.getFullYear() + '-' + pad(now.getMonth() + 1) + '-' + pad(now.getDate()) + 'T' + pad(now.getHours()) + ':' + pad(now.getMinutes()) + ':' + pad(now.getSeconds()) + '.' + pad(now.getMilliseconds()) + dif + pad(tzo / 60) + ':' + pad(tzo % 60);
}

function clientid() {
    var match = document.cookie.match('(?:^|;)\\s*_ga=([^;]*)');
    var raw = (match) ? decodeURIComponent(match[1]) : null;
    if (raw) {
        match = raw.match(/(\d+.\d+)$/);
    }
    var gacid = (match) ? match[1] : null;
    if (gacid) {
        return gacid;
    }
}

function getSessionId() {
    return new Date().getTime() +
        '.' + Math.random().toString(36).substring(5);
}

function uuidv4() {
    return ([1e7] + -1e3 + -4e3 + -8e3 + -1e11).replace(/[018]/g, function(c) {return (c ^ (window.crypto || window.msCrypto).getRandomValues(new Uint8Array(1))[0] & 15 >> c /   4).toString(16)});
  }

gtag('event', 'purchase', {
    "transaction_id": "{{ order_number }}",
    "affiliation": "",
    "currency": "{{ shop.currency }}",
    "shipping": "{{ shipping_price }}",
    "items": ga_items,
    "session_id": {{coupon}}, // insira um valor se você tiver um código de promoção personalizado. Saiba mais
    "action_code": "{{ action_code }}", // copie o valor da tabela na página Integração por meio da API do Google Analytics (menu → Programa → Integração → Avançar → aba Integração personalizada → API do Google Analytics → Avançar)
    "tariff_code": "{{ tariff_code }}", // copie o valor da tabela na página Integração por meio da API do Google Analytics (menu → Programa → Integração → Avançar → aba Integração personalizada → API do Google Analytics → Avançar)
    "suid": uuidv4(),
    "client_id": clientid(),
    "user_id": "ID do usuário no seu sistema",
  // se o ID for desconhecido, deixe essa string vazia. Saiba mais sobre as configurações de ID do usuário
    "session_id": getSessionId(),
    "hit_id": getTimeStamp(),
});
</script>

Pronto. Você configurou os parâmetros de integração e implementou o código de rastreamento nas páginas do site.

Agora informe o especialista da Admitad de que você

configurou o rastreamento de e-commerce,
concedeu acesso aos pedidos atribuídos à Admitad no Google Analytics,
configurou parâmetros especiais e implementou o código com os valores relevantes no site.

Em seguida, o especialista da Admitad irá elaborar um programa de processamento de pedidos que usará os seguintes parâmetros:

dimensions:
- ga:transactionId: número do pedido;
- ga:productSku: número do produto (pode ser usado para determinar a taxa);
- ga:adContent: conteúdo do identificador utm_content (usado para armazenar o valor do parâmetro admitad_uid);
- ga:dateHourMinute: data e hora do pedido;
- ga:currencyCode: código da moeda;
metrics:
- ga:itemRevenue: preço do pedido;
- ga:couponCode: código de promoção.

Como configurar a deduplicação de pedidos

A deduplicação é um método de processamento de dados que permite identificar corretamente uma fonte de tráfego paga para atribuir um pedido a ela, bem como eliminar ações duplicadas, se houver.

Ao integrar por meio da API do Google Analytics, a deduplicação não precisa ser configurada:

para o modelo Last Non-direct Click: a deduplicação de ações é configurada por padrão.
para o modelo Last Paid Click: a última fonte de tráfego paga é determinada pelo valor do parâmetro de acesso ao site utm_source. Se o valor for utm_source=admitad, o pedido será atribuído à Admitad Partner Network.

Como testar a integração configurada

Para testar a integração por meio da API do GA:

1. Obtenha um link de afiliado de teste na página Setting up integration through a tracking code na seção Integration testing.

1.1 Em sua conta pessoal, vá para a seção Integration (Program → Integration).

1.2 Em seguida, clique em Next e, na página Integration methods, mude para a guia Custom integration.

1.3 Na guia Custom integration, selecione Tracking code e clique em Next.

1.4 O bloco Integration testing está localizado na parte inferior da tela.

2. Siga o link e faça uma ação de acordo com as condições do seu programa.
Por exemplo, se você só paga afiliados se um usuário comprar um determinado produto, compre esse produto.

Recomendações de teste de integração:

Se você tiver várias ações e/ou taxas, faça alguns pedidos de teste para verificar todas as ações e taxas.
Inclua vários itens em um de seus pedidos de teste para verificar se os itens e o valor total do pedido são transferidos corretamente.
Se você tiver um formulário de pedido rápido ou de compra com um clique, faça um pedido por meio dele para testar a integração do formulário.

3. Abra sua conta do Google Analytics e, no painel esquerdo, selecione Conversões → E-commerce → Transações.

4. Na aba Explorador, clique em Dimensão secundária (1) e, em seguida, Usadas frequentemente (2) → Origem (3).

5. Na guia Explorador, na caixa de pesquisa (4), digite "admitad" e clique no botão de pesquisa.

6. Se a integração estiver configurada corretamente, uma lista de pedidos será aberta, com todos os pedidos de teste exibidos e a fonte de tráfego indicada como "admitad".

Pronto. Teste de integração concluído.
Notifique o especialista da Admitad sobre o fim do teste para que o programa seja preparado para o lançamento.

Como configurar a transferência de dados para códigos de promoção personalizados

A configuração da transferência de dados para códigos de promoção é uma etapa de integração opcional.

Os códigos de promoção personalizados são códigos de promoção que contêm uma palavra-chave exclusiva pela qual as ações são rastreadas. Esses códigos de promoção são atribuídos a afiliados específicos. Saiba mais sobre códigos de promoção personalizados

Para usar códigos de promoção personalizados:

o formulário de pedido no site deve ter o campo Promo code;
sua conta do Google Analytics deve ter a transferência de tags Enhanced Ecommerce ativada e configurada.

Para configurar a transferência de dados para códigos de promoção personalizados:

1. Crie um código de promoção personalizado com uma palavra-chave exclusiva para seu site.

2. Copie o código de promoção personalizado do formulário de pedido e cole-o no parâmetro "coupon" no Google Analytics. Exemplos:

gtag.js: novo tipo do Google Analytics
analytics.js: antigo tipo do Google Analytics

Quando chegar um pedido com o valor "coupon" correspondente ao código de promoção personalizado criado no sistema, o pedido será atribuído ao afiliado com esse código de promoção.

Para transferir pedidos com um código de promoção regular (não personalizado), não é necessário configurar a transferência de dados por código de promoção.

Como configurar a transferência de dados de backup

Se o "contador" do Google Analytics foi bloqueado por um bloqueador de anúncios no navegador do usuário, o Google Analytics pode não registrar a ação do usuário.

Para que a ação seja registrada corretamente, você pode opcionalmente transferir dados de ações para o Google Analytics de seu banco de dados usando o protocolo de transferência de dados estatísticos Google Measurement Protocol.

GA_API.drawio.png

Para transferência de dados de backup de ações:

1. Quando um usuário acessar o site, extraia os valores das tags UTM do link de afiliado e sobrescreva-os quando chegarem novos usuários.

<!--?php 
$cookie_name = 'utm_cookie'; $expires_days = 90;

  foreach ($GET as $param_name => $param_value) { if (substr($param_name, 0, 4) === 'utm')
  { $cookie_string = $cookie_string . $param_name . '=' . $param_value . ';'; }
  }


  if (isset($cookie_string)) { setcookie($cookie_name, $cookie_string, time() +
  $expires_days * 24 * 60 * 60, '/'); } ?-->

2. Transfira as tags UTM com os dados do pedido para o banco de dados do site.

3. Transfira os dados do pedido do banco de dados do site para o Google Analytics usando o Google Measurement Protocol.

Você pode configurar a transferência de dados do banco de dados do site para o Google Analytics usando o Google Measurement Protocol de acordo com a documentação do Google.