Audiences - importar segmentos de audiências de sistemas internos

Premium
Para:
Profissionais de marketing Desenvolvedores
Última atualização:

Resumo: você pode importar segmentos de audiências predefinidas de seus sistemas internos (como BI e CRM) para o Audiences, e usá-los como seu ponto central para conectar e manter todos esses segmentos com seus parceiros publicitários.

Por que importar audiências?

Em certas situações, você pode ter segmentos de audiências predefinidos em seus sistemas internos. Ao importar essas audiências (como listas de device e/ou user IDs) para a AppsFlyer, você pode usar o Audiences como o ponto central para conectar e gerenciar todos os seus segmentos com seus parceiros publicitários. Além disso, você pode aproveitar os recursos do Audiences, tais como ID matching/enriquecimento de dados e métricas de campanha conectadas.

Considere os exemplos seguintes:

 Exemplos

Remarketing promocional
Você quer enviar ofertas promocionais para os usuários no mês dos seus aniversários.

Veja como fazer isso com o Audiences:

  1. Use o seu CRM interno para criar uma lista de usuários com as suas datas de aniversário.
  2. Divida a lista de acordo com o mês de aniversário e exporte-a como listas individuais de advertising IDs.
  3. Importe as listas para a AppsFlyer como audiências e conecte-os aos parceiros para as campanhas promocionais que você pretende realizar.
  4. Configure campanhas com os parceiros adequados para direcionar corretamente as audiências.

Aquisição de novos usuários
Vamos supor que o seu studio de desenvolvimento de aplicativos adquiriu um novo studio. Esse novo studio tem os device IDs de usuários que instalaram os apps desse studio no passado, e você quer segmentar esses usuários para que eles instalem seus apps atuais.

Veja como fazer isso com o Audiences:

  1. Obtenha a lista de device IDs do studio adquirido e importe-a para a AppsFlyer como uma audiência.
  2. Conecte a audiência importada aos parceiros com os quais você pretende realizar campanhas.
  3. Configure campanhas com os parceiros relevantes para alcançar esses usuários da melhor forma.

Audiences import V2.0

Veja os conceitos e procedimentos relacionados com a nova funcionalidade de importação do Audiences V2.0, que inclui opções para importação por CSV e API. 

Tipos de audiências importadas

Quando importar uma audiência, você deverá definir o seu tipo, determinando como a AppsFlyer processa e envia a audiência para os parceiros. Isso é feito na primeira importação de uma audiência e não pode ser alterado posteriormente.
 

Uma audiência importada padrão:

  • Passa por ID matching e enriquecimento de dados—um processo em que o Audiences combina os identificadores importados com os existentes na base de dados (para o mesmo usuário no mesmo app), enriquecendo os dados enviados aos parceiros.
  • É enviado para parceiros conforme a política de identificadores de usuário da sua conta.
  • Deve ser importado usando a funcionalidade de importação V2.0 descrita neste artigo.

Uma audiência importada "como está":

  • Não passa por ID matching e enriquecimento de dados.
  • É enviado para os parceiros sem seguir a política de identificadores de usuário da sua conta (ou seja, todos os identificadores importados são enviados para os parceiros).
  • Pode ser importado usando a funcionalidade de importação V2.0 (descrita neste artigo).

Importante!

  • Todas as audiências existentes a partir de 23 de novembro de 2021, são designadas como audiências "como estão" e não podem ser alteradas para audiências padrão. Pode continuar a atualizar essas audiências conforme necessário, usando a funcionalidade de importação V2.0 (descrita neste artigo).
  • Você pode ter até 500 audiências importadas ativas de uma só vez.
  • Apenas um administrador pode designar uma nova audiência importada para como "como está".
  • Ao importar uma audiência que possui um CUID como identificador, a associação de CUID deve ter sido recebida pela AppsFlyer na instalação (e não apenas em eventos pós-instalação), garantindo a associação completa com os dispositivos relevantes e um enriquecimento eficaz com os identificadores de dispositivos (como GAID, IDFA, etc.). Saiba mais

Procedimentos para importação de audiências

Importe uma audiência fazendo o upload de um arquivo CSV ou usando a Import Audience API.

Importar um arquivo CSV

Prepare um arquivo CSV com as seguintes especificações:

Formato

  • Uma coluna para cada identificador de usuário a ser enviado
  • Uma linha de header com o nome do identificador em cada coluna (tudo em letras minúsculas)
  • Sem linhas em branco
  • Número máximo de linhas: 1 milhão
  • Se preparar o arquivo no Excel, salve-o como CSV (delimitado por vírgula) (*.csv), como mostra a imagem a seguir: CSV.jpg

Colunas e identificadores

  • Os dados são processados usando a linha de header para identificar os dados em cada coluna, portanto:
    • Não é necessário que as colunas apareçam em uma ordem específica.
    • Não é necessário incluir colunas para identificadores que não serão enviados.
    • Você pode importar quantos identificadores desejar em um único arquivo CSV, desde que cada linha inclua os identificadores obrigatórios, conforme detalhado abaixo.
  • Identificadores disponíveis:
    • app_id
    • idfv
    • idfa
    • gaid
    • oaid
    • imei
    • cuid
    • emails
    • phone
    • phone_e164
    • braze_id
    • amplitude_id

      Atenção: Identificadores adicionais, como emails e phone, devem estar no formato sha256 criptografado ou deixados em branco.
  • Identificadores obrigatórios:
    • Para audiências Android: app_id + um dos seguintes: gaid OU oaid OU imei OU cuid OU braze_id OU amplitude_id
    • Para audiências iOS: app_id + um dos seguintes: idfv OU cuidOU braze_id OU amplitude_id
  • Em conformidade com o Digital Markets Act (DMA) da Google: a partir de 6 de março de 2024, ao importar uma audiência "como está", será necessário adicionar duas colunas adicionais de consentimento da AppsFlyer. São elas:
Colunas de consentimento da AppsFlyer  Campo do Google  Valores Explicação do campo
ad_personalization_enabled ad_personalization true/false O usuário permitiu que o Google use seus dados para receber anúncios personalizados?
ad_user_data_enabled ad_user_data true/false O usuário permitiu o compartilhamento de seus dados com o Google?  

Se os campos de consentimento não forem preenchidos com valores, serão enviados para a Google como "Não especificado" e provavelmente não serão incluídos na audiência do lado do Google. Preencher esses campos assegura a máxima inclusão de usuários do Espaço Econômico Europeu (EEE) nas suas audiências do Google.

Exemplos de arquivos CSV:

new-import-android-example.csv
new-import-ios-example.csv

Para criar e importar uma nova audiência usando um arquivo CSV:

  1. No dashboard esquerdo da AppsFlyer, vá até Engajar > Audiences.
  2. Clique em Nova audiência.
  3. Escolha Importar audiência.
    A janela Importar audiência será aberta.
  4. Insira um Nome de audiência exclusivo.
  5. Selecione a plataforma: Android ou iOS.
  6. Indique se essa audiência é padrão ou como está .
  7. Para uma audiência padrão, mantenha a caixa desmarcada.
  8. Para uma audiência no estado atual, marque a caixa. (Atenção: disponível apenas para administradores.)
  9. Clique em Salvar audiência e prossiga.
    A aba Importar é mostrada.
  10. Em Importar usando CSV, mantenha a opção padrão de Adicionar novos dispositivos/usuários (já que se trata de uma nova audiência).
  11. Escolha o arquivo CSV para upload.
    Aguarde a mensagem de confirmação Upload feito com sucesso.
  12. Clique em Próximo.
    A aba Conectar é exibida.
  13. (Opcional) Siga as instruções para conectar uma audiência a parceiros.
  14. Clique em Concluir.

A sua audiência já aparece no dashboard do Audiences, e já foi importada e conectada aos seus parceiros. É importante observar, no entanto, que a lista de audiências importada ainda não está disponível para upload para os parceiros, pois as audiências importadas são processadas com uma atualização de dados diária.

Para atualizar uma audiência existente usando um arquivo CSV:

  1. No dashboard esquerdo da AppsFlyer, vá até Engajar > Audiences.
  2. Clique no nome da audiência que você deseja atualizar.
    A tela Editar audiência aparece, com a aba Definir.
  3. Se você deseja alterar o nome da audiência, você pode fazer isso agora. Caso contrário, selecione a aba Importar para enviar o novo arquivo CSV.
  4. EmImportar usando CSV, escolha a o que fazer com a lista enviada:
  5. Adicionar novos dispositivos/usuários: Adicione identificadores de dispositivos/usuários à audiência existente.
  6. Remover dispositivos/usuários: Remova os identificadores de dispositivos/usuários da lista.
  7. Substituir a audiência existente por novos dispositivos/usuários: Substitua a audiência pela lista carregada.
  8. Escolha o arquivo CSV para upload.
    Aguarde a mensagem de confirmação Upload feito com sucesso.
  9. Clique em Próximo.
    A aba Conectar é exibida.
  10. Faça alterações nas conexões de parceiros para essa audiência, se necessário.
  11. Clique em Concluir.

A sua audiência foi atualizado usando o arquivo CSV. É importante observar, no entanto, que a lista de audiências revisada ainda não está disponível para upload para os parceiros, pois as audiências importadas são processadas com uma atualização de dados diária.

Mensagens de erro

Mensagem Causa O que fazer
Problema com a lista de dispositivos Um ou mais problemas com a lista de dispositivos Verifique se o arquivo CSV:
 
  • está preenchido com dispositivos e identificadores GAID/IDFA no formato correto
  • contém os identificadores necessários
  • tem uma linha de header com os cabeçalhos no formato correto
  • não possui linhas em branco
  • app_id está associado ao app correto que você usa para o Audiences
Parece que a sua lista de dispositivos está vazia. Adicione alguns device IDs e tente novamente. O arquivo CSV está vazio Verifique se o CSV contém pelo menos um device ID.
Não conseguimos entender um ou mais dos seus device IDs.
  • O formato do CSV está incorreto
  • O arquivo enviado não é um arquivo CSV
  • O arquivo CSV foi editado e salvo por um programa que não é um editor CSV válido (por exemplo, Microsoft Excel)
  • Um ou mais device IDs estão no formato errado
  • Verifique se o CSV está no formato correto.
  • Verifique se todos os device IDs estão no formato correto.
  • Se tiver usando o Excel, salve o arquivo como um arquivo CSV, conforme descrito acima.
Não é possível usar a importação v1 ao aplicar a política de conta de usuário à audiência. Você enviou um arquivo CSV para uma audiência padrão utilizando a estrutura de importação V1.0. As audiências padrão devem ser enviadas usando um CSV na estrutura V2.0. Edite o arquivo CSV para utilizar o formato, as colunas e os identificadores descritos acima.
Tivemos um problema temporário de conexão e não conseguimos carregar o seu arquivo. Tente novamente agora. Possível erro de rede Tente enviar novamente o arquivo CSV.

Usando a Import Audience API

A Import Audience API é usada para adicionar ou remover dispositivos de uma audiência. 

Para importar uma nova audiência usando a API:

  1. No dashboard esquerdo da AppsFlyer, vá até Engajar > Audiences.
  2. Clique em Nova audiência.
  3. Escolha Importar audiência.
    A janela Importar audiência será aberta.
  4. Insira um Nome de audiência exclusivo.
  5. Selecione a plataforma: Android ou iOS.
  6. Indique se essa audiência é padrão ou como está .
    • Para uma audiência padrão, mantenha a caixa desmarcada.
    • Para uma audiência tal como está, marque a caixa (essa opção está disponível apenas para administradores). Em conformidade com o Digital Markets Act (DMA) da Google: a partir de 6 de março de 2024, ao importar uma audiência "como está", será necessário adicionar duas colunas adicionais de consentimento. Preencher esses campos assegura a máxima inclusão de usuários do Espaço Econômico Europeu (EEE) nas suas audiências do Google.
  7. Clique em Salvar.
    A página importar é exibida.
  8. Em Importar usando a API, mantenha a opção padrão de Adicionar novos dispositivos/usuários (já que se trata de uma nova audiência).
  9. Copie a URL de pedido da API da página Importar uma nova audiência (o token da API já está incluído).
  10. Depois, copie e cole o corpo do pedido da API.
  11. Clique em Concluído.
    A aba Conectar é exibida.
  12. (Opcional) Siga as instruções para conectar uma audiência a parceiros.
  13. Clique em Concluir.
  14. Prepare o pedido da API incluindo os identificadores de usuário/dispositivo e envie-o para a AppsFlyer. 

Para atualizar uma audiência existente usando a API:

  1. No dashboard esquerdo da AppsFlyer, vá até Engajar > Audiences.
  2. Clique no nome da audiência que você deseja atualizar.
    A tela Editar audiência aparece, com a aba Definir.
  3. Se você deseja alterar o nome da audiência, você pode fazer isso agora. Caso contrário, selecione a aba Importar.
  4. Em Importar usando a API, escolha o que fazer com a lista enviada:
  5. Adicionar novos dispositivos/usuários: Adicione identificadores de dispositivos/usuários à audiência existente. 
  6. Remover dispositivos/usuários: Remova os identificadores de dispositivo/usuário da audiência existente.
  7. Copie a API request URL da página Importar uma nova API de audiência (o token da API já está incluído). Atenção: Alterar essa opção modifica o caminho do endpoint no código a ser copiado. Certifique-se de que está usando o endpoint correto para a ação que está realizando (nessa e em futuras solicitações de API).
  8. Em seguida, copie o corpo do pedido da API.
  9. Clique em Próximo.
    A aba Conectar é exibida.
  10. Faça alterações nas conexões de parceiros para essa audiência, se necessário.
  11. Clique em Concluir.
  12. Prepare o pedido da API incluindo os identificadores de usuário/dispositivo e envie-o para a AppsFlyer.

Atenção: Ao importar através da API, a atualização da audiência levará 24 horas.

Códigos de resposta

Código Mensagem Descrição
200 A solicitação foi bem-sucedida Audiência importada com sucesso
400 Plataforma inválida. Essa audiência já está configurada para Android/iOS. Para usar uma plataforma diferente, crie uma nova audiência na interface do usuário. A plataforma especificada no corpo do pedido não corresponde à plataforma especificada ao criar a audiência.
400 X ou mais linhas não contêm um App ID. É necessário anexar um App ID a cada linha. Cada linha deve incluir um app_id.
  • Atenção: o app_id não é necessário para uma audiência tal como está, quando importada usando a funcionalidade legada de importação da versão V1.0.
400 X ou mais das suas linhas não contêm um identificador único válido. Algumas ou todas as linhas não contêm pelo menos um dos seguintes identificadores em um formato válido:
  • Para audiências Android: gaid OU oiad OU imei OU cuid OU braze_id OU amplitude_id
  • Para audiências iOS: idfv OU cuid OU braze_id OU amplitude_id
400 Não é possível processar mais de Y dispositivos por pedido (foram contados n dispositivos nesse pedido) O corpo do pedido inclui uma lista com mais de 10.000 device IDs
400 A lista de dispositivos não pode estar vazia

O corpo do pedido contém uma lista de dispositivos vazia

É necessário fornecer pelo menos um device ID por pedido
400 Não conseguimos interpretar um ou mais dos seus device IDs Alguns ou todos os device IDs não estão em um formato válido
400 X ou mais dispositivos a remover contêm mais do que um device ID Foi enviada uma solicitação de remoção com mais de um device ID
403 Proibido Pedido não autorizado: Chave de importação incorreta ou ausente
429 Pedidos em excesso Os pedidos estão limitados a 350 por minuto
500 Não foi possível interpretar o pedido

Formato do corpo do pedido inválido (não corresponde à estrutura JSON esperada ou não é JSON)

Consulte o exemplo de pedido acima

Limitações da API

  • Você só pode adicionar dispositivos a uma audiência através de uma solicitação.
  • Só é possível remover dispositivos de uma audiência através de uma solicitação.
  • Você pode enviar até 20.000 device IDs por solicitação.
  • Você pode enviar até 350 solicitações por minuto.

Imported Audience Management API

A Imported Audience Management API permite criar e configurar audiências importadas, conectar essas audiências a parceiros, eviar essas audiências aos parceiros e muito mais.