Referenciador de instalação da Meta

Este documento mostra como usar o referenciador de instalação da Meta no seu app Android para obter metadados de campanhas de anúncios do Facebook, do Instagram e do Audience Network que tenham como objetivo a instalações de apps. Enquanto o referenciador de instalação do Google Play (GPIR, pelas iniciais em inglês) fornece apenas informações sobre instalações por clique em uma única sessão, o referenciador da Meta inclui dados sobre o seguinte:

• Instalações por visualização (VT, pelas iniciais em inglês)
• Instalações por clique (CT, pelas iniciais em inglês)
• Instalações por clique em múltiplas sessões

Existem duas opções para configurar o referenciador de instalação da Meta para suas campanhas de apps Android: integração direta ou integração compatível por meio do Parceiro de Métricas para Aplicativos (MMP, pelas iniciais em inglês).

Opção 1: integração direta

Antes de começar

Antes de dar os primeiros passos, você precisará do seguinte:

• Configurar a chave de descriptografia para o GPIR

Etapa 1. Adicionar os apps da Meta

Em apps do Facebook, Instagram e Facebook Lite, adicione os elementos queries ao seu arquivo AndroidManifest.xml para que você possa obter dados de atribuição de referência desses apps da Meta.

<queries>
  <package android:name="com.facebook.katana" />
</queries>

<queries>
  <package android:name="com.instagram.android" />
</queries>

<queries>
  <package android:name="com.facebook.lite" />
</queries>

Etapa 2. Implementar a API de ContentProvider

Adicione o código ContentProvider para obter dados de atribuição de referência dos apps do Facebook e do Instagram. Você obterá esses dados quando o app for iniciado pela primeira vez.

Cursor c = null;
try {
    String [] projection = { "install_referrer", "is_ct", "actual_timestamp", };
    Uri providerUri = null;
    
    // This IF statement queries the facebook app first.
    // To query from the instagram app first, change the sequence of the IF statement

    if (context.getPackageManager().resolveContentProvider(
           "com.facebook.katana.provider.InstallReferrerProvider", 0) != null) {
       providerUri = Uri.parse(
           "content://com.facebook.katana.provider.InstallReferrerProvider/" + FB_APP_ID);
    } else if (context.getPackageManager().resolveContentProvider(
           "com.instagram.contentprovider.InstallReferrerProvider", 0) != null) {
       providerUri = Uri.parse(
           "content://com.instagram.contentprovider.InstallReferrerProvider/" + FB_APP_ID);
    } else if (context.getPackageManager().resolveContentProvider(
           "com.facebook.lite.provider.InstallReferrerProvider", 0) != null) {
       providerUri = Uri.parse("content://com.facebook.lite.provider.InstallReferrerProvider/" + FB_APP_ID);
    } else {
       return null;
    }

    c = context.getContentResolver().query(providerUri, projection, null, null, null);
    if (c == null || !c.moveToFirst()) {
       return null;
    }

    int installReferrerIndex = c.getColumnIndex("install_referrer");
    int timestampIndex = c.getColumnIndex("actual_timestamp");
    int isCTIndex = c.getColumnIndex("is_ct");
    String installReferrer = c.getString(installReferrerIndex); // serialized and encrypted attribution details

    // TODO: 
    // 1. deserialize installReferrer (convert String to JSON)
    // 2. decrypt attribution details in install_referrer.utm_content.source.data using 
    // key: GPIR decryption key 
    // nonce: retrieve from installReferrer.utm_content.source.nonce
    // data: retrieve from installReferrer.utm_content.source.data
    // decrypt data 

    long actualTimestamp = c.getLong(timestampIndex); // timestamp in seconds for click/impression
     int isCT = c.getInt(isCTIndex); // VT or CT, 0 = VT, 1 = CT
           
} catch (Exception e) {
    return null;
} finally {
    if (c != null) {
        c.close();
    }
}

As etapas para desserializar e descriptografar os dados são semelhantes às encontradas no guia do referenciador de instalação.

Para cada app da Meta, a resposta da estrutura de dados recebida a partir do install_referrer após a desserialização incluirá o seguinte:

• actual_timestamp: o valor é o registro de data e hora em segundos que indica quando o clique ou a impressão ocorreu.
• is_ct: os valores podem ser 1 (representa um clique) ou 0 (representa uma impressão).
• install_referrer: o valor são os dados de atribuição do GPIR criptografados.

Exemplo de resposta JSON

{
  is_ct=1,
  actual_timestamp=123,
  install_referrer={
    utm_campaign = fb4a,
    utm_content: {
      source: {
        data: “7fb9bd76…”, // encrypted attribution information
        nonce: “1234” // nonce from encryption
      },
      a: <app_id>,
      t: <timestamp>
    }
    utm_source : “apps.facebook.com” //OR “apps.instagram.com”
  }
}

Exemplo de dados após a descriptografia: install_referrer.utm_content.source

{ 
  "ad_id":"6110809314024", 
  "adgroup_id":"6110808725024", 
  "adgroup_name":"RTG_Storie_", 
  "campaign_id":"6110808710224", 
  "campaign_name":"Mobex_Conversiones_Storie_Android_21 a 31 de Diciembre_OP39895",
  "campaign_group_id":"6110808710624", 
  "campaign_group_name":"Mobex_Instagram Storie_ Conversiones_ Diciembre OP 43918",
  "account_id":"485495091598353",
  "ad_objective_name":"CONVERSIONS", 
  // data included for Instagram ads
  "is_instagram":true,
  "publisher_platform":"instagram",                
  "platform_position":"instagram_stories"          
}

Etapa 3. Desduplicar os dados

Se os metadados da campanha de anúncios do GPIR estiverem disponíveis, siga o fluxo atual de desduplicação do referenciador.

Desduplicar com o referenciador de instalação

É possível remover duplicações usando os dados retornados em install_referrer porque, seja no referenciador de instalação da Meta ou do GPIR, os valores para uma instalação ou campanha de CT são os mesmos.

Para VT e CT de sessão cruzada, use dados do referenciador de instalação da Meta, já que não há compatibilidade com o GPIR.

Se os metadados da campanha de anúncios do GPIR não forem encontrados, será possível desduplicar os dados com ou sem um Parceiro de Métricas para Aplicativos.

Desduplicar com um MMP

O Parceiro de Métricas para Aplicativos tem acesso a dados de atribuição no nível da linha para instalações que não possuem uma rede de anúncios vencedora, seja por serem atribuídas à Meta ou a instalações orgânicas. É possível verificar se há um referenciador de instalação fornecido por meio do referenciador de instalação da Meta. Se for o caso, você poderá considerar que a instalação é orientada pela Meta e que os dados do referenciador de instalação são os metadados da campanha de anúncios para a instalação.

Desduplicar sem um MMP

O referenciador de instalação da Meta fornece informações do último toque para a instalação, incluindo os metadados da campanha de anúncios, além do registro de data e hora real e do tipo de ação do último toque (impressão ou clique). Você pode comparar o tipo de ação e o registro de data e hora do último toque com os dados de atribuição obtidos a partir de outras redes de anúncios para escolher a rede de anúncios vencedora.

Verificar a configuração

Primeiro, verifique se você está usando uma versão do app que seja compatível com a solução. Estas são as versões mínimas:

• Facebook: v428
• Instagram: v296
• Facebook Lite: v411

Para verificar sua configuração, siga estas etapas:

1. Insira a campanha de teste usando o recurso de prévia no Gerenciador de Anúncios.
2. Encontre o anúncio no Facebook ou no Instagram e clique nele.
3. Adicione pontos de interrupção ou registros ao seu código na Etapa 2.

Seu app receberá uma resposta e deverá descriptografá-la para exibir os dados da campanha.

Opção 2: integração compatível por meio do MMP

Etapa 1: atualizar o SDK do Parceiro de Métricas para Aplicativos

Atualize o SDK do seu MMP para uma versão que tenha o Meta Install Referrer integrado:

• SDK do AppsFlyer: SDK do AppsFlyer v6.14.2+
• SDK do Adjust: SDK do Adjust v4.36.0 ou posterior (Flutter 4.36.0 ou posterior, Unity 4.37.0 ou posterior)
• SDK do Singular ou API do S2S: SDK do Singular v12.3.0 ou posterior (Unity 4.2.0 ou posterior, React Native 3.3.0 ou posterior, Unreal 2.2.0 ou posterior)
• SDK do Kochava: Android SDK do Kochava v5.1.0 ou posterior
• SDK do Airbridge: Android SDK do Airbridge v2.22.3 ou posterior
• SDK do Branch: SDK do Branch v5.10.1 ou posterior

Etapa 2: verificar se o ID do app do Facebook está associado ao SDK do MMP

Veja as instruções nos links abaixo.

• Instruções do Adjust
• Instruções do Singular
• Instruções do Kochava (acesse a seção Meta/Facebook)
• Instruções do Airbridge
• O AppsFlyer gerencia automaticamente esse processo.
• Instruções do Branch

Etapa 3: atualizar o arquivo de manifesto do Android do seu app (dependendo do MMP)

Veja as instruções nos links abaixo.

• Instruções do Kochava (acesse a seção Meta/Facebook)
• Instruções do Branch
• As plataformas AppsFlyer, Adjust, Singular e Airbridge gerenciam automaticamente essa etapa por meio de um SDK próprio.
• Entre em contato com seu MMP se estiver usando SDKs do Flutter/React em vez dos Android SDKs.

Etapa 4: compartilhar sua chave de descriptografia do referenciador de instalação para permitir que o MMP descriptografe os metadados do referenciador

Observação: caso você já tenha feito isso para o referenciador de instalação da Google Play Store, essa etapa não será necessária.

• Você precisará ter acesso de administrador à conta do Gerenciador de Negócios à qual o app pertence.
• Acesse o Meta for Developers.
• Navegue até Meus apps no canto superior direito.
• Selecione o app para acessar sua chave de descriptografia.
• Selecione Configurações do app > Básico.
• Deslize a tela para baixo até a seção Android. Procure Chave para descriptografar o referenciador de instalação no rótulo Google Play.
• Compartilhe sua chave de descriptografia com seu MMP. Veja as instruções nos links abaixo.
  

  • Instruções do AppsFlyer
  • Instruções do Adjust
  • Instruções do Singular
  • Instruções do Kochava
  • Instruções do Airbridge
  • Instruções do Branch