Num relance: Utilize a API de Identificadores Adicionais para carregar em massa identificadores de utilizadores dos seus sistemas internos (como BI e CRM) para o AppsFlyer Audiences, permitindo uma comunicação de público mais abrangente com parceiros relevantes, baseada nestes identificadores.
Sobre a API
A API de Identificadores Adicionais pode ser utilizada para adicionar os seguintes identificadores de utilizador dos seus sistemas internos ao AppsFlyer Audiences:
- Até 2 endereços de e-mail encriptados
- Número de telefone encriptado
- Número de telefone E164 encriptado
Pode optar por enviar estes identificadores aos seus parceiros do Audiences (sujeito à sua política de identificadores de utilizador a nível de conta), permitindo-lhes identificar de forma mais precisa os seus públicos-alvo. Note que nem todos os parceiros de publicidade suportam todos os identificadores.
Quando devo utilizar esta API?
Esta API foi desenhada para ser utilizada quando pretende fazer o upload de um grande volume de dados de identificadores. Normalmente, isto significa dados recolhidos ao longo do tempo (por exemplo, e-mails encriptados recolhidos de todos os utilizadores de uma app nos últimos 12 meses). Para atualizações individuais e em tempo real de identificadores de dispositivos específicos, configure identificadores adicionais no SDK da AppsFlyer ou API S2S-mobile.
Importante!
Encriptação: Todos os valores de identificadores adicionais devem ser encriptados com o algoritmo de hash SHA256. Os identificadores que não estiverem encriptados não serão processados.
Tempo: Para garantir uma correspondência precisa dos identificadores, a API de Identificadores Adicionais pode ser utilizada logo no dia seguinte ao relatório dos principais identificadores através do SDK da AppsFlyer (UTC). Por exemplo, os principais identificadores reportados a 3 de janeiro de 2022 (UTC) podem ser atualizados através desta API a partir de 4 de janeiro de 2022 (UTC).
Ações
Autenticação
O pedido deve incluir um cabeçalho HTTP contendo o token da API AppsFlyer V2.0 da sua conta. Solicite ao seu administrador de conta para obter este token no painel de controlo da AppsFlyer.
Especificações da API e código de exemplo
Adicionar/modificar identificadores (PUT)
URL do pedido de API
https://hq1.appsflyer.com/api/audience-bulk-api/v1/additional-identifiers/app/{app-id}
| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| {id da aplicação} |
ID da aplicação de onde os identificadores foram recolhidos (como aparece no painel da AppsFlyer) |
Sim |
Corpo do pedido API
{
"key_type": "<key_type>",
"action": "add",
"data": [
{
"key_value": "<key_value>",
"identifiers": {
"hashed_emails": [
"<hashed_email_value>",
"<hashed_email_value>"
],
"phone_number_sha256": "<phone_number_sha256_value>",
"phone_number_e164_sha256": "<phone_number_e164_sha256_value>"
}
},
{
"key_value": "<key_value>",
"identifiers": {
"hashed_emails": [
"<hashed_email_value>",
"<hashed_email_value>"
],
"phone_number_sha256": "<phone_number_sha256_value>",
"phone_number_e164_sha256": "<phone_number_e164_sha256_value>"
}
}
]
}| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| {key_type} |
O identificador usado como valor único para representar o utilizador em cada linha de dados do pedido. O valor especificado aqui aplica-se a todas as linhas do pedido. Valores possíveis:
|
Sim |
| {ação} |
adicionar |
Não Valor padrão: adicionar |
| {valor_chave} |
Valor válido do identificador para o key_type especificado |
Sim |
|
{identificadores} |
Objeto que contém os nomes e valores dos identificadores a adicionar:
|
Sim * Deve incluir um valor para pelo menos 1 destes 3 identificadores |
|
{hashed_emails} |
Uma matriz com até 2 endereços de e-mail com hash Formato:
Exemplo de valor antes do hash: nome@dominio.com |
Não |
|
{número_telefone_sha256} |
Número de telefone (ver nota abaixo) Formato:
Exemplo de valor antes do hash: 442070313000 |
Não |
| {número_telefone_e164_sha256} |
Número de telefone no formato E164 (ver nota abaixo) Formato
Exemplo de valor antes do hash: +442070313000 |
Não |
Nota
Diferentes parceiros de publicidade suportam formatos diferentes de número de telefone. Portanto, se optar por adicionar um número de telefone, é recomendável enviar ambos os identificadores: phone_number_sha256 e phone_number_e164_sha256.
Restrições
As seguintes restrições aplicam-se ao pedido Adicionar/modificar identificadores:
- Os valores anteriormente existentes (se houver) serão substituídos pelos valores enviados no pedido.
- O objeto {data} pode incluir no máximo 4.000 linhas (key_values) por pedido.
Exemplo de pedido para adicionar identificadores
HTTP PUT
body:
{
"key_type": "idfv",
"action": "add",
"data": [
{
"key_value": "CDDA802e-AAAA-BBBB-CCCC-DDDDDDDDDDDD",
"identifiers": {
"hashed_emails": [
"34d31be18022626de6b311d6a76e791176d2691b6eef406f524d8f56364c187a",
"d8c2aec999baad2464e521873ee4465caaf7ff6db8c8b4a25b09ca07694e4dee"
],
"phone_number_sha256": "6c91c4c640f6ef0162833260db4f13dec0df2b683092f4dba7e874bef1acea37",
"phone_number_e164_sha256": "f3d7e96c73fb0de1b66acfce541d7af758fbd4f3fa3af0ea4e10110000d3625e"
}
}
]
}Remover identificadores (PUT)
URL do pedido de API
https://hq1.appsflyer.com/api/audience-bulk-api/v1/additional-identifiers/app/{app-id}
| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| {id da aplicação} |
ID da aplicação de onde os identificadores foram recolhidos (como aparece no painel da AppsFlyer) |
Sim |
Corpo do pedido API
{
"key_type": "<key_type>",
"action": "remove",
"data": [
{
"key_value": ",<key_value>",
"identifiers": [
"hashed_emails",
"phone_number_sha256",
"phone_number_e164_sha256"
]
},
{
"key_value": ",<key_value>",
"identifiers": [
"hashed_emails",
"phone_number_sha256",
"phone_number_e164_sha256"
]
}
]
}| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| {key_type} |
O identificador usado como valor único para representar o utilizador em cada linha de dados do pedido. O valor especificado aqui aplica-se a todas as linhas do pedido. Valores possíveis:
|
Sim |
| {valor_chave} |
Valor válido do identificador para o key_type especificado |
Sim |
| {ação} |
remover |
Não Valor padrão: adicionar |
|
{identificadores} |
Uma matriz que contém os nomes dos identificadores cujos valores devem ser removidos:
|
Sim
|
Restrições
O objeto {data} pode incluir no máximo 4.000 linhas (key_values) por pedido.
Exemplo de pedido para remover identificadores
HTTP PUT
body:
{
"key_type": "gaid",
"action": "remove",
"data": [
{
"key_value": "cdda802e-aaaa-bbbb-cccc-dddddddddddd",
"identifiers": [
"hashed_emails",
"phone_number_sha256",
"phone_number_e164_sha256"
]
}
]
}Respostas
| Código | Mensagem | Descrição |
|---|---|---|
|
202 |
Aceite para processamento |
O pedido será processado na próxima janela disponível. |
|
400 |
O corpo do pedido deve conter um key_type válido |
Os seguintes key_types são suportados:
|
|
400 |
O pedido deve incluir 'dados' com pelo menos um elemento |
A lista de dados não pode estar vazia. |
|
400 |
Os 'dados' do pedido não devem ultrapassar o tamanho de 4.000 por pedido único |
A lista de dados pode incluir no máximo 4.000 linhas. |
|
400 |
Dados do pedido contêm demasiados elementos inválidos |
Mais de 10% dos dados a serem modificados não são válidos conforme a especificação. |
|
404 |
AppsFlyer - Página não encontrada |
Verifique o seguinte:
|
Exemplos de resposta
{
"message": "Accepted for processing",
"received": 1000,"invalid": 2,
"trace-id": "698ed323-c787-45b5-b792-463c67c94064"
}
{
"error": "Request body must have a valid key_type",
"trace-id": "18a5f685-ea4d-4ca9-beab-a542a3786d12"
}
{
"error": "Request must have 'data' with at least 1 element",
"trace-id": "c155a7fa-b573-4efe-9bfb-5ae7de40e7fd"
}
{
"error": "Request 'data' should not exceeds the size of 4000 in a single request”,
"trace-id": "b325a7fa-b573-4efe-9bfb-5ae7de40e72c"
}
{
"error": "Request data has too many invalid 'data' elements",
"valid": 2,
"invalid": 30,
"trace-id": "33551c1d-5682-405e-a959-c8729ca74735"
}
Limites de taxa
- 5 pedidos por segundo
- 350 pedidos por minuto