#
Macros de retorno de chamada #
As macros são espaços reservados para valores que variam dinamicamente no pedido de servidor de um URL. Estas macros vêm pré-configuradas para as redes integradas do Tenjin, mas compreender o funcionamento das macros pode ser útil para quaisquer canais personalizados que pretenda adicionar.
Por que precisamos de macros? #
Precisamos de macros para transmitir dados que variam dinamicamente através de parâmetros de links de rastreamento que permanecem inalterados.
Para aprofundar este assunto, vamos explicar como funcionam as URLs, os parâmetros, os valores e os valores que mudam dinamicamente no Attribution.
URLs e parâmetros #
Vamos dar uma vista de olhos a um URL padrão: https://track.tenjin.com?param1=value1. Nesta URL, pode ver-se que existe um endereço de servidor track.tenjin.io e um único parâmetro param1 definido com o valor value1. Quando esta URL chega ao servidor track.tenjin.io, o servidor da Tenjin lê esta URL e analisa o parâmetro e o valor. Neste caso, param1 está definido como value1.
Num exemplo mais realista relacionado com os parâmetros e valores de atribuição, considere este URL com dois parâmetros (id_publicitário e país) e dois valores: https://track.tenjin.com?advertising_id=xyz123&country=US. Quando este pedido chega ao servidor Tenjin em track.tenjin.com, sabemos que o id_publicitário que acede ao servidor é o dispositivo xyz123 com um país dos EUA.
Valores dinâmicos dos parâmetros #
Agora que já sabemos como os valores e os parâmetros são transmitidos a um servidor, vamos ver como as URLs são utilizadas no contexto da atribuição e do rastreamento.
Para que o Tenjin possa atribuir um utilizador a um clique ou a uma impressão, o Tenjin recolhe informações sobre o dispositivo e as suas propriedades em cada clique ou impressão. Estas propriedades são utilizadas para estabelecer uma correspondência com as propriedades recolhidas quando um dispositivo instala a aplicação.
É gerada uma URL de rastreamento Tenjin sempre que criar uma campanha para uma rede que não seja da SAN ou para um canal personalizado. Esta URL de rastreamento contém “macros” que se adaptam dinamicamente aos valores variáveis relacionados com o clique ou a impressão. As macros são utilizadas como espaços reservados para valores que variam numa URL específica.
Suponhamos que queira realizar uma campanha numa rede que não seja SAN. Crie um link de rastreamento através do painel de controlo do Tenjin e forneça-o à sua rede de publicidade.
Eis um exemplo de como pode ser um link de rastreamento da Tenjin: https://track.tenjin.com?advertising_id={idfa}&country={country}
Neste caso {idfa} e {país} são macros. Quando um dispositivo utiliza esta ligação, a Rede de Publicidade preencherá estas macros com os valores reais do dispositivo. Utilizando o exemplo anterior, {idfa} e {país} preencheria os valores com xyz123 e EUA respectivamente.
Depois de preenchido, a rede de publicidade ou o canal irá aceder ao servidor da Tenjin utilizando o seguinte URL:
https://track.tenjin.com?advertising_id=xyz123&country=US
Em alternativa, se o dispositivo do utilizador tivesse mudado e tivesse um advertising_id de abc234 e um country de CA, o URL passaria a ser: https://track.tenjin.com?advertising_id=abc234&country=CA
Como se pode ver, estes cenários utilizam o mesmo URL, mas alteram os valores consoante o dispositivo ou o utilizador que está a utilizar o link de rastreamento.
As macros permitem que as redes de publicidade alterem o URL para cada clique ou impressão de cada utilizador. Estas macros são simplesmente espaços reservados para os valores que variam à medida que diferentes utilizadores interagem com os links de rastreamento.
#
Macros para callbacks de redes de publicidade #
Cada rede de publicidade tem o seu próprio conjunto de macros de cliques e impressões para as seguintes propriedades dos dispositivos:
- ID de publicidade
- Endereço IP
- ID do pacote
- País
- ID do clique
- Site
- Plataforma do sistema operativo
- Limitar o rastreio de anúncios
- Criativo
Se a rede publicitária estiver pré-configurada e integrada com o Tenjin, cada uma das macros da rede publicitária aparecerá automaticamente em cada URL de clique ou link de rastreio de impressões para cada campanha.
A título de exemplo:
- A macro "advertising_id" do Axon da AppLovin
tem o seguinte aspeto:{IDFA} - A macro
advertising_idda Tapjoy tem o seguinte aspeto:TAPJOY_ADVERTISING_ID
Consequentemente, os URLs de clique do Axon da AppLovin e da Tapjoy podem ter um aspeto semelhante a este:
- Axon da AppLovin:
https://track.tenjin.com/v0/id?advertising_id={IDFA} - Tapjoy:
https://track.tenjin.com/v0/id?advertising_id=TAPJOY_ADVERTISING_ID
Mais uma vez, cada rede terá o seu próprio formato de macro. Se a rede já estiver pré-integrada com o Tenjin, não precisa de se preocupar com isso. Isto serve apenas para que saiba como são construídas as URLs de cliques e de impressões.
#
Macros suportadas #
Ao configurar um callback do Tenjin para outro serviço, pode utilizar macros para representar valores de dados que variam dinamicamente, a enviar para outros servidores/serviços. É a isto que chamamos “Roteamento”.
O Tenjin permite-lhe “encaminhar” dados de eventos em direto para outros servidores em tempo real.
Esta é uma lista das macros de callback disponíveis que pode configurar ao enviar dados para outros serviços.
Macros relacionadas com a aplicação #
| Macro | Explicação |
|---|---|
{{app_version}} | Versão da aplicação. (1.0.3) |
{{bundle_id}} | ID do pacote da aplicação. (com.tenjin.wordfinder) |
{{lowercase_bundle_id}} | Versão em minúsculas do ID do pacote da aplicação. (com.tenjin.wordfinder) |
{{platform}} | Plataforma da aplicação (iOS) |
{{user_agent}} | Agente do utilizador |
{{sdk_version}} | Versão do Tenjin SDK do utilizador |
{{store_id}} | ID da aplicação na App Store (887212194) |
Macros relacionadas com a atribuição #
| Macro | Explicação |
|---|---|
{{acquired_at_s}} | Carimbo temporal do evento «Instalação» em segundos |
{{acquired_at_ms}} | Carimbo temporal do evento «Instalação» em milissegundos |
{{engaged_at_s}} | Data e hora do evento de clique ou impressão, em segundos |
{{engaged_at_ms}} | Data e hora do evento de clique ou impressão, em milissegundos |
{{ad_network}} | Nome do canal ao qual um utilizador está associado |
{{campaign_id}} | O mesmo que {{remote_campaign_id}} |
{{campaign_name}} | Nome da campanha Tenjin à qual o utilizador está associado |
{{campaign_name_encoded}} | Nome da campanha «Tenjin» codificado a que o utilizador está associado |
{{click_id}} | ID do clique do canal, caso o utilizador seja atribuído a canais pagos |
{{creative_name}} | Nome criativo |
{{deeplink_url}} | URL do link direto |
{{is_conversion_integer}} | 1 para a primeira abertura da aplicação, 0 para outros eventos |
{{is_impression}} | 1 => Atribuição por visualização, 0 => Atribuição por clique |
{{is_install_or_landing}} | Na primeira vez que a aplicação for aberta, selecione “Instalar”; nas vezes seguintes, selecione “página inicial” |
{{ip_address}} | Endereço IP do utilizador |
{{ip_address_click}} | Endereço IP para o evento de clique ou de impressão |
{{remote_campaign_id}} | ID da campanha do canal ao qual o utilizador está associado |
{{site_id}} | ID do canal ao qual um utilizador está associado |
{{site_id_encoded}} | ID do site do canal codificado ao qual o utilizador está associado |
{{ad_network_short_id_match_type}} | Se o utilizador vier de uma atribuição por dispositivo, probabilística ou por referenciador, a parte ad_network_short_id varia consoante a rede; por favor, contacte-nos para obter mais detalhes. |
{{is_organic}} | ‘1’ -> o utilizador é atribuído ao canal orgânico, ‘0’ -> o utilizador é atribuído a um canal não orgânico |
{{tenjin_campaign_id}} | ID da campanha Tenjin atribuído ao utilizador |
{{tenjin_parameter_0}} | Macro de reencaminhamento que permite reencaminhar a partir de um clique num URL |
{{tenjin_parameter_1}} | Macro de reencaminhamento que permite reencaminhar a partir de um clique num URL |
{{tenjin_parameter_2}} | Macro de reencaminhamento que permite reencaminhar a partir de um clique num URL |
{{tenjin_parameter_3}} | Macro de reencaminhamento que permite reencaminhar a partir de um clique num URL |
{{tenjin_parameter_4}} | Macro de reencaminhamento que permite reencaminhar a partir de um clique num URL |
{{tenjin_parameter_5}} | Macro de reencaminhamento que permite reencaminhar a partir de um clique num URL |
Macros relacionadas com o identificador do dispositivo #
| Macro | Explicação |
|---|---|
{{advertising_id}} | Identificador de publicidade do dispositivo |
{{analytics_installation_id}} | Identificador específico da instalação da aplicação. Em minúsculas, sem hífen. |
{{developer_device_id}} | Identificador do fornecedor (IDFV) ou o ID do dispositivo do programador |
{{formatted_advertising_id}} | Identificador de publicidade do dispositivo, 00000000-0000-0000-0000-000000000000 se estiver vazio |
{{imei}} | IMEI |
{{md5_advertising_id}} | MD5 do identificador de publicidade |
{{lowercase_advertising_id}} | Identificador de publicidade do dispositivo em minúsculas |
{{md5_imei}} | MD5 do IMEI |
{{md5_oaid}} | MD5 do OAID |
{{oaid}} | OAID |
{{customer_user_id}} | ID do utilizador da aplicação, tal como definido pelo método setCustomerUserId do SDK |
Macros relacionadas com as propriedades do dispositivo #
| Macro | Explicação |
|---|---|
{{allow_ad_tracking}} | O dispositivo permite o rastreio de anúncios? (verdadeiro, falso) |
{{allow_ad_tracking_integer}} | O dispositivo permite o rastreio de anúncios? (1, 0) |
{{carrier}} | Suporte para dispositivos |
{{connection_type}} | Tipo de ligação |
{{country}} | Código do país do dispositivo do utilizador |
{{device}} | Dispositivo do utilizador |
{{device_brand}} | Marca do dispositivo |
{{device_model}} | Modelo do dispositivo |
{{language}} | Definição de idioma do utilizador |
{{limit_ad_tracking}} | O dispositivo limita o rastreio de anúncios? (verdadeiro, falso) |
{{limit_ad_tracking_integer}} | O dispositivo limita o rastreio de anúncios? (1, 0) |
{{locale}} | Configuração regional do dispositivo |
{{os_version}} | Versão do sistema operativo do utilizador |
{{os_version_release}} | Versão do sistema operativo do utilizador |
{{referrer}} | Referência Android |
{{timezone}} | Fuso horário do dispositivo |
{{tracking_status}} | Número inteiro correspondente ao estado ATT do dispositivo iOS. 0 => não determinado, 1 => restrito, 2 => recusado, 3 => autorizado |
Macros relacionadas com eventos #
| Macro | Explicação |
|---|---|
{{currency}} | Código da moeda de 3 dígitos da compra |
{{event}} | Nome do evento |
{{time_in_seconds}} | Tempo da solicitação em segundos |
{{time_in_ms}} | Tempo da solicitação em milissegundos |
{{time_iso8601}} | Hora do pedido no formato ISO 8601 |
{{revenue}} | Receita bruta obtida com uma compra na moeda original |
{{revenue_usd_net}} | Receita líquida em dólares americanos por compra |
{{revenue_usd_gross}} | Receita bruta em dólares americanos de uma compra |
{{value}} | Valor de evento personalizado |
{{value_micro}} | Valor do evento personalizado dividido por 1 000 000. Esta macro é utilizada para enviar um valor decimal através de uma chamada de retorno, enviando o valor real multiplicado por 1 000 000 por meio de um evento personalizado. |
Macros relacionadas com impressões de anúncios #
- AppLovin
| Macro | Explicação |
|---|---|
{{ilrd::ad_unit_id}} | ID do bloco de anúncios comunicada pela rede vencedora |
{{ilrd::currency}} | As receitas publicitárias em moeda são apresentadas em |
{{ilrd::ad_format}} | Formato do bloco de anúncios |
{{ilrd::mediation_country}} | País do prestador de serviços de mediação |
{{ilrd::network_name}} | Rede que exibiu o anúncio |
{{ilrd::ad_revenue}} | Receitas comunicadas pela rede de publicidade |
{{ilrd::network_placement}} | Colocação definida pela rede |
{{ilrd::placement}} | Posicionamento do bloco de anúncios |
{{ilrd::creative_id}} | ID criativo do bloco de anúncios |
{{ilrd::precision}} | Precisão das receitas |
- Unity LevelPlay
| Macro | Explicação |
|---|---|
{{ilrd::ab_test}} | Valor do teste A/B |
{{ilrd::ad_format}} | Formato do bloco de anúncios |
{{ilrd::ad_revenue}} | Receitas comunicadas pela rede de publicidade |
{{ilrd::auction_id}} | ID do leilão proveniente da mediação da Ironsource |
{{ilrd::ecpm}} | eCPM da mediação da Ironsource |
{{ilrd::instance_id}} | ID da instância da mediação da Ironsource |
{{ilrd::instance_name}} | Nome da instância proveniente da mediação da Ironsource |
{{ilrd::mediation_country}} | (não utilizado; iremos utilizar a macro «Tenjin country») |
{{ilrd::mediation_ltv}} | Receitas acumuladas provenientes da mediação da Ironsource |
{{ilrd::network_name}} | Rede que exibiu o anúncio |
{{ilrd::placement}} | Posicionamento do bloco de anúncios |
{{ilrd::precision}} | Precisão das receitas |
{{ilrd::segment}} | Nome do segmento proveniente da mediação da Ironsource |
- AdMob
| Macro | Explicação |
|---|---|
{{ilrd::precision}} | Tipo de precisão definido pelo AdMob |
{{ilrd::ad_unit_id}} | ID do bloco de anúncios definido pelo AdMob |
{{ilrd::currency}} | Código da moeda do AdMob |
{{ilrd::adapter_class}} | Classe adaptadora da rede de publicidade |
{{ilrd::response_id}} | ID da resposta fornecida pelo AdMob |
{{ilrd::ad_revenue_micro}} | Receitas publicitárias em microcêntimos fornecidas pela AdMob |
- Topon
| Macro | Explicação |
|---|---|
{{ilrd::mediation_country}} | País do prestador de serviços de mediação |
{{ilrd::ad_network_type}} | Tipo de rede, promoção cruzada ou intercâmbio |
{{ilrd::adsource_index}} | Ordenação da fonte de anúncios atual na Waterfall |
Atribuições SAN #
- Meta
| Macro | Explicação |
|---|---|
{{meta::account_id}} | Conta publicitária utilizada para criar o anúncio |
{{meta::ad_id}} | ID único do anúncio clicado/visualizado antes da conversão |
{{meta::ad_objective_name}} | Objetivo selecionado aquando da criação da campanha (por exemplo, MOBILE_APP_INSTALLS, CONVERSIONS) |
{{meta::adgroup_id}} | ID do anúncio Meta |
{{meta::adgroup_name}} | Nome do Meta Ad |
{{meta::campaign_group_id}} | ID da meta-campanha |
{{meta::campaign_group_name}} | Nome da meta-campanha |
{{meta::campaign_id}} | ID do Meta AdSet |
{{meta::campaign_name}} | Nome do Meta AdSet |
{{meta::click_time}} | Data e hora do último clique num anúncio antes da atribuição |
{{meta::engagement_type}} | Tipo de interação para atribuição (por exemplo, engaged_view) |
{{meta::is_fb}} | Se a instalação foi feita a partir do Meta |
{{meta::is_modeled}} | Se a atribuição é modelada ou determinística |
{{meta::is_paid}} | Se a instalação foi feita a partir de um canal pago na Meta |
{{meta::is_view_through}} | Se a atribuição foi baseada em visualizações ou em cliques |
{{meta::platform_position}} | Formato de anúncio apresentado na plataforma |
{{meta::publisher_platform}} | Plataforma onde o anúncio foi exibido (por exemplo, AUDIENCE_NETWORK, INSTAGRAM, MESSENGER, FACEBOOK) |
{{meta::view_time}} | Data e hora da última visualização do anúncio antes da atribuição |
Pode ler mais sobre o encaminhamento e a utilização destas macros na configuração de callback.