> ## Documentation Index > Fetch the complete documentation index at: https://docs.x.com/llms.txt > Use this file to discover all available pages before exploring further. # Audiences > Visão geral da segmentação de audiências no X Ads, cobrindo Custom Audiences, CRM, web, mobile e segmentos lookalike usados para alcançar usuários em campanhas de anúncios. export const Button = ({href, children}) => { return
; }; export const BlueprintMark = ({name, height = 150}) =>
; **Construa audiências altamente segmentadas para suas campanhas de anúncios no X usando dados primários e sinais de engajamento do X.** ## Links rápidos * [Referência completa da API](/x-ads-api/audiences/reference) — Todos os endpoints e objetos de Audience * [Guias](#guides) — CRM, Web, Mobile, ID Sync, uploads de User Data, FAQ ## Custom Audiences ### Visão geral Existem várias formas de os parceiros criarem [Custom Audiences](https://business.x.com/en/targeting/tailored-audiences.html). * [Audience API (CRM)](#crm) * [Web](#web) * [Mobile](#mobile) * [Flexible](#flexible) Observe que você não pode excluir custom audiences lookalike da segmentação. Além disso, não é possível segmentar uma custom audience e um lookalike da mesma custom audience no mesmo line item (ad group). **Gerenciamento de audiências** Audiências podem ser gerenciadas por parceiros de audiência e parceiros da Ads API. Oferecemos uma série de endpoints na API para acessar e manter custom audiences. Para informações sobre custom audiences, oferecemos 2 endpoints: * [GET accounts/:account\_id/custom\_audiences](/x-ads-api/audiences) * [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/x-ads-api/audiences) Para mais detalhes sobre como fazer upload e gerenciar audiências, consulte o [guia da Audience API](/x-ads-api/audiences). **Tempos de processamento** De forma geral, as alterações em audiências são processadas em lotes que rodam a cada 6-8 horas. Enquanto uma alteração de audiência está sendo processada, a audiência existente a ser atualizada não é afetada. Não recomendamos fazer mais de uma atualização de adições e uma atualização de remoções por audiência dentro deste intervalo. **Segmentação (Targeting)** Uma audiência só pode ser segmentada se corresponder a pelo menos 100 usuários ativos nos últimos 90 dias em clientes de propriedade e operados pelo X. [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/x-ads-api/audiences) indicará se uma audiência não pode ser segmentada por corresponder a poucos usuários. **Audience API (CRM)** image2 Parceiros de audiência ou API fornecem uma lista de identificadores com hash e o X faz a correspondência produzindo segmentos disponíveis para compra de mídia no X. Parceiros podem criar essas audiências com a [Audience API](/x-ads-api/audiences). **Como funciona?** image3 **Web** Oferecemos um processo padrão de correspondência por cookies ao trabalhar com parceiros de audiência MPP para identificar segmentos a serem visados na compra de mídia no X. Além disso, os anunciantes podem configurar uma [X Web Event Tag](/x-ads-api/measurement/web-conversions#web-event-tags) para coletar dados de usuários do site e criar uma Custom Audience correspondente. **Etapas de configuração** image0 **Como funciona?** image1 **Mobile** Consulte o [post do blog sobre Custom Audiences a partir de apps mobile](https://blog.x.com/2014/introducing-tailored-audiences-from-mobile-apps) para detalhes. **Flexible** [Audiências flexíveis](/x-ads-api/audiences) dão aos anunciantes a capacidade de criar e salvar combinações de audiências com base em custom audiences existentes ou subconjuntos de custom audiences existentes. Subconjuntos dos membros de uma custom audience podem ser segmentados com base na recência e frequência de interação. **Casos de uso restritos para Custom Audiences** [Leia mais sobre as restrições](https://developer.x.com/en/developer-terms/more-on-restricted-use-cases "Leia mais sobre as restrições") ### FAQ de audiências **P: Enviamos uma grande quantidade de dados, por que o tamanho da audiência aparece como TOO\_SMALL?** R: No momento, os dados são adicionados à audiência em tempo real, mas o job que processa os dados para fornecer o tamanho da audiência só rodará após um período. O tamanho correto da audiência deve ser exibido na UI depois de algumas horas. **P: Terminamos de enviar os dados da audiência e esperamos 24 horas ou mais, mas ainda não conseguimos segmentar a audiência - o que devemos fazer?** R: Por favor, confirme o seguinte: * 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. Se todo o resto estiver confirmado como correto e funcionando, entre em contato com os contatos de produto do X com informações o mais detalhadas possível (veja o [Guia de Inbounds de Parceiros](/x-ads-api/introduction) como exemplo das informações preferidas). **P: Quantas vezes podemos chamar o endpoint, e com qual algoritmo?** R: Recomendamos fortemente que você chame nosso sistema com deltas incrementais, e nunca reenvie as adesões completas da audiência. O sistema foi testado para ter uma taxa de transferência suficiente para processar atualizações incrementais para alguns dos maiores sites do mundo. O upload inicial das audiências deve ser cuidadosamente controlado e espera-se que o primeiro upload leve um tempo significativo para ser concluído. **P: Qual é o tamanho mínimo para que uma audiência seja usada em segmentação?** * 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. **P: Quanto tempo leva para processar os arquivos de audiência? E quanto tempo leva para os arquivos estarem prontos na interface do X?** * 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. **P: Como a taxa de correspondência é calculada?** * Taxa de correspondência = usuários ativos do X nos últimos 90 dias / número de usuários fornecidos **P: Como testamos se um arquivo de audiência está funcionando corretamente?** * 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. **P: O que é um partner user identifier (`p_user_id`)?** * É o identificador utilizado por sua empresa para identificar de forma única cada um dos seus clientes. **P: O que é um standard ID?** * Pode ser um endereço de e-mail, device ID, @handle do X ou ID. **P: Como obtenho a chave HMAC?** * Ela será fornecida por e-mail criptografado. Forneça sua chave pública PGP para [mpp-inquiry@x.com](mailto:mpp-inquiry%x.com) e enviaremos um e-mail de teste para verificar se tudo está funcionando. Uma vez verificado, enviaremos a chave HMAC. **P: Como verifico se o processo de hashing funcionou usando a chave HMAC fornecida?** * 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. **P: Há um limite de tamanho de arquivo para o full data match?** * Não, não há limite de tamanho para o arquivo de full data match. **P: Quanto tempo levará para o arquivo de full data match ser processado?** * Uma vez que o arquivo é recebido pelo X, levará aproximadamente 1 dia para processar o arquivo. ### CRM image0 Este documento descreve os detalhes de integração para parceiros CRM de Custom Audiences, incluindo formatos de arquivo e processo de troca de dados. **Resumo** A empresa fornecerá uma lista de identificadores comuns de usuário com hash (ou seja, endereços de e-mail) ou partner user IDs em nome de um cliente ao X para realizar uma correspondência às cegas e produzir uma lista de X User IDs para segmentação. Os segmentos para segmentação estarão disponíveis para o @handle específico do anunciante especificado pelo nome do arquivo na configuração da campanha em ads.x.com. Todos os arquivos da empresa serão fornecidos ao X através de um pacote seguro no IronBox ([www.golockbox.com](http://www.golockbox.com)) por meio de uma conta específica concedida à empresa pelo X. O X fornecerá acesso ao IronBox. A documentação das APIs do IronBox pode ser encontrada em [https://secure.goironcloud.com/Docs/Help/](https://secure.goironcloud.com/Docs/Help/). #### Requisitos de correspondência de Partner ID Se a empresa usa seu próprio sistema padrão de IDs para rastrear usuários (ou seja, não identificadores comuns como endereços de e-mail, device ids, X user ID, etc.), este é o processo recomendado. **1. Full Data match** Inicialmente, a empresa fornecerá uma lista abrangente de todos os registros de usuários que incluem um identificador comum único ao X em um único arquivo para realizar uma correspondência completa e produzir um mapeamento armazenado pelo X de Partner IDs (`p_user_id`) para X IDs (`tw_id`). Isso será feito regularmente a cada 2-3 meses para garantir manutenção adequada. Uma vez concluída a correspondência, o X compartilhará uma taxa de correspondência inicial deste arquivo com a empresa por e-mail. O formato deste arquivo deve ser: Convenção de nome: FullDataMatch.\[CompanyName].txt Algoritmo de hashing: HMAC\_SHA-256 Formato: Coluna 1: Valor HMAC com hash dos identificadores comuns Coluna 2: Partner User ID (único por usuário, não único no arquivo) Delimitador de coluna (CSV): Vírgulas serão usadas para delimitar o identificador comum do Partner ID Valores separados por linha * Ex: Se o registro de usuário A tem Partner User ID 1 e identificadores comuns 1, 2 e 3: | | | | :-------------------- | :--------- | | identificador comum 1 | p\_user\_1 | | identificador comum 2 | p\_user\_1 | | identificador comum 3 | p\_user\_1 | \*Consulte a seção de Diretrizes de Hashing para identificadores comuns abaixo. **2. Custom Segment Lists** A empresa fornecerá listas de usuários na forma de `p_user_id` para criar custom audiences para segmentação no X. * 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 Se a empresa não usa um ID padrão para mapear identificadores de usuário, este é o processo recomendado. **Custom Segment Lists** A empresa fornecerá listas de identificadores comuns de usuário com hash diretamente ao X em nome dos clientes para criar custom audiences. O formato deste arquivo deve ser: * 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 A operação de um arquivo será determinada pelo nome do arquivo com as seguintes operações disponíveis e convenção geral de nomeação: audiencename\_partnername.handle.operation.filetype * 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 Criar uma nova audiência com um único arquivo, por exemplo, loyalty\_card\_holders\_partnername.pepsi.new\.txt Add - Adicionar as correspondências de uma lista a uma audiência existente, por exemplo, loyalty\_card\_holders\_partnername.pepsi.add.txt Remove - Remover as correspondências de uma lista de uma audiência existente, ex.: loyalty\_card\_holders\_partnername.pepsi.remove.txt Remove All - Remover as correspondências produzidas de uma lista cumulativa atualizada regularmente de todas as audiências desse cliente (ou seja, a lista de Opt Out do cliente). Ex.: partnername.pepsi.removeall.txt * 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. Replace - Remover uma audiência existente e substituí-la por uma nova lista de audiência. Ex.: loyalty\_card\_holders\_partnername.pepsi.replace.txt Overall Company Opt-Out - A empresa fornecerá um arquivo cumulativo de Opt-Out para remover usuários que fizeram opt-out conforme a política da empresa. O X respeitará apenas a última lista fornecida neste arquivo Company Opt-Out e a respeitará em todas as audiências existentes e futuras. O formato do arquivo Company Opt-Out será: Ex.: partnername.removeall.txt Delete - Remover uma audiência existente da lista atual de audiências, por exemplo, Ex.: loyalty\_card\_holders\_partnername.pepsi.delete.txt #### Diretrizes de Hashing O X compartilhará com segurança uma chave de produção codificada em base64 via PGP para gerar o hash dos identificadores comuns de usuário (ou seja, endereços de e-mail). A empresa fará a decodificação base64 da chave para produzir uma chave de 32 bytes a ser usada para realizar o hashing. Exemplo de chave codificada em base64: BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM= Exemplo de chave decodificada de Base64: /:� TшY Normalização: A empresa fará uma normalização básica nos identificadores comuns antes do hashing (exceto em Device IDs, veja a seção Normalização de Device ID). #### Normalização de e-mail Ou seja, remover espaços à esquerda e à direita e transformar o endereço de e-mail em minúsculas. Ex.: E-mail bruto: testemail\_Organisational\_baseball+884`@`It92I6Ev2B`.`Com Após normalização: testemail\_organisational\_baseball+884`@`it92i6ev2b`.`com Valor com hash: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec Observação: O número específico de caracteres tanto do hmac codificado quanto da chave pode variar de acordo com a entrada e a codificação. #### Normalização de Device ID Teremos os mesmos requisitos para o hashing de device IDs usando um algoritmo SHA-256 e um salt comum que fornecemos aos parceiros de dados. Removemos espaços como fazemos com endereços de e-mail, mas não há normalização para minúsculas em IDFAs/Android IDs e o formato exato do IDFA/Android ID deve ser usado. Aqui está um exemplo do formato bruto de Device IDs para iOS e Android, pré-hashing: iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431 Android ID: b5bf2122961b3595 Hashed iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b Hashed Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4 #### Normalização de X User ID Os X IDs ainda serão hash porque o agrupamento de dados - ou seja, lista de @handles dos clientes - é privado ao anunciante, mesmo que não seja PII. Teremos os mesmos requisitos para hashing de X IDs usando o algoritmo SHA-256 e um salt comum que fornecemos aos parceiros de dados. Espaços devem ser removidos tanto do X ID quanto do `@`username, mas User IDs não requerem normalização. @usernames devem ser transformados em minúsculas para normalização. E o símbolo @ não deve ser incluído como parte do username. O formato bruto do ID será: * User ID: 27674040 * @username: testusername Hashed User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85 Hashed @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812 ### Integração de ID Sync Parceiros que enviam dados com um `p_id` devem passar por um processo de ID Sync para gerar um mapeamento dos user ids do anunciante ou parceiro para os X user ids. Isso permite que os anunciantes segmentem diretamente seus próprios segmentos de usuários no X. Os parceiros também devem definir o valor do parâmetro `user_identifier_type` como `TALIST_PARTNER_USER_ID` ou `TAWEB_PARTNER_USER_ID` ao enviar suas atualizações de membros. * **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](/x-ads-api/audiences/reference#crm). #### URL do Pixel | | | :----------------------------------------------------------------- | | **URL Base** | | [https://analytics.x.com/i/adsct](https://analytics.x.com/i/adsct) | #### Parâmetros do Pixel | | | | :------------ | :------------------------------------- | | **Parâmetro** | **Descrição** | | `p_id` | Seu partner id atribuído pelo X | | `p_user_id` | O id do usuário no sistema do parceiro | #### Pixel de ID Sync: Usando um exemplo de partner id 111 e um exemplo de `p_user_id` abc, o pixel construído seria: ```json theme={null}
``` **Configuração e envio de arquivos de Opt-Out** Os parceiros devem fornecer ao X uma lista de usuários que, pelo melhor conhecimento do parceiro, optaram por sair da entrega de anúncios segmentados. O formato do arquivo deve ser enviado como: | | | | | | :------------------- | :------------------------------------- | :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Número da coluna** | **Nome da coluna** | **Tipo da coluna** | **Descrição** | | 1 | Partner ID | string | O "partner id" é o ID que o X fornece ao Parceiro para identificar cada Parceiro de forma única. | | 2 | O id do usuário no sistema do parceiro | string | O `p_user_id` é o ID único usado para identificar o usuário pelo Parceiro. O arquivo com esses usuários opt-out deve ser enviado usando o endpoint [TON upload](/x-ads-api/audiences) e o caminho dos dados enviados deve ser enviado para o endpoint Global Opt Out: [PUT accounts/:account\_id/custom\_audiences/global\_opt\_out](/x-ads-api/audiences). | **Envio de atualizações de membros** Conforme especificado em nossa documentação de endpoints, ao passar usuários pelo endpoint [POST custom\_audience\_memberships](/x-ads-api/audiences), você deve passar um customer ID para permitir uma correspondência baseada em cookie. Parceiros que enviam dados com um `p_id` **devem** definir o `user_identifier_type` como `TALIST_PARTNER_USER_ID` ou `TAWEB_PARTNER_USER_ID`. Todas as outras etapas permanecem iguais às listadas no [Guia de Integração da Real-Time Audience API](/x-ads-api/audiences) ### Custom Audiences User Data Este documento descreve o formato dos dados de usuário para [Custom Audience](/x-ads-api/audiences). **Normalização de dados** **Device IDs**: * 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` **Endereços de e-mail**: * minúsculas, remover espaços à esquerda e à direita; ex: `support@x.com` **Usernames do X**: * sem @, em minúsculas e com espaços à esquerda e direita removidos; ex: `jack` **X User IDs**: * Inteiro padrão; ex: `143567` **Hashing dos dados** Os dados de cada linha devem ser hash com `SHA256`, sem salt. Além disso, o hash de saída final deve estar em minúsculas. Ex: 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d e **não** 49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D ``` # hashing do usuário @AdsAPI usando python import hashlib hashlib.sha256("adsapi".encode()).hexdigest() #saída 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d ``` Exemplos de código adicionais para hashing podem ser encontrados em [github.com/xdevplatform/ads-platform-tools](https://github.com/xdevplatform/ads-platform-tools). ### Custom Audiences: Web info.png **Informação** Os parceiros enviarão uma lista de IDs (`p_user_ids`) para segmentar em nome de um anunciante. Isto é feito através de um processo de ID Sync que constrói um mapeamento entre os `p_user_ids` e o X user ID. Este mapeamento é então usado para produzir listas de X User IDs que podem ser usados para segmentação. Essas custom audiences serão disponibilizadas para o @handle específico do anunciante especificado pelo rótulo na configuração de campanha Custom Audiences Web em ads.x.com. O X fornecerá o pixel seguro que pode ser colocado em tags e sites de parceiros para fazer a correspondência dos IDs (`p_user_ids`) com os X user IDs. Uma vez concluído o processo de ID Sync, os arquivos de segmentação serão criados pelo parceiro e serão disponibilizados ao X por meio de um endpoint HTTPS. Esses arquivos são ingeridos regularmente pelo X e depois disponibilizados na UI do X. **Pixel seguro do X** O pixel seguro do X terá a seguinte aparência: [https://analytics.x.com/i/adsct?p\\\_user\\\_id=xyz\&p\_id=123](https://analytics.x.com/i/adsct?p\\_user\\_id=xyz\&p_id=123) **`p_user_id`** - xyz representa o partner user ID fornecido pelo Parceiro **`p_id`** - 123 representa o ID único do Parceiro (fornecido pelo X) **Endpoint HTTPS do Parceiro e arquivo de usuários para segmentação** O parceiro precisará fornecer ao X um endpoint HTTPS e credenciais (usuário/senha) que podem ser usados para ingerir o arquivo de segmentação regularmente. Um exemplo de endpoint HTTPS será: ``` https:///twitter/partner_targeting_%Y-%M-%D.tsv.gz ``` %Y - Código de formato para Ano (YYYY) %M - Código de formato para Mês (MM) %D - Código de formato para Dia (DD) Os dados transmitidos consistirão nos seguintes arquivos: 1. Partner Targeting User File 2. Targeting Conversion File Todos os arquivos estarão em formato TSV, onde os campos individuais de cada linha são separados uns dos outros por um caractere de tabulação. Valores de campo válidos nunca conterão o caractere de tabulação. **Faixa de IP do X permitida:** Aqui está a faixa de IPs que podem ser permitidos para acesso ao Endpoint do Parceiro. * 199.16.156.0/22 * 199.59.148.0/22 **Partner Targeting User File:** | **Número da coluna** | **Nome da coluna** | **Tipo da coluna** | **Descrição** | | :------------------- | :----------------- | :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | partner id | string | O "partner id" é o ID que o X fornece ao Parceiro para identificar cada Parceiro de forma única. | | 2 | advertiser id | string | O "advertiser id" é o @handle do anunciante. | | 3 | p\_user\_id | string | O "p\_user\_id" é o ID único usado para identificar o usuário pelo Parceiro. | | 3 | confidence score | integer | O "confidence score" é opcional. Nossa recomendação é usar 0-100. Se o caso de uso for retargeting, então um confidence score de "100" é um usuário que foi diretamente retargetado. Qualquer valor entre 0-99 corresponderia ao nível de confiança do look-alike. | | 4 | segment label | string | O "segment label" é opcional. Parceiros podem usar "segment label" para especificar categorias de produtos, por exemplo. Nossa recomendação é usar este "segment label" porque é o nome legível para Custom Audiences na UI do ads.x.com. | **Observações:** Toda vez que recebemos um novo Partner Targeting File, esperamos que esta seja a lista completa de usuários que o Parceiro recomenda que segmentemos, não incremental, a menos que seja acordado o contrário. Combinaremos com cada parceiro a frequência de entrega deste Partner Targeting File. Se não recebermos um Partner Targeting File conforme esperado, usaremos a versão anterior com algum tempo pré-definido de expiração. ## Integração da Audience API ### Visão geral A Audience API foi lançada como parte da [v4](/x-ads-api/introduction) da Ads API e traz várias melhorias em relação aos endpoints legados de audiências. Este novo endpoint é sustentado por um novo backend de processamento de audiências e traz várias melhorias em termos de estabilidade, robustez e confiabilidade. O objetivo deste guia é destacar as diferenças entre a Audience API e os processos legados de upload e gerenciamento de audiências. A documentação de referência pode ser encontrada na página de referência da [Audience API](/x-ads-api/audiences). **Nota**: Todos os dados de usuário de Audience devem ser hashed com SHA-256 antes do upload. Mais detalhes, junto com os tipos de identificadores de usuário aceitos e a normalização de dados, podem ser encontrados na página de [user data](/x-ads-api/audiences). **Alterações na funcionalidade de Audience** As seguintes alterações em Custom Audiences foram introduzidas a partir da v4 e quaisquer endpoints depreciados não estarão mais disponíveis quando a v3 da Ads API for descontinuada: * **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](/x-ads-api/audiences). 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) **Pré-requisitos** * Acesso à Ads API * Para acesso ao endpoint Audience, você precisará ser adicionado a uma allowlist. Preencha este formulário e aceite o novo [X Ads Products and Services Agreement](/x-ads-api/introduction) se aceitou inicialmente antes de 2018-08-01 **Processo de upload de Audience** A tabela a seguir lista as principais diferenças entre os fluxos antigo e novo de criação de Audience, com mais detalhes disponíveis abaixo: | Etapa no processo | Audience API | (Depreciado) TON Upload | | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | | Criar uma Audience shell | Pode ser criada pelo endpoint [POST custom\_audience](/x-ads-api/audiences) | Pode ser criada pelo endpoint [POST custom\_audience](/x-ads-api/audiences) | | Adicionar um novo usuário | Use `operation_type` `Update` com o endpoint [Audience](/x-ads-api/audiences) | Use `operation` `ADD` com o endpoint [POST custom\_audience\_changes](/x-ads-api/audiences) | | Remover um usuário | Use `operation_type` `Delete` com o endpoint [Audience](/x-ads-api/audiences) | Use `operation` `REMOVE` com o endpoint [POST custom\_audience\_changes](/x-ads-api/audiences) | | Opting-Out de usuários | Use `operation_type` `Delete` com o endpoint [Audience](/x-ads-api/audiences) e os `custom_audience_id`s correspondentes dos quais o usuário faz parte | Use o [endpoint Global opt-out](/x-ads-api/audiences) | **Nota** Quaisquer audiências sendo atualizadas ou opted-out via o caminho TON Upload devem ter uma lista correspondente enviada pelo endpoint [TON Upload](/x-ads-api/audiences) e associada a uma Audience usando o endpoint [custom\_audience\_changes](/x-ads-api/audiences). **Rate Limiting** O endpoint da Audience API tem um rate limit de 1500/1min por conta. Não há limites no número de usuários que podem ser enviados em um único payload. As únicas restrições no payload são: 1. Número total de operações: 2500 operações 2. Tamanho máximo do payload: 5.000.000 bytes **Gerenciamento de usuários de Audience** Para criar uma nova Audience, as seguintes etapas são necessárias ### Criar uma nova Custom Audience Crie uma nova "shell" de Custom Audience usando o endpoint [POST custom\_audience](/x-ads-api/audiences) e recupere o `id` correspondente da Custom Audience. Esta etapa é necessária se você estiver criando uma Audience do zero. Se estiver atualizando uma Audience existente, pule para a próxima seção ### Adicionar usuários a uma Audience Use o endpoint [POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/users](/x-ads-api/audiences) com o `id` da Custom Audience e um payload de exemplo assim: POST [https://ads-api.x.com/11/accounts/18ce54d4x5t/custom\_audiences/1nmth/users](https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users) ``` # 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" ] } ] } } ] ``` Para adicionar um usuário a uma Audience, use o `operation_type` `Update`. A nova interface de Audience permite passar múltiplas chaves de usuário para um único usuário. Cada objeto no array de objetos JSON corresponde a um único usuário. Usando o payload de exemplo acima, a requisição adicionará dois usuários a uma Audience, um com `email` e `handle` e outro com `email` e `twitter_id`. #### Remover usuários de uma Audience Semelhante ao processo descrito para adicionar usuários, usuários podem ser removidos de uma audiência assim: POST [https://ads-api.x.com/11/accounts/18ce54d4x5t/custom\_audiences/1nmth/users](https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users) ``` # 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" ] } ] } } ] ``` O `operation_type` deve ser definido como `Delete` e os usuários serão correspondidos em quaisquer chaves presentes ao adicionar usuários à audiência. Por exemplo, se um usuário foi adicionado a uma audiência usando `email` e `twitter_id`, então o mesmo usuário pode ser removido usando qualquer uma dessas chaves, ou seja, `email` ou `twitter_id`, ou ambas. Além disso, é possível adicionar e remover usuários de uma Audience na mesma requisição. O endpoint suporta múltiplos `operation_type` por requisição. #### Opt-Out de usuários Com a depreciação do endpoint global opt-out, os parceiros são obrigados a `Delete` quaisquer usuários que optaram por sair de qualquer Audience. Existem algumas formas de fazer isso: 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. **Melhores práticas gerais** * 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](https://en.wikipedia.org/wiki/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 Para a referência completa (Tailored Audience Permissions, Custom Audiences, Custom Audiences Users, Keyword Insights, Do Not Reach Lists, etc.), consulte a página **[Referência da API de Audiences](/x-ads-api/audiences/reference)**.