Audiences

​

Links rápidos

• Referência completa da API — Todos os endpoints e objetos de Audience
• Guias — CRM, Web, Mobile, ID Sync, uploads de User Data, FAQ

​

Custom Audiences

​

Visão geral

• Audience API (CRM)
• Web
• Mobile
• Flexible

• GET accounts/:account_id/custom_audiences
• GET accounts/:account_id/custom_audiences/:custom_audience_id

​

FAQ de audiências

• O user ID que está sendo passado está correto e não malformado.
• Os nomes das audiências passados estão corretos e correspondem a atualizações anteriores de membros.
• Confirme a resposta dos comandos POST.
• Confirme se o pixel de ID Sync está implementado corretamente e, conforme descrito no processo de ID Sync, que usuários suficientes visitaram o site em questão para mapeá-los. Usuários não mapeados nas atualizações de membros não serão convertidos em usuários segmentáveis.

• O tamanho mínimo para uma audiência é de 100 usuários (após correspondência). Se uma audiência com menos de 500 usuários for correspondida, ela não estará disponível para segmentação na UI do X Ads.

• Normalmente leva de 4 a 6 horas para processar os arquivos, mas depende do tamanho do arquivo. Depois de processado, as audiências ficam disponíveis na UI do X Ads.

• Taxa de correspondência = usuários ativos do X nos últimos 90 dias / número de usuários fornecidos

• Você pode fornecer um arquivo de teste e usar “keltonlynn” como o handle do anunciante. Podemos então verificar se o arquivo é adequadamente ingerido e carregado na UI do X.

• É o identificador utilizado por sua empresa para identificar de forma única cada um dos seus clientes.

• Pode ser um endereço de e-mail, device ID, @handle do X ou ID.

• Ela será fornecida por e-mail criptografado. Forneça sua chave pública PGP para mpp-inquiry@x.com e enviaremos um e-mail de teste para verificar se tudo está funcionando. Uma vez verificado, enviaremos a chave HMAC.

• O X fornecerá um arquivo de teste (contendo endereços de e-mail de amostra, device IDs, etc.) e um arquivo de hash resultante contra o qual você pode verificar seus resultados.

• Não, não há limite de tamanho para o arquivo de full data match.

• Uma vez que o arquivo é recebido pelo X, levará aproximadamente 1 dia para processar o arquivo.

​

CRM

​

Requisitos de correspondência de Partner ID

• Ex: Se o registro de usuário A tem Partner User ID 1 e identificadores comuns 1, 2 e 3:

• Valores separados por linha
• p_user_id
• (O mesmo fornecido em 1. Full Data Match acima. Se o valor fornecido no full data match for hash, a empresa fornecerá o mesmo valor com hash no arquivo de audiência. Se o valor fornecido não for hash, a empresa fornecerá o valor não hasheado.)

​

Requisitos de correspondência padrão

• Valores separados por linha
• Identificador comum de usuário com hash (ou seja, endereço de e-mail)
• Seguir as convenções de nomeação de arquivos descritas abaixo
• Seguir as diretrizes de hashing para endereços de e-mail abaixo (em Diretrizes de Hashing)

​

Nomeação e operações da Custom Segment List

• audiencename: O nome da Custom Audience. Este campo é o nome que será exibido ao selecionar a audiência na UI de configuração de campanhas em ads.x.com, por exemplo, brand_loyalty_card_holders.
• partnername: Nome da empresa que fornece os dados em nome do anunciante, por exemplo, company_name.
• handle: Conta do X (@handle) que terá acesso às Custom Audiences, por exemplo, @pepsi, @dietpepsi
• operation: new, add, remove, removeall, replace (detalhes abaixo)
• : Tempo epoch Unix padrão em segundos, usado para garantir que cada arquivo de audiência enviado seja único
• filetype: o arquivo deve estar no formato *.txt

​

Criando e atualizando audiências

• Isso pode ser usado para uma lista abrangente de usuários que optaram por sair do Anunciante.
• O X respeitará apenas a última lista fornecida neste arquivo, e a respeitará em todas as audiências existentes e futuras para X users correspondidos no momento em que este arquivo foi fornecido e processado.

​

Diretrizes de Hashing

​

Normalização de e-mail

​

Normalização de Device ID

​

Normalização de X User ID

• User ID: 27674040
• @username: testusername

​

Integração de ID Sync

• Apenas Web: Pode ser feito colocando um pixel no site do anunciante, conforme descrito abaixo.
• Lista: Pode ser feito usando qualquer um dos métodos descritos na página CRM.

​

URL do Pixel

​

Parâmetros do Pixel

​

Pixel de ID Sync:

    <pre class="brush: xml">
    <img height="1" width="1" src="https://analytics.x.com/i/adsct?p_id=111&p_user_id=abc" style="display:none" />
    </pre>

​

Custom Audiences User Data

• IDFA - em minúsculas com traços; ex: 4b61639e-47cc-4056-a16a-c8217e029462
• AdID - formato original do dispositivo é obrigatório, sem maiúsculas com traços; ex: 2f5f5391-3e45-4d02-b645-4575a08f86e
• Android id - formato original do dispositivo é obrigatório, sem maiúsculas sem traços ou espaços; ex: af3802a465767e36

• minúsculas, remover espaços à esquerda e à direita; ex: support@x.com

• sem @, em minúsculas e com espaços à esquerda e direita removidos; ex: jack

• Inteiro padrão; ex: 143567

# hashing do usuário @AdsAPI usando python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#saída
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

​

Custom Audiences: Web

https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz

1. Partner Targeting User File
2. Targeting Conversion File

• 199.16.156.0/22
• 199.59.148.0/22

​

Integração da Audience API

​

Visão geral

• Depreciado TON Upload:
  • GET accounts/:account_id/custom_audience_changes
  • GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
  • POST accounts/:account_id/custom_audience_changes
  • PUT accounts/:account_id/custom_audiences/global_opt_out
• Depreciado Real Time Audiences:
  • POST custom_audience_memberships
• Custom Audience:
  • O parâmetro list_type será removido da requisição e resposta em todos os endpoints de Custom Audience. Este parâmetro era usado anteriormente para identificar o tipo de identificador de usuário da Audience (ou seja, e-mail, X User ID, etc.), no entanto, as Audiences agora têm a capacidade de aceitar múltiplos identificadores de usuário para a mesma Audience, tornando esse valor irrelevante.
• Geral:
  • A janela de lookback da Audience foi atualizada para corresponder a usuários ativos nos últimos 90 dias (de 30 dias)
  • O número mínimo de usuários correspondidos necessários para que uma audiência seja segmentável foi reduzido para 100 usuários (de 500 usuários)

1. Número total de operações: 2500 operações
2. Tamanho máximo do payload: 5.000.000 bytes

​

Criar uma nova Custom Audience

​

Adicionar usuários a uma Audience

    # Todos os valores devem estar em hash, valores não hasheados são usados neste exemplo apenas para ilustração
    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "handle": [
                "x",
                "adsapi"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

​

Remover usuários de uma Audience

    # Todos os valores devem estar em hash, valores não hasheados são usados neste exemplo apenas para ilustração
    [
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

​

Opt-Out de usuários

1. Manter o controle de quais usuários fazem parte de quais Audiences e remover esses usuários individualmente de cada Audience.
2. Remover o usuário de todas as Audiences associadas a uma conta Ads.

• Recomendamos fortemente chamar este endpoint em batches quase em tempo real para evitar picos nas filas que demoram mais para processar e, em geral, causar carga desnecessária no nosso sistema. Isso também garante que os usuários estejam disponíveis para segmentação de campanha mais cedo.
• Uma chamada de API bem-sucedida retornará um success_count e total_count correspondendo ao número de objetos user recebidos na requisição.
• Este endpoint é atômico por natureza, ou seja, a requisição inteira é bem-sucedida ou, no caso de qualquer erro, a requisição inteira falha. Em caso de resposta de erro, os consumidores da API devem corrigir o erro e tentar novamente a requisição com o payload completo.
• Em caso de falha, os parceiros devem usar uma abordagem de exponential backoff com retries. Por exemplo, tentar novamente imediatamente na primeira falha, tentar após 1 minuto após a segunda falha e após 5 minutos após a terceira falha consecutiva, e assim por diante

​

Referência completa da API