API de Eventos do App

Os eventos do app permitem que você rastreie ações que ocorrem no seu app para celular ou página da web, como instalações e eventos de compra. Ao rastrear esses eventos, é possível mensurar o desempenho de anúncios e criar públicos para o direcionamento de anúncios.

Para ver informações sobre o rastreamento de eventos do app para mensagens com empresas, consulte Como registrar eventos com a API de Eventos para mensagens com empresas na documentação da plataforma do Messenger.

Como funciona

Há três tipos de Eventos do App:

• Eventos registrados automaticamente – o SDK do Facebook registra automaticamente instalações, sessões e compras no app.
• Eventos Padrão – eventos populares que o Facebook criou para você.
• Eventos Personalizados – eventos que você cria que são específicos ao seu app.

O evento do app contém três partes:

1. name – uma string obrigatória que descreve o evento. O nome aparece no registro do evento quando o evento do app é enviado ao Analytics.
2. valueToSum – um valor opcional que o Analytics adiciona a outros valores para soma dos eventos do app com o mesmo nome.
3. parameters – valores opcionais incluídos no seu evento do app.

O número máximo de nomes de eventos distintos é mil. Observação: nenhum tipo de evento novo será registrado quando esse limite for atingido e, se for ultrapassado, o erro 100 Invalid parameter poderá aparecer durante o registro. No entanto, é possível desativar eventos obsoletos. Leia mais sobre os limites de eventos nas perguntas frequentes.

Antes de começar

Você precisará do seguinte:

• A identificação do anunciante, o ID de publicidade de um dispositivo Android ou o Identificador de Anunciante (IDFA, pelas iniciais em inglês) de um dispositivo Apple.
• Um token de acesso do app para que o Facebook autentique. Não armazene seu token de acesso do app cliente.

Instalações do app

Envie uma solicitação POST do seu servidor ao ponto de extremidade /{app-id}/activities com os parâmetros application_tracking_enabled e advertiser_tracking_enabled:

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=MOBILE_APP_INSTALL
   &application_tracking_enabled=0      
   &advertiser_tracking_enabled=0       
   &advertiser_id={advertiser-tracking-id}
   &{app-access-token}"

Se o processo for bem-sucedido, o aplicativo receberá a seguinte resposta:

{
  "success": true
}

Atenção

• Relate somente uma instalação por usuário. Desduplique os IDs nos níveis de usuário e de ID, se possível.

Consulte nosso guia de referência de atividades do app para ver uma lista dos parâmetros disponíveis.

Ativar rastreamento de anúncios

O campo advertiser_tracking_enabled especifica se a pessoa habilitou o rastreamento de anúncios no dispositivo móvel. Configure 0 para desabilitado ou 1 para habilitado. É preciso buscar os dados e retorná-los ao Facebook para determinar se o rastreamento de anúncio pode ser usado para otimização ou conversões. A Meta usará os dados do evento (de parceiros sobre atividades do usuário fora da Meta) de acordo com a própria Política de Dados, inclusive para geração de relatórios de anúncios, detecção de fraudes, bem como construção e melhoria dos nossos produtos (incluindo os produtos de veiculação de anúncios). No entanto, o uso dos dados sobre o usuário será restrito à personalização dos anúncios que são exibidos a ele. Nos dispositivos com versões anteriores ao iOS 6, o parâmetro será 1 por padrão.

Visite a referência do AdSupport da Apple para obter o status de rastreamento de um usuário.

O trecho de código a seguir mostra como buscar o valor da sinalização de rastreamento habilitado.

É possível obter a configuração atual da sinalização de rastreamento habilitado pela propriedade Settings.shared.isAdvertiserTrackingEnabled.

print("isAdvertiserTrackingEnabled: \(Settings.shared.isAdvertiserTrackingEnabled)")

Desabilitar rastreamento de anúncios

Todos os apps podem optar por incluir uma configuração que permite que os usuários desativem o rastreamento de anúncios. O Facebook pede que os parceiros incluam essa opção no SDK e informem sobre a escolha do usuário, assim como sobre o evento de conversão e instalação. O Facebook usa o evento de conversão e instalação para a geração de relatórios de anúncios, mas não autoriza seu uso na otimização de anúncios. A configuração do usuário deve ser a mesma em todas as inicializações do app.

Eventos de conversão

Envie uma solicitação POST ao ponto de extremidade /{app-id}/activities com event definido como CUSTOM_APP_EVENTS e defina advertiser_tracking_enabled para cada evento. O parâmetro advertiser_id ou attribution é necessário.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS" 
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
       "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &{app-access-token}" 

Se o processo for bem-sucedido, o app receberá a seguinte resposta:

{
  "success": true
}

Atribuição

O ponto de extremidade attribution retorna instalações e conversões com base nos cliques em um anúncio no período de 28 dias. O Gerenciador de Anúncios usa uma visualização de 1 dia com um modelo de atribuição de cliques de 28 dias. Além disso, os insights são apresentados com base na impressão ou no tempo de clique, e não no tempo de instalação ou conversão. Isso é importante ao comparar seus relatórios aos do Gerenciador de Anúncios do Facebook. Além das obtenções do evento do app de clique no anúncio, as seguintes situações também são importantes:

• Obtenções da atribuição de visualização: a configuração de consider_views=TRUE retornará dados de atribuição para instalações ocorridas dentro de 1 dia de uma impressão de anúncio, desde que a conta da Central de Contas não tenha clicado no anúncio em 28 dias. A resposta retornada será is_view_through=TRUE, e view_time substituirá click_time. Todas as outras atribuições são as mesmas dos dados de atribuição de clique no anúncio.

• Obtenções entre campanhas: os anunciantes podem rastrear o desempenho de todos os anúncios que levaram a um evento do app. O Facebook enviará obtenções para eventos de campanhas de anúncios se o objetivo da campanha não estiver definido como engajamento ou instalação do app para celular. Esses dados somente aparecerão se o anunciante tiver adicionado o app ao campo "Rastreamento de eventos de app para celular" no anúncio.

• Caso do usuário: se o cliente quiser rastrear as instalações geradas por um anúncio de publicação da Página ou um anúncio de cliques no site que direciona os usuários a um site para dispositivos móveis, será possível fazer isso no Gerenciador de Anúncios, e o Facebook obterá as instalações de app relevantes.

• Obtenções entre dispositivos: os anunciantes que têm apps em diversas plataformas podem ver os dados de instalações impulsionadas por anúncios nessas plataformas.

• Caso de uso: um usuário clica em um anúncio de app no iPhone e instala esse app no iPad. Dessa forma, é possível atribuir a instalação do app para iPad ao anúncio do iPhone, independentemente do direcionamento do anúncio.

Correspondência avançada

A correspondência avançada permite que você envie dados de clientes para o Facebook, onde usamos esses dados para determinar com mais precisão quais contas da Central de Contas agiram em resposta ao seu anúncio. Com esses dados, o Facebook pode fazer a correspondência de eventos de conversão com seus clientes para otimizar os anúncios e criar públicos de remarketing maiores.

Envie uma solicitação POST ao ponto de extremidade /{app-id}/activities com o ud definido como um parâmetro que ajudará a rastrear o cliente, como email ou número de telefone. Todos os dados de clientes precisam estar em hash para que não sejam ignorados pelo Facebook. Lembre-se de definir advertiser_tracking_enabled para cada evento.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
      "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &ud[em]={sha256-hashed-email}
   &{app-access-token}"

Se o processo for bem-sucedido, o app receberá a seguinte resposta:

{
  "success": true
}

É necessário aplicar hash SHA256 a todos os dados de usuário antes que eles sejam enviados ao Facebook. Os dados sem hash serão ignorados pelo Facebook.

Desduplicação

Para eventos do app, aplicamos a mesma funcionalidade de desduplicação usada com eventos da web. A lógica usa desduplicação baseada no campo event_id e no event_name. O parâmetro event_id é um identificador que distingue eventos semelhantes. IDs de evento imprecisos podem fazer com que a conversão seja desduplicada incorretamente, afetando os relatórios de conversão e o desempenho da campanha.

Informações estendidas sobre dispositivos

Envie informações de dispositivos, como largura e altura de tela, na chamada de evento do app usando /{app-id}/activities?extinfo. Os valores são separados por vírgula e precisam estar na ordem exibida no guia de referência /application/activites. Ao usar extinfo, todos os valores são obrigatórios.

• version precisa ser a2 para Android.
• version precisa ser i2 para iOS

Referência

• Application Activities
• Android Developer Documentation - Display Metrics
• Android Developer Documentation - External Storage
• Apple Developer Documentation - Display Metrics
• Apple Developer Documentation - External Storage
• Apple Developer Documentation - Screen Size

Obter cookies para dispositivos móveis

Recomendamos que você associe os eventos do app a um advertiser_id. No entanto, para dispositivos Android e dispositivos iOS anteriores ao iOS 6, também é possível usar o parâmetro attribution definido como o cookie para dispositivos móveis do dispositivo em questão.

Nota: cookies móveis não são derivados de outros atributos do dispositivo ou usuários. Esses cookies não são persistentes e foram projetados para atualizações frequentes. Não use cookies para dispositivos móveis para redirecionar anúncios.

Android

O cookie é uma string aleatória de 22 caracteres alfanuméricos.

Para obter o ID de atribuição do Facebook, use ContentProvider:

public static final Uri ATTRIBUTION_ID_CONTENT_URI = Uri.parse("content://com.facebook.katana.provider.AttributionIdProvider");

public static final String ATTRIBUTION_ID_COLUMN_NAME = "aid";

public static String getAttributionId(ContentResolver contentResolver) {
        String [] projection = {ATTRIBUTION_ID_COLUMN_NAME};
        Cursor c = contentResolver.query(ATTRIBUTION_ID_CONTENT_URI, projection, null, null, null);
        if (c == null || !c.moveToFirst()) {
            return null;
        }
        String attributionId = c.getString(c.getColumnIndex(ATTRIBUTION_ID_COLUMN_NAME));
        c.close();
        return attributionId;
    }

Você também pode obter o ID de publicidade do seu aplicativo Android.

iOS

O cookie para dispositivos móveis é criado pelos apps do Facebook para iOS com CFUUIDCreateString e é uma representação de string do identificador único universal (UUID, pelas iniciais em inglês) de 128 bits.

Obtenha a identificação do cookie e o IDFA. Depois, envie-os ao Facebook como um identificador:

ASIdentifierManager *manager = [ASIdentifierManager sharedManager];
NSString *advertiserID = [[manager advertisingIdentifier] UUIDString];

if (advertiserID) {
  // do stuff
}

Cabeçalho HTTP X-Forwarded-For

Se as solicitações POST forem feitas de um lugar central, como um servidor/proxy, ou seja, por meio de uma chamada de servidor para servidor, o cabeçalho HTTP X-Forwarded-For será necessário para garantir a precisão da localização e das informações do dispositivo. Envie o endereço IP do dispositivo, nos formatos IPv4 ou IPv6, por meio do parâmetro de cabeçalho HTTP encaminhado, em todas as solicitações enviadas de eventos do app. Com isso, será possível sincronizar o advertiser_id com o endereço IP correto que poderá ser usado na nossa plataforma.

Exemplo de IPv6

curl ...
  -H "X-Forwarded-For: fd45:f238:3b40:23b1:ffff:ffff:ffff:abcd" \
  https://graph.facebook.com/<APP_ID>/activities/

Exemplo de IPv4

curl ...
  -H "X-Forwarded-For: 192.168.0.99" \
  https://graph.facebook.com/<APP_ID>/activities

Testes

1. Acesse o Gerenciador de Eventos.
2. Clique no ícone Fontes de dados no lado esquerdo da página.
3. Selecione o nome e a identificação dos seus dados.
4. Clique em Eventos de teste e selecione App como canal.
5. Envie uma solicitação AE-API com a ferramenta Explorador da Graph API.
6. Suas interações serão exibidas na aba Eventos de teste.

Discrepâncias

Caso um cliente compare os relatórios de Parceiros de Métricas para Aplicativos aos relatórios do Facebook e veja discrepâncias, verifique os itens abaixo:

Caso o Facebook relate menos instalações que o MMP:

• O SDK do Facebook está integrado corretamente?
• O cliente está usando o ID do app errado?

Caso o Facebook relate mais instalações que o MMP:

• As janelas de atribuição são as mesmas? Normalmente, o Facebook tem uma janela de atribuição maior que a maioria dos Parceiros de Métricas para Aplicativos.
• O SDK do MMP está integrado corretamente?
• O cliente está usando o ID do app errado?
• A discrepância corresponde somente ao iOS 7? O MMP está recebendo o Identificador de Anunciante da Apple (IDFA) do dispositivo e passando-o corretamente para o Facebook?

Referência

Extinfo de atividades de aplicativo

Consulte o guia de referência /application/activites para saber mais sobre as informações estendidas de app.

Parâmetros de dados de usuário

Nomes de evento padrão

Parâmetros de evento padrão

Veja também

• Eventos do Aplicativo
• Guia de boas práticas para eventos do app
• Como lidar com erros
• Conformidade com RGPD
• Gerenciador de Anúncios do Facebook
• Painel de Apps do Facebook