Guia de integração do PBA Web SDK

<script>
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" } };
  window.AF.plugins = {};

  // Inject SDK
  var o = document.createElement("script"),
      p = document.getElementsByTagName("script")[0];
  o.async = 1;
  o.src = "https://websdk.appsflyersdk.com?" + "st=pba&af_id=WEB_DEV_KEY";
  p.parentNode.insertBefore(o, p);
</script>

<script>
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" }, banners: { key: "YOUR_BANNER_KEY" } };
  window.AF.plugins = {};

  // Inject SDK
  var o = document.createElement("script"),
      p = document.getElementsByTagName("script")[0];
  o.async = 1;
  o.src = "https://websdk.appsflyersdk.com?" + "st=pba,banners&af_id=WEB_DEV_KEY";
  p.parentNode.insertBefore(o, p);
  AF('banners', 'showBanner');
</script>

<script>
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" } };
  window.AF.plugins = {};

  // Manifest loader config
  window.AF_LOADER_CONFIG = {
    baseUrl: "https://websdk.appsflyersdk.com",
    plugins: ["pba"]
  };

  // Inject manifest loader
  var loaderScript = document.createElement("script");
  loaderScript.src = "https://websdk.appsflyersdk.com/manifestLoader.v1.js";
  loaderScript.integrity = "sha384-Uncl2YwvjFpFz0PwEfl3bL/0JsOQcDFEpwXHzcN0MBavn9vvFEx5pZxADTq8h+CV";
  loaderScript.crossOrigin = "anonymous";
  loaderScript.async = true;
  document.head.appendChild(loaderScript);
</script>

<script>
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" }, banners: { key: "YOUR_BANNER_KEY" } };
  window.AF.plugins = {};

  // Manifest loader config
  window.AF_LOADER_CONFIG = {
    baseUrl: "https://websdk.appsflyersdk.com",
    plugins: ["banners", "pba"]
  };

  // Inject manifest loader
  var loaderScript = document.createElement("script");
  loaderScript.src = "https://websdk.appsflyersdk.com/manifestLoader.v1.js";
  loaderScript.integrity = "sha384-Uncl2YwvjFpFz0PwEfl3bL/0JsOQcDFEpwXHzcN0MBavn9vvFEx5pZxADTq8h+CV";
  loaderScript.crossOrigin = "anonymous";
  loaderScript.async = true;
  document.head.appendChild(loaderScript);
</script>

Considerações e ações necessárias

Antes de começar:

• Verifique com o profissional de marketing se o pacote de marca foi criado. 
• Para obter orientações adicionais, consulte o guia de integração de PBA.
• Considere: se você já possui o Web SDK específico para Smart Banners, remova-o e substitua-o pelo Web SDK para Smart Banners e PBA. Não adicione somente o Web SDK para PBA. 

Faça o seguinte:

• Obter a chave de desenvolvimento web do web SDK. Atenção! Esta não é a mesma chave usada pelos aplicativos mobile.
  • Para obter a chave do desenvolvedor web: 
    1. Na AppsFlyer, no menu superior, selecione a aba Meus Aplicativos .
    2. Clique em Visualizar pacotes de marca.
    3. Copie a chave de desenvolvimento web necessária . (WEB_DEV_KEY)
• Se você implementar Smart Banners, obtenha a chave Smart Banner. 
  • Para obter a chave Smart Banner:
    1. Na AppsFlyer, no menu lateral, vá para Engajamento> Web-to-app > Smart Banners.
    2. Copie a chave do Smart Banner necessária. 
• Permissões para adicionar scripts a etiquetas de cabeçalho no site.
• Se você usar o Google Tag Manager, ele deve estar integrado no site.

Proceda à integração do SDK web usando uma das seguintes opções. 

Depois de instalado, verifique se o Web SDK da AppsFlyer é chamado pelo navegador do visitante e se as mensagens estão sendo enviadas. Isto é feito examinando a conexão de rede de mensagem relatada no navegador.

Para garantir que o SDK é carregado e está funcionando:

1. Acesse o site.

2. Abra as ferramentas de desenvolvimento do navegador.

   

3. Vá para a aba (A) Network.  
4. Atualize a página.
5. Filtre por (B) wa.appflyer.
6. Selecione a mensagem events (C).
7. Na aba de cabeçalhos, (D) certifique-se de:
   • O URL de solicitação é wa.appsflyer.com/events.
   • parâmetro de consulta site_id= WEB_DEV_KEY.
   • (E) o código de status é 200.
8. Verifique se o valor de site_id é igual ao valor de WEB_DEV_KEY nas configurações do pacote de marcas:
   1. Na AppsFlyer, no menu lateral, selecione Configurações > Pacotes de marca.
   2. Clique na chave Web dev, o que permite copiar a chave.
   3. Cole a chave em qualquer local (nova aba do navegador, bloco de notas) para exibir a chave.
   4. Verifique se o site_id e WEB_DEV_KEY correspondem. 
9. Certifique-se de que o SDK é carregado apenas uma vez. O carregamento múltiplo de SDK pode fazer com que o SDK deixe de funcionar.

O Web SDK envia dados de eventos do visitante para a AppsFlyer. É possível controlar, parar ou iniciar o envio de eventos, conforme descrito nesta secção. 

Considere:

• Definição do estado inicial do SDK: Determina se o SDK envia eventos ao carregar inicialmente a página web ou se o SDK tem de esperar até que seja dado um comando explícito para começar a enviar eventos. A definição está contida no trecho da web.
• Controle explícito: Use para parar ou iniciar o envio de eventos. Por exemplo, se você implementar banners de opt-in/opt-out de dados (também conhecidos como banners de consentimento de cookies), integre os comandos explícitos nos controlos do banner para iniciar e parar o envio de eventos. O controle explícito tem prioridade sobre a definição do estado inicial do SDK e usa cookies primários persistentes com as seguintes características:
  • Definido no domínio do site.
  • Expira após um período definido pelo Web SDK ou conforme determinado pelo navegador. Após a expiração do cookie, o Web SDK reverte para a configuração do estado inicial.
  • O cookie do Web SDK não causa interferência e está sempre sujeito às configurações de cookies específicas do navegador.
     

Definição do estado inicial do SDK

Controle explícito:

Se o seu site exige protocolos rigorosos de segurança e de privacidade de dados, use os seguintes mecanismos para configurar a maneira como o Web SDK interage com seu ambiente e seus dados.

Política de Segurança de Conteúdo (CSP)

Se o seu site exige que o JavaScript seja protegido por uma CSP, o Web SDK é compatível com duas abordagens diferentes, a depender da configuração da sua CSP.

• CSP usando self: Adicione https://websdk.appsflyersdk.com à sua lista de permissões script-src. Isso funciona tanto para o Web SDK padrão quanto para a Verificação avançada do SDK.
• CSP usando nonce: Se sua política usar script-src 'nonce-...', você pode usar a variante nonce-extended da Verificação avançada do SDK. Esse mecanismo encaminha o nonce para todas as três tags de script exigidas pelo processo de verificação. Substitua {{CSP_NONCE}} pelo valor nonce gerado pelo servidor.

A tabela abaixo mostra quais políticas CSP são compatíveis com a variante nonce-extended.

Verificação avançada de SDK com snippets de nonce CSP

<script nonce="{{CSP_NONCE}}">
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" } };
  window.AF.plugins = {};

  // Manifest loader config — nonce forwarded to the injected SDK <script> tag
  window.AF_LOADER_CONFIG = {
    baseUrl: "https://websdk.appsflyersdk.com",
    plugins: ["pba"],
    nonce: "{{CSP_NONCE}}"
  };

  // Inject manifest loader
  var loaderScript = document.createElement("script");
  loaderScript.src = "https://websdk.appsflyersdk.com/manifestLoader.v1.js";
  loaderScript.integrity = "sha384-Uncl2YwvjFpFz0PwEfl3bL/0JsOQcDFEpwXHzcN0MBavn9vvFEx5pZxADTq8h+CV";
  loaderScript.crossOrigin = "anonymous";
  loaderScript.nonce = "{{CSP_NONCE}}";
  loaderScript.async = true;
  document.head.appendChild(loaderScript);
</script>

<script nonce="{{CSP_NONCE}}">
  // Queue — buffers AF() calls until the SDK is ready
  window.AppsFlyerSdkObject = "AF";
  window.AF = window.AF || function() {
    (window.AF.q = window.AF.q || []).push([Date.now()].concat(Array.prototype.slice.call(arguments)));
  };
  window.AF.id = window.AF.id || { pba: { webAppId: "WEB_DEV_KEY" }, banners: { key: "YOUR_BANNER_KEY" } };
  window.AF.plugins = {};

  // Manifest loader config — nonce forwarded to the injected SDK <script> tag
  window.AF_LOADER_CONFIG = {
    baseUrl: "https://websdk.appsflyersdk.com",
    plugins: ["banners", "pba"],
    nonce: "{{CSP_NONCE}}"
  };

  // Inject manifest loader
  var loaderScript = document.createElement("script");
  loaderScript.src = "https://websdk.appsflyersdk.com/manifestLoader.v1.js";
  loaderScript.integrity = "sha384-Uncl2YwvjFpFz0PwEfl3bL/0JsOQcDFEpwXHzcN0MBavn9vvFEx5pZxADTq8h+CV";
  loaderScript.crossOrigin = "anonymous";
  loaderScript.nonce = "{{CSP_NONCE}}";
  loaderScript.async = true;
  document.head.appendChild(loaderScript);
</script>

Se seus parâmetros de consulta contiverem dados que você não deseja que a AppsFlyer registre, você poderá instruir a plataforma AppsFlyer a descartar alguns ou todos os parâmetros de consulta. Ao fazer isso, eles não ficam disponíveis em dados brutos ou relatórios.  

Você pode implementar os métodos descritos em relação a URLs, referenciadores e header_referer.

Consultar opções de descarte

• Os eventos do usuário são registrados pelo SDK, que envia o evento para a plataforma AppsFlyer.
• Usando a lista de eventos de conversão, definida pelo profissional de marketing, a AppsFlyer faz uma divisão entre eventos padrão e de conversão.
• Os dados dos eventos de conversão estão disponíveis nos painéis de controle de PBA.
• Os dados de conversão e eventos padrão estão disponíveis nos relatórios de dados brutos.

Eventos de conversão

• Os eventos de conversão fornecem insights sobre os seus esforços comerciais e de marketing. Os eventos de conversão incluem compras, downloads, inscrições e assinaturas.
• O PBA atribui os eventos de conversão à fonte de media que levou o usuário a visitar o site.
• Ao identificar o canal de mídia atribuído, é possível medir e diferenciar a qualidade dos usuários trazida por diferentes canais de mídia.
• Os eventos de conversão são usado para registrar as receitas e calcular o ROI.
• Use-os para comparar o orçamento de anúncios para canais de mídia específicas com as receitas geradas pelos usuários que provêm desses canais de mídia.

Eventos padrão

• Os eventos padrão são usados para validar a jornada do usuário e os funis que geram conversões.
• Use-os para medir a atividade do usuário e destacar os canais de mídia que atraem usuários engajados.
• Registre a atividade do usuário para marcar os usuários para campanhas de reengajamento.

Eventos de registro

Acione o Web SDK para registrar eventos quando determinadas condições são cumpridas, por exemplo, quando uma página inicial é carregada ou quando os usuários interagem com elementos do site. Ver exemplos de registro de eventos.

• Os usuários da web são identificados na AppsFlyer usando o CUID único que você atribui a eles. Normalmente, o CUID é gerenciado pelos seus servidores backend. 
• Use o mesmo valor CUID que usa no ambiente móvel. Desta forma, é possível ter uma visão holística da atividade do usuário em multi plataformas. A função no SDK mobile é setCustomerUserId (iOS, Android, Unity).
• Para definir o CUID no Web SDK:
  • Defina o CUID no primeiro momento em que tiver acesso a ele. Na maioria das vezes, isto significa que é necessário esperar que o usuário se identifique através do login ou da inscrição.
  • Acione a chamada JavaScript para setCustomerUserId() como mostrado no exemplo a seguir.
    Atenção! Envie o CUID como uma string mesmo que seja um número. Não se esqueça das aspas.
• Se você implementar a Web S2S, talvez precise notificar o PBA quando associar um CUID a um ID de visitante da web no seu backend.
• Os CUID não devem conter informações pessoais diretamente identificáveis , como um número de telefone ou um endereço de email.

Exemplo: definir o CUID

// Associate all current user web events to distinct ID 663274 
AF('pba', 'setCustomerUserId' , '663274')

Exemplo de evento

// purchase event of shoes with associated revenue
AF('pba', 'event', {eventType: 'EVENT', eventName: 'purchase', eventRevenue: 12, eventValue: {"key1": 123, "key2": "name"}});

Os eventos que você envia dependem da natureza do seu aplicativo web. Por exemplo, um aplicativo de loja online requer um conjunto de eventos diferente do de um canal de notícias. Veja os cenários que a seguir para ter uma noção dos eventos que você deve enviar e quando.

Loja online

Suponha que está gerenciando uma loja online. Alguns eventos padrão que talvez você queira registrar são: 

• Pesquisa: evento padrão
• Adicionar ao carrinho: evento padrão
• Remover do carrinho: evento padrão
• Compra: evento de conversão

Canal de notícias

Suponhamos que está gerenciando um canal de notícias. Alguns eventos que talvez você queira registrar são:

• Inscrição: evento de conversão
• Assinatura de compras: evento de conversão

Esta parte destina-se a desenvolvedores web.

Teste a integração do Web SDK do PBA: visualize eventos de teste em tempo real.

Para garantir que os eventos sejam enviados para a AppsFlyer:

1. Abra o site.
2. Abra as ferramentas de desenvolvimento do navegador.
   • Como abrir as ferramentas de desenvolvimento no Chrome
   • Como abrir as ferramentas de desenvolvimento no Safari
3. Mude para a aba Network.
4. Acione o evento.

5. Filtrar por mensagem.

   

6. Procure uma solicitação de network que comece com o destino wa.appsflyer.com (veja a imagem abaixo).
7. Certifique-se de que:
   1. O código de status é 200.
   2. A carga útil do pedido está alinhada com os parâmetros do evento.

O código fornecido serve apenas para fins ilustrativos. Não use este código tal como está. 

• Pressupostos: O Web SDK já está carregado pela página no momento em que o evento é enviado.
• Os cenários de exemplo contêm o código para registrar eventos quando: 
  • uma página inicial é carregada.
  • os usuários interagem com o site.

<html>
    <head>
        <!-- Assume that the server returns a response with details about the newly subscribed user -->
        <!-- Alternatively, you can extract data from localStorage or cookies,
            in case data was set in either of them during the subscription process
        -->
        <script>window.onload = function(){
            AF('pba', 'event', {eventType: 'EVENT', eventValue: {'category': 'holiday_promotion', eventValue: {'label' : 'newspaper'}, eventName: 'subscription',}); } </script> </head> <body> <h1>Thank You for Subscribing to Our Newsletter</h1> </body> </html>

<html>
<head>
    <!-- Assume that data about products in the shopping cart
    is stored in localStorage -->
    <script>
        window.onload = function () {
            document.getElementById('checkout').addEventListener('click', function () {
                AF('pba', 'event', {eventType: 'EVENT', eventValue: {'category' : 'holiday_promotion'}, eventName: 'checkout'});
            });
        }
    </script>
</head>
<body>
    <h1>Shopping Cart</h1>
    <h2>Shirt</h2>
    <p>
        <ul>
            <li>Color: Blue</li>
            <li>Quantity: 2</li>
            <li>Price: $20</li>
        </ul>
    </p>
    <h2>Pants</h2>
    <p>
        <ul>
            <li>Color: Black</li>
            <li>Quantity: 3</li>
            <li>Price: $15</li>
        </ul>
    </p>
    <button id='checkout'>Checkout</button>
</body>
</html>

• Certifique-se de que a tag das funções do Web SDK seja carregada antes de o evento ser acionado.
• Não envie caracteres especiais nos valores dos eventos, como símbolos de moeda no valor da receita.
• As strings de valor devem ter menos de 50 caracteres.

O código fornecido nestes exemplos é apenas para referência. Não use este código tal como está. Se você não tiver certeza de como usar este código, consulte o seu desenvolvedor Web. 

Pressuposto: O Web SDK é carregado pela página antes de o evento ser enviado; não carregue o SDK novamente.

Cenário do usuário:

• Um usuário inscreve-se no seu site.
• O código do site recolhe os dados do usuário e envia-os para o seu servidor.
• O servidor gera um CUID único para o usuário.
• Na página de agradecimento após o registro, você consulta o servidor para obter o novo CUID.
• Usando a resposta do servidor, você define o CUID da AppsFlyer usando o método setCustomerUserId() do Web SDK.

<html>
<head>
    <!-- The Web SDK script loads first -->
    <script>
!function(t,e,n,s,a,c,i,o,p){t.AppsFlyerSdkObject=a,t.AF=t.AF||function(){
(t.AF.q=t.AF.q||[]).push([Date.now()].concat(Array.prototype.slice.call(arguments)))},
t.AF.id=t.AF.id||i,t.AF.plugins={},o=e.createElement(n),p=e.getElementsByTagName(n)[0],o.async=1,
o.src="https://websdk.appsflyersdk.com?"+(c.length>0?"st="+c.split(",").sort().join(",")+"&":"")+(i.length>0?"af_id="+i:""),
p.parentNode.insertBefore(o,p)}(window,document,"script",0,"AF","pba",{pba: {webAppId: "WEB_DEV_KEY"}})
    </script>
    <script>
        };
    // This function stores the user email sent to the server after the user reaches the thank you page
    // The response from the server is a unique CUID that should be set using the web SDK setCustomerUserId method
        function storeUserEmail (){
            var userEmail = document.getElementById('email').value;
            localStorage.setItem('user_email', userEmail);
        }
    </script>
</head>
<body>
    <h1>Sign Up</h1>
    <form onsubmit="storeUserEmail()" action="/signup" method="post">
        <div><label>Name</label>
            <input type="text" name="name" id="name"></div>
        <br />
        <div> <label>Email</label>
            <input type="email" name="email" id="email"></div>
        <br />
        <input type="submit" id="submit">
    </form>
</body>
</html>

<html>
<head>
    <script>
!function(t,e,n,s,a,c,i,o,p){t.AppsFlyerSdkObject=a,t.AF=t.AF||function(){
(t.AF.q=t.AF.q||[]).push([Date.now()].concat(Array.prototype.slice.call(arguments)))},
t.AF.id=t.AF.id||i,t.AF.plugins={},o=e.createElement(n),p=e.getElementsByTagName(n)[0],o.async=1,
o.src="https://websdk.appsflyersdk.com?"+(c.length>0?"st="+c.split(",").sort().join(",")+"&":"")+(i.length>0?"af_id="+i:""),
p.parentNode.insertBefore(o,p)}(window,document,"script",0,"AF","pba",{pba: {webAppId: "WEB_DEV_KEY"}})
    </script>
    <script>
        // Using the fetch API to send the user email to the server
        // and get the unique user id in return	
        window.onload = function () {
            var userEmail = localStorage.getItem('user_email');
            fetch('users/' + userEmail).then(function (res) {
                   res.text().then(function (id) {
                    console.log(id);
                    AF('pba', 'setCustomerUserId', id);
                });
            });
        }  </script> 
     </head> 
     <body> 
        <h1>Thank You for Signing Up!</h1> 
     </body> 
</html>

A função setCustomerUserId pode ser enviada em qualquer fase do fluxo do utilizador, por exemplo, após o início de sessão e a inscrição do usuário. A AppsFlyer usa o CUID mais recente enviado para atualizar o usuário atualmente observado para pontos de contacto e eventos passados ou futuros.

Use o mesmo valor de CUID que você usa na função setCustomerUserId no app mobile (consulte setCustomerUserId mobile para: iOS, Android e Unity)

Os cookies listados na tabela que a seguir são definidos ou usados pelo Web SDK no seu site. 

Na tabela são utilizadas as seguintes abreviaturas:

• AMP: Páginas AMP (accelerated mobile pages) 
• CDN: Rede de distribuição de conteúdo
• 3PC: Cookies de terceiros

• Um aviso de descontinuação informa sobre a nossa intenção de parar a compatibilidade com um recurso ou método. A caraterística ou método continua a funcionar até à sua data de expiração.
• Encare os avisos de descontinuação como uma oportunidade para fazer alterações no seu código.