Integração por meio de requisição-postback

  • Atualizado

Ao integrar por meio de requisição-postback, o servidor do anunciante envia uma requisição com informações sobre as ações executadas em seu site para o servidor da Admitad. O servidor Admitad recebe esses dados e os registra nas estatísticas..

Características de integração por meio de postback:

  • As alterações no site não afetam o envio de requisições por meio de postback.
  • É um tipo mais seguro de integração porque a requisição contém uma chave de autorização particular. Além disso, as requisições são enviadas a partir dos endereços IP conhecidos e a fonte de requisições pode ser verificada a qualquer momento pelo registros.
  • Há plugins prontos para integração com lojas nas plataformas de CMS populares (WooCommerce, OpenCart ou Magento).
  • Para implementar a solução, é preciso acessar o back-end do site.
  • Se tiver versão móvel do site ou aplicativo, formulários de pedidos rápidos ou formulários de pedidos com um clique, eles também devem ser integrados..
  • Requisição-postback é enviada diretamente do seu servidor e não do lado do cliente (navegador do usuário).
  • Requisição-postback deve ser enviada apenas para as ações dos usuários que vieram da Admitad. Para identificar esses usuários, o parâmetro admitad_uid é usado.

O que é o admitad_uid? O mecanismo de funcionamento do link de afiliados

No decorrer do trabalho com o programa de afiliados, o afiliado insere seu link de afiliados em seu espaço publicitário. O link de afiliados é gerado com base no link de redirecionamento, que leva ao site do programa e contém os parâmetros GET necessários para a Admitad e utm-tags de anunciante. Um dos parâmetros-GET deve transferir o valor do admitad_uid, um identificador exclusivo que é gerado no lado da Admitad quando o usuário clicar num link. O admitad_uid armazena as informações particulares sobre o afiliado e a fonte de tráfego, com base nas guias o sistema Admitad reconhece quem dos afiliados trouxe o usuário para o site e a quem devem ser atribuídas suas ações.

Exemplo de um link de redirecionamento:
https://site.ru/?admitad_uid={{admitad_uid}}

O valor do parâmetro admitad_uid deve ser recebido do parâmetro GET após a entrada do usuário no site e salvo por 90 dias nos cookies. Após a autorização do usuário, admitad_uid deve ser registrado no banco de dados e associado à conta do usuário.. O link pode levar o usuário para qualquer página do site, por isso é necessário rastrear o admitad_uid em todas as páginas. Quando o usuário executar uma ação, é preciso verificar se ele tem o admitad_uid. Se houver, seu valor deve ser inserido em uma requisição-postback.

O cookie ou seu tempo de vida não devem ser alterados quando o cliente vem através de outras fontes gratuitas, tais como pesquisa orgânica ou e-mail em massa. O sistema da Admitad usa o modelo de atribuição Last Paid Click (último clique pago), de acordo com o qual a ação é creditada à última fonte de tráfego pago.

Esquema geral do processo

postback_integration_PT.png

Etapas de integração

  1. Implemente um algoritmo de criação de cookie e insira o valor de admitad_uid nele.
  2. Implemente o algoritmo para obter o valor de admitad_uid do cookie e registre-o no banco de dados no momento da autorização de um usuário.
  3. Implemente o mecanismo de envio de uma requisição-postback do seu servidor (por exemplo cURL, Wget, file_get_contents).
  4. Determine o preço, a quantidade e os outros parâmetros de cada produto no carrinho.
  5. Substitua esses valores em uma matriz de parâmetros de solicitação de postback.

Não há nenhuma resposta especial do servidor da Admitad para a requisição-postback. É retornado o status HTTP 200 OK é retornado.

 

Como definir o parâmetro GET admitad_uid nos cookies usando PHP

if (isset($_GET['admitad_uid'])) {
$days = 90;
setcookie('_aid', $_GET['admitad_uid'], time() + 60 * 60 * 24 * $days, '/');
}

function get_admitad_uid() {
if (!isset($_COOKIE[‘_aid’])) {
return null;
}

return $_COOKIE['_aid'];
} 

 

Configuração de uma requisição-postback

Parâmetros obrigatórios

Nome do parâmetro
(aliases  são destacados em itálico)

Descrição Tipo Observação
uid ID Admitad  cadeia

o valor gerado, quando usuário faz o login no site e está incluído no parâmetro admitad_uid.

Se você permitir publicidade contextual em seu programa afiliado, quando os usuários clicarem nos anúncios do Google Ads de afiliados, em vez do valor uid, o gclid gerado pelo Google será atribuído ao parâmetro admitad_uid.

Para que o rastreamento de ações funcione corretamente, seu servidor deve ser capaz de receber e transmitir o valor inteiro do parâmetro gclid. Mais informações sobre o tamanho do parâmetro gclid

campaign_code código da campanha cadeia, 10 caracteres uma constante, o valor é definido em requisição-postback enviada para você no início da integração.

order_id, oid

Seu ID de ordem interior cadeia, 1-100 caracteres

Seu ID de ordem interior

Importante! Certifique-se de que você pode localizar o pedido no seu CRM pelo este id, pois ele será usado no futuro para a verificação.

action_code, ac, product, product_code

código de ação número inteiro uma variável, o valor é fornecido pelo especialista de rastreamento no início da integração.
tariff_code, tc código de tarifa número inteiro uma variável, o valor é fornecido pelo especialista de rastreamento no início da integração.
currency_code, currency, c código de moeda cadeia, 3 caracteres é definido em ISO 4217; somente valores literais são aceitos.
position_id, pid  número do item no carrinho número inteiro uma variável, valor varia de 1 para N, onde N = position_count.
position_count, pc, pn número de itens no carrinho número inteiro variável, valor N, depende da composição do carrinho, formado pelo usuário.
payment_type tipo de ação cadeia, 4 caracteres uma constante, valor sale/lead
product_id, prid Seu ID de ordem interior cadeia, 1-100 caracteres Seu ID de produto interior deve corresponder ao ID do feed de produto.
quantity número de unidades do item número inteiro ou fracionário  
postback, pb chave de autorização da solicitação de postback cadeia, 1 caracter uma constante, valor 1
postback_key, postback_hash, pk chave de identificação da solicitação de postback cadeia, 32 caracteres uma constante, o valor é definido em requisição-postback, enviada para você no início da integração.
price, cart, p, amount o valor de uma unidade do produto no carrinho número inteiro ou fracionário  

 

Opcionalmente, você pode adicionar o parâmetro client_id que conterá um ID de cliente em seu sistema.

 

Observação

Este conjunto de parâmetros é necessário para a integração de sites tipo Loja virtual. Se o seu site pertence a uma categoria diferente (negócios financeiros ou turísticos, serviços de Internet, jogos online, serviços para dispositivos móveis), o conjunto de parâmetros necessários pode ser alterado.

Por exemplo, uma operadora de turismo não tem parâmetros responsáveis pela repartição do carrinho, e há apenas o valor do pacote de viagem e o número do pedido. Nesse caso, serão necessários os parâmetros order_id e price, e não vai ter os parâmetros position_id, position_count.

Para descobrir quais parâmetros são obrigatórios no seu caso, entre em contato com o gerente da sua conta.

 

Exemplo de uma requisição-postback do carrinho com vários itens de produto

Posição

Nome do produto

Preço Quantidade

Valor total

1 TV 20 000 2 40 000
2 iPhone 35 000 3 105 000
3 Notebook 50 000 1 50 000
      Total

195 000

 

https://ad.admitad.com/r?campaign_code=your_campaign_code&postback=1&postback_key=your_postback_key
&action_code=1 &uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1¤cy_code=RUB
&price=20000&quantity=2&position_id=1 &position_count=3&product_id=11&client_id=&payment_type=sale

https://ad.admitad.com/r?campaign_code=your_campaign_code&postback=1&postback_key=your_postback_key
&action_code=1&uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1&currency_code=RUB
&price=35000&quantity=3&position_id=2&position_count=3&product_id=21&client_id=&payment_type=sale

https://ad.admitad.com/r?campaign_code=your_campaign_code&postback=1&postback_key=your_postback_key
&action_code=1&uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1&currency_code=RUB
&price=50000&quantity=1&position_id=3&position_count=3&product_id=31&client_id=&payment_type=sale

Para cada item do produto, uma solicitação separada deve ser enviada. Cada pedido deve conter informações diferentes sobre o preço, quantidade, número de seqüência no carrinho de compras, etc.

 

Configuração de transferência de códigos promocionais únicos

Códigos promocionais únicos são códigos promocionais atribuídos ao afiliado específico. Leia mais sobre eles aqui.

Se você pretende trabalhar com os códigos promocionais únicos:

1. Certifique-se que há um campo "código promocional" no formulário de pedido no site.

2. Insira o código promocional único do formulário de pedido no parâmetro promocode.

 Nome do parâmetro  Descrição  Tipo
 promocode  código de código promocional único  cadeia, 255 caracteres

 

Exemplo de uma requisição-postback

https://ad.admitad.com/r?campaign_code=your_campaign_code&postback=1&postback_key=your_postback_key 
&action_code=1&uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1&currency_code=RUB 
&price=50000&quantity=1&position_id=3&position_count=3&product_id=31&client_id=&payment_type=sale
&promocode=admitad500

3. Certifique-se de que todos os pedidos com um código promocional único são enviados para a Admitad.
    Para a Admitad o pedido deve ser transferido nos seguintes casos:

  • há um admitad_uid e um código promocional único;
  • há apenas um código promocional único;
  • há apenas um admitad_uid.

     As informações sobre o pedido com o código promocional único não devem ser transferidas em outros canais.

 

Procedimento de teste

1. Depois de configurar o algoritmo de envio de requisições-postback do servidor, entre em contato com o departamento de rastreamento da Admitad e solicite um link de afiliados para fazer um teste.

2. Faça os pedidos de teste. Certifique-se de que:

  • o admitad_uid é processado em todas as páginas do site;
  • o admitad_uid é salvo no cookie e no banco de dados e vincula-se à conta pessoal do usuário;
  • o tempo de vida de um cookie com admitad_uid corresponde ao contrato, cookie não é excluído quando o usuário chega através de uma pesquisa orgânica;
  • quando a ação for executada, as requisições-postback são enviadas do seu servidor e não do lado do cliente.
  • requisições são enviados para todas as ações e tarifas do seu programa de afiliados;
  • para cada unidade de produto no carrinho será enviada uma requisição;
  • número e o valor do pedido são transferidos corretamente;
  • rastreamento é configurado na versão móvel do site (se houver), formulários de pedido rápidos e formulários de pedido em 1 clique, etc.

3. Se o rastreamento estiver configurado corretamente, as ações aparecem nos relatórios da Admitad (Conta pessoal — Relatórios — Por ações).

2019-04-03_10-28-21.png

Informe, por favor, o especialista técnico da Admitad que o teste foi bem-sucedido. Em seguida, a campanha estará pronta para o lançamento.

4. Se a ação não aparecer nos relatórios dentro de uma hora, ou o erro ocorreu na hora da implementação do mecanismo de envio de requisição ou os parâmetros de requisição são inválidos. Certifique-se de que:

  • você não cometeu nenhum erro na implementação do mecanismo de requisição-postback;
  • a requisição contém exatamente aqueles campaign_code e postback_key que foram enviados para você no início da integração.

Para identificar o erro, vá para o log de pedidos (Ferramentas — Pedidos de pagamento). O texto de erro é especificado no campo Resultado. Corrija o erro e execute o teste novamente. Manual da seção Pedidos de pagamento se encontra aqui.

 

Integração por meio de plugins

Se sua loja foi construída na plataforma WooCommerce, OpenCart ou Magento, você pode usar o plugin apropriado para uma integração rápida com a Admitad. Leia mais sobre isso no artigo Integração por meio de plugins.

Esse artigo foi útil?