OneLink Smart Script V2

Visão geral: personalize OneLinks que são gerados e incorporados automaticamente atrás de um botão ou banner no site da sua marca.

Sobre o OneLink Smart Script

OneLink Smart Script usa URLs de entrada que levam à página web para gerar automaticamente URLs exclusivas de saída OneLink que levam à loja de aplicativos.

As URLs de saída são geradas usando argumentos que você recebe do profissional de marketing e entrada no script. Observação: O argumento afParameters tem uma estrutura composta de vários outros argumentos (parâmetros), e cada um contém um objeto de configuração que tem chaves, valores de substituição e um valor padrão.

Etapas de implementação

Para configurar o Smart Script, você pode:

Embed the script in your website

A inicialização do Smart Script e o código de chamada podem vir do gerador de Smart Script no painel da AppsFlyer (recomendado) ou importados e chamados manualmente pelo desenvolvedor.

📘

Preservar parâmetros de URL de entrada

Para garantir que os parâmetros de URL de entrada sejam mapeados para o OneLink gerado, é recomendável importar o Smart Script em todas as páginas do site, independentemente de um OneLink ser gerado na página ou não.

Disponível a partir da versão 2.5.0.

Mais detalhes e um exemplo completo aqui.

Usar código gerado pelo Smart Script Generator

  1. Obtenha o arquivo do profissional de marketing que inclui o script, o código de inicialização e os argumentos.
  2. Test the script on the Smart Script test page. Ensure the correct outgoing URL is generated.
  3. Siga o teste e use as instruções de resultados do Smart Script.

Veja o exemplo de integração no Github

Configurar manualmente o script

  1. Fazer download do script.
  2. Obtenha os argumentos para chamar o script que mapeia os parâmetros de entrada para os parâmetros de saída do profissional de marketing.
  3. Inicialize os argumentos e os objetos de configuração do Smart Script.
  4. Gere os URLS chamando o script no HTML da web/página inicial usando o seguinte método:
var result = window.AF_SMART_SCRIPT.generateOneLinkURL({
  oneLinkURL,
  afParameters,
  referrerSkipList, // optional
  urlSkipList // optional
})
  1. Siga o teste e use as instruções de resultados do Smart Script.

Verificar e usar o resultado do Smart Script

  1. Verifique o valor de retorno em result. Os possíveis valores de retorno são:
    • An outgoing Onelink URL. Use the result value as needed. For example, to place it as a link under a CTA on your website.
    • null. Se o script retornar null, implemente o fluxo de erro desejado. Por exemplo: o URL existente da web/página inicial não é alterado.
      var result_url = "No output from script"
      if (result) {
            result_url = result.clickURL;            
            // Put the generated OneLink URL behind CTA buttons
            document.getElementById('andrd_link').setAttribute('href', result_url);
            document.getElementById('ios_link').setAttribute('href', result_url);
            // Optionally - Create QR code from the generated OneLink URL
            window.AF_SMART_SCRIPT.displayQrCode("my_qr_code_div_id");
            //The size of the QR code is defined in the CSS file under #my_qr_code_div_id
            // #my_qr_code_div_id canvas { 
            //  height: 200px;
            //  width: 200px;
            //}
            // Optionally - fire an impression.
            // The impression will fire to https://impressions.onelink.me//.... 
            setTimeout(() => {
              window.AF_SMART_SCRIPT.fireImpressionsLink();
              console.log("Impression fired"); 
            }, 1000);
      }

Use Google Tag Manager

Para configurar o Smart Script no Google Tag Manager:

  1. Confirm that the marketer followed their instructions and placed the Smart Script code into GTM.
  2. Verifique o valor de retorno em AF_SMART_SCRIPT_RESULT. Os possíveis valores de retorno são:
    • Um URL OneLink de saída. Use o valor do resultado conforme necessário. Por exemplo, para colocá-lo como um link em um CTA em seu site.
    • null. Se o script retornar null, implemente o fluxo de erro desejado. Por exemplo: o URL existente da web/página inicial não é alterado.
      var result_url = AF_SMART_SCRIPT_RESULT.clickURL;
      if (result_url) {
            document.getElementById('andrd_link').setAttribute('href', result_url);
            document.getElementById('ios_link').setAttribute('href', result_url);
            // Optionally - Create QR code from the generated OneLink URL
            window.AF_SMART_SCRIPT.displayQrCode("my_qr_code_div_id");
            //The size of the QR code is defined in the CSS file under #my_qr_code_div_id
            // #my_qr_code_div_id canvas { 
            //  height: 200px;
            //  width: 200px;
            //}
            // Optionally - fire an impression.
            // The impression will fire to https://impressions.onelink.me//.... 
            setTimeout(() => {
              window.AF_SMART_SCRIPT.fireImpressionsLink();
              console.log("Impression fired"); 
            }, 1000);            
      }
  1. Test the script on the Smart Script test page. Ensure the correct outgoing URL is generated.

Create a QR code with the Smart Script result

Pré-requisito: Smart Script V2.6+

📘

Melhores práticas

  • Personalize o código QR de acordo com a marca do seu aplicativo com um logotipo central e uma cor de código relevante
  • Mostrar o código QR quando os usuários estiverem no computador e mostrar o botão com o link quando os usuários estiverem no celular

Para criar um código QR:

  1. Crie uma tag div com um ID específico na página HTML do seu site para hospedar o código QR.
    Você pode definir o estilo da tag div como quiser.
  2. Depois de executar o Smart Script e gerar um URL do OneLink, chame o seguinte método displayQrCode

displayQrCode


Assinatura do método

const qrOptions = {
  logo,
  colorCode
}

window.AF_SMART_SCRIPT.displayQrCode(divId, qrOptions)

Argumentos de entrada

TipoObrigatórioNomeDescriçãoComentário
StringSimdivIDA div com um ID específico na página HTML do seu site para hospedar o código QR
ObjectNãoqrOptionsObjeto de configuração (veja detalhes na tabela abaixo)Se o objeto estiver faltando, o código QR será criado sem logotipo na cor padrão

qrOptions object

TipoObrigatórioNomeDescriçãoComentário
StringNãologoUm URL de imagem válido ou um URI de dados de imagemSe o valor for inválido, o código QR será gerado sem o logotipo
StringNãocolorCodeCor hexadecimal do código QRSe o valor for inválido, a cor do código retornará à cor preta padrão

Exemplos de uso:

Fire an impression

You can fire an impression when a page loads, a CTA or banner displays, etc. Note: Impressions can only be fired on mobile devices; not on desktop.

Pré-requisitos: Smart Script V2,2+

Para disparar uma impressão:

  1. Siga as instruções para executar o Smart Script e gerar um URL clicável.
  2. Certifique-se de que o resultado seja válido (e não nulo).
  3. Execute a seguinte função de impressão:

🚧

Uma solução alternativa obrigatória

Por favor, finalize a chamada para fireImpressionsLink com setTimeout para garantir que haja pelo menos 1 segundo de atraso entre a chamada para generateOneLinkURL and fireImpressionsLink

setTimeout(() => {
  window.AF_SMART_SCRIPT.fireImpressionsLink();
  console.log("Impression fired"); 
}, 1000);

You can find examples for firing impressions for mobile only and for cross platform support

Argumentos

Argumento Observações Exemplo
oneLinkURL (obrigatório)
  • Forneça o domínio do template do OneLink + ID do template. Nota: não forneça um URL de link personalizado do OneLink!
  • yourbrand.onelink.me/A1b2
  • Exemplo de domínio de marca: clique.suamarca.com/A1b2

afParameters

(obrigatório)

 

 

 


mediaSource

(obrigatório)

Objeto de configuração para fonte de mídia

  • Chaves: ['incoming_mediasource' 'utm_source']
  • Substituir valores: {twitter: 'twitter_int', orig_src: 'new_src'}
  • Valor padrão: ['any_source']

campaign

Objeto de configuração para campanha

  • Chaves: ['incoming_campaign', 'utm_campaign']
  • Substituir valores: {campaign_name: 'new_campaign_name'}
  • Valor padrão: ['any_campaign_name']

channel

Objeto de configuração para canal

  • Chaves: ['incoming_channel', 'utm_channel']
  • Substituir valores: {video: 'new_video'}
  • Valor padrão: ['any_video']

ad

Objeto de configuração para anúncio

  • Chaves: ['incoming_ad', 'utm_ad']
  • Substituir valores: {ad_name: 'new_ad_name'}
  • Valor padrão: ['any_ad_name']
adSet

Objeto de configuração para adset

  • Chaves: ['incoming_adset', 'utm_adset']
  • Substituir valores: {'adset_name': 'new_adset_name'}
  • Valor padrão: ['any_adset_name']
deepLinkValue

Objeto de configuração para deep_link_value

  • Chaves: ['product_id', 'page_name']
  • Substituir valores: {twenty_percent_off: 'thirty_percent_off'}
  • Valor padrão: 'new_offers_page'
afSub1-5

Objeto de configuração para af_sub[1-5]

 
googleClickIdKey

Smart Script automatically maps the incoming GCLID parameter value to the outgoing GCLID parameter: gclid={gclid}.
Note! To display in AppsFlyer raw data reports, the param must be one of af_sub[1-5].

 
Outros parâmetros de consulta (personalizados)
  • Lista de quaisquer outros parâmetros que você deseja incluir na URL de saída do OneLink para atribuição ou deep linking, junto com seus objetos de configuração.
  • O nome do parâmetro personalizado é listado pelo desenvolvedor como paramKey no objeto de configuração.
  • paramKey: 'deep_link_sub1'
  • Chaves: ['page_id']
  • Substituir valores: {page12: 'new_page12'}
  • Valor padrão: 'page1'
 
referrerSkipList
Lista das strings no referenciador HTTP para um clique específico (por exemplo, Twitter ou Meta ads) que, se encontrado, faz com que o Smart Script retorne null. Isso pode ser útil para SRNs como Twitter e Meta ads, para os quais os cliques já são relatados.  
urlSkipList Lista das strings no URL de um clique específico (por exemplo af_r) que, se encontradas, fazem com que o Smart Script retorne null. Isso pode ser útil se você usar um link de atribuição da AppsFlyer com af_r para redirecionar usuários para seu site mobile e não quiser que os dados do clique original sejam perdidos.  
webReferrer This argument defines a key in the outgoing URL, which its value will be a copy of the HTTP document.referrer. The referrer is saved in the first page the user lands in, and may be used in any consecutive page in this domain which runs Smart Script with this argument.  

Objeto de configuração

O OneLink Smart Script usa argumentos para gerar um URL de saída com base nos parâmetros do URL de entrada e nos argumentos definidos no script. O argumento afParameters tem uma estrutura composta de vários outros argumentos (parâmetros) usados para atribuição e deep linking, e cada um contém um objeto de configuração que tem chaves, valores de substituição e um valor padrão, conforme descrito na tabela a seguir.

Argumento Descrição Exemplo
keys
  • Lista de sequências de caracteres
  • Lista de parâmetros possíveis no URL de entrada que o script procura, cujo valor é colocado como o valor no URL de saída.
  • O script pesquisa da esquerda para a direita e para na primeira partida.
  • Exemplo: ['in_channel', 'utm_channel']
  • Para o parâmetro do canal no script, o script pesquisa o link de entrada para in_channel e usa o valor como o valor para channel.

overrideValues

  • Dictionary {string: string}
  • Para valores que você deseja alterar no link de saída, liste os valores no URL de entrada, junto com o que você deseja que eles sejam substituídos.
  • O script substitui os valores de parâmetro do URL de entrada pelos valores que você define. 

Exemplo: {'video': 'video_new'}

Para o parâmetro do canal no script, sempre que o valor de entrada for video, o script o altera para video_new no link de saída.

defaultValue
  • Sequência de caracteres
  • Indique qual valor você quer para o seu "fallback".
  • Se um parâmetro não for encontrado na sua lista de chaves, o valor defaultValue será usado no URL de saída.
  • Você pode forçar um valor padrão passando uma lista de chaves vazia.

Exemplo: ['web_video']

Para o parâmetro do canal no script, se você tiver o parâmetro in_channel e ele não for encontrado, web_video será usado como o valor do canal.

Exemplos

Basic attribution

Veja um exemplo da conversão básica de uma URL de entrada para uma URL de saída OneLink, com uma única chave para a mídia_source e campanha

Multiple keys

Veja um exemplo da conversão de uma URL de entrada para uma URL de saída OneLink, com múltiplas chaves para mídia_source e campanha.

UTM parameters

Veja um exemplo da conversão de uma URL de entrada para uma URL de saída OneLink, com parâmetros UTM para mídia_source e campanha.

Override values

Veja um exemplo da conversão de uma URL de entrada para uma URL de saída OneLink, substituindo o valor da media_source de entrada.

Default values

Veja um exemplo da conversão de uma URL de entrada para uma URL de saída OneLink, usando o valor padrão quando um valor de media_source de entrada não é encontrado.

Forced default values

Veja um exemplo da conversão de uma URL de entrada para uma URL de saída OneLink, usando o valor padrão mesmo quando um valor de media_source de entrada é encontrado.

Google click ID passthrough

See example of the conversion of an incoming URL to an outgoing OneLink URL that passes the Google click ID to af_sub4 and gclid.
As of Smart Script version 2.8.1, the GCLID is automatically forwarded to the outgoing URL when present in the incoming URL.
Note: When a GCLID is detected, the script searches for the incoming keyword parameter, and inserts its value into the outgoing URL as the value for the af_keywords parâmetro.

Facebook click ID passthrough

See example of the conversion of an incoming URL to an outgoing OneLink URL that passes the Facebook click ID to af_sub2 and fbclid.
As of Smart Script version 2.8.1, the FBCLID is automatically forwarded to the outgoing URL when present in the incoming URL.

Set attribution and OneLink parameters

Veja um exemplo da conversão de uma URL de entrada para uma URL de saída OneLink com atribuição da AppsFlyer e parâmetros OneLink.

Set additional custom parameters

See example of the conversion of an incoming URL to an outgoing OneLink URL with additional custom parameters.

Referrer skip list

Veja um exemplo de como você pode desabilitar o Smart Script para um determinado clique (por exemplo, do Twitter ou Meta ads) criando uma lista de exceções. Se alguma das strings na lista de exceção aparecer no referenciador HTTP do clique, o Smart Script retornará null.

URL skip list

Veja o exemplo de como você pode desabilitar o Smart Script para uma determinada string na URL (por exemplo, af_r) criando uma lista de exceções. Se alguma das strings na lista de exceções aparecer no URL do clique, o Smart Script retornará null.

Smart Script set up with Google Tag Manager

Veja um exemplo da conversão de uma URL de entrada para uma URL de saída OneLink usando o OneLink Smart Script configurado usando o Google Tag Manager.

Impressions - OneLink Template with mobile-only support

Veja um exemplo de impressões disparadas usando um template do OneLink que possui apenas um dispositivo móvel.

🚧

Uma solução alternativa obrigatória

Por favor, finalize a chamada para fireImpressionsLink com setTimeout para garantir que haja pelo menos 1 segundo de atraso entre a chamada para generateOneLinkURL and fireImpressionsLink

Impressions - OneLink Template with Cross-platform support

Veja um exemplo de impressões disparadas usando um template do OneLink que tem suporte para várias plataformas.
Por exemplo, uma impressão disparada de uma plataforma não mobile (por exemplo, desktop ou console).

📘

Firing an impression from a cross platform landing page

You can find here a code example for firing an impression from a demo landing page

🚧

Uma solução alternativa obrigatória

Por favor, finalize a chamada para fireImpressionsLink com setTimeout para garantir que haja pelo menos 1 segundo de atraso entre a chamada para generateOneLinkURL and fireImpressionsLink

Preserve incoming URL parameters across pages

📘

Disponível a partir da versão 2.5.0.

Parâmetros de entrada (por exemplo, utm_source) de uma página inicial não são passados para outras páginas no site por padrão.
Importar o Smart Script em todas as páginas do site preserva os parâmetros de URL de entrada e permite que o Smart Script os use em outras páginas.

Você pode encontrar aqui um exemplo deste caso de uso.

Copy HTTP referrer to outgoing URL

📘

Available from version 2.7.0.

You can set Smart Script to copy the HTTP document.referrer to either a custom outgoing URL parameter or predefined outgoing URL parameters. If you want to see web referrer values in dashboards or in raw data reports, we suggest using one of the following predefined outgoing URL parameters:

  • af_channel - Parameter is available in dashboards and raw data
  • af_sub1-5 - The parameter is available in raw data under the af_sub1-5 columns and in the original URL column.

If you want to set a custom parameter, Smart Script has to copy the  document.referrer property value and set it as the value of the parameter. In this example, Smart Script copies the document.referrer value to a custom outgoing URL parameter key defined by webReferrer. The selected custom key in the example is this_referrer.

For more information, see Web referrer mapping.

Utilizing Local Storage to Set Parameters for Deep Linking

You can choose to save any data from the website to local storage, and then configure Smart Script to retrieve this data and assign it to an outgoing URL parameter. For example, you can leverage website information to dynamically populate the deep_link_value parameter, enabling the deep linking of users directly to the app's relevant content.

In this example, you can see how the outgoing URL deep_link_value is populated by a value copied from the website's local storage. The copied value in this example is the product ID arriving from the website data.