| Versão | Caminho | Data de introdução | Data de descontinuação | Data de fim de vida |
|---|---|---|---|---|
| 12.0 | /12/ | 27 de outubro de 2022 | A definir | A definir |
| 11.0 | /11/ | 31 de março de 2022 | A definir | A definir |
| 10.0 | /10/ | 31 de agosto de 2021 | 31 de março de 2022 | 27 de outubro de 2022 |
| 9.0 | /9/ | 2 de março de 2021 | 31 de agosto de 2021 | 31 de março de 2022 |
| 8.0 | /8/ | 8 de setembro de 2020 | 2 de março de 2021 | 31 de agosto de 2021 |
| 7.0 | /7/ | 3 de março de 2020 | 1º de setembro de 2020 | 2 de março de 2021 |
| 6.0 | /6/ | 28 de agosto de 2019 | 3 de março de 2020 | 1º de setembro de 2020 |
| 5.0 | /5/ | 28 de fevereiro de 2019 | 28 de agosto de 2019 | 3 de março de 2020 |
| 4.0 | /4/ | 28 de agosto de 2018 | 28 de fevereiro de 2019 | 28 de agosto de 2019 |
| 3.0 | /3/ | 1º de fevereiro de 2018 | 28 de agosto de 2018 | 28 de fevereiro de 2019 |
| 2.0 | /2/ | 10 de julho de 2017 | 1º de fevereiro de 2018 | 1º de agosto de 2018 |
| 1.0 | /1/ | 31 de março de 2016 | 7 de julho de 2017 | 10 de janeiro de 2018 |
| 0.0 | /0/ | 21 de fevereiro de 2013 | N/A | 31 de outubro de 2016 |
Visão geral
- Remoção de um parâmetro do request/response da API
- Modificação do nome de quaisquer parâmetros ou endpoints
- Alteração na representação de valores (preview_url → card_uri)
- Mudança no comportamento de endpoints (por exemplo, estatísticas async vs sync)
- Adição/alteração de parâmetros opcionais ou obrigatórios (por exemplo, tornar name um campo obrigatório na solicitação)
Estratégia de versionamento
- Todas as mudanças incompatíveis serão agrupadas em uma nova versão
- A descontinuação de versões existentes, sempre que uma nova versão for anunciada, terá duração de 6 meses
- A qualquer momento, a API permitirá solicitações de duas versões simultaneamente; no entanto, a mais antiga das duas não terá suporte
- Para acelerar a adoção de novos produtos, eles serão lançados de forma contínua (fora da cadência de versionamento)
-
Todas as respostas da API conterão um
x-current-api-version, definido para a versão atual da API, além de um cabeçalhox-api-warnao chamar quaisquer endpoints de API descontinuados.
v9
Observação: A partir deste lançamento, a Version 7 (v7) da Ads API chegou ao fim do ciclo de vida e não está mais disponível.
v8
v7
v6
v5
accounts/:account_id/account_media foram descontinuados.
Assim como em versões anteriores, haverá um período de transição de 6 meses para a migração para a v5. Em 2019-08-28, a versão 4 da X Ads API não estará mais disponível. Incentivamos todos os parceiros a migrarem para a versão mais recente da API o quanto antes, a fim de evitar qualquer interrupção de serviço. A versão 3 da X Ads API atingiu o fim do ciclo de vida e não está mais disponível.
Novidades
CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE e PROMOTED_TWEET.
Estatísticas de MEDIA_CREATIVE
Os endpoints de analytics da X Ads API agora fornecem metrics para entidades Media Creative. Media Creatives são a forma como anúncios in-stream ou imagens na X Audience Platform são promovidos. A X Ads UI exibe as metrics de Media Creative nas abas “In-stream videos” e “Display creatives”. Tanto os endpoints de analytics síncronos quanto assíncronos agora oferecem suporte ao enum de entidade MEDIA_CREATIVE.
Buscar múltiplos cards
Aprimorando o lançamento v3 do endpoint projetado para recuperar um único card pelo seu valor de card URI, agora é possível buscar múltiplos cards usando o endpoint GET accounts/:account_id/cards/all. Agora, em vez de fazer uma solicitação para cada card, você pode recuperar até 200 cards em uma única solicitação.
Duas observações:
- O caminho da URL agora é
accounts/:account_id/cards/all. (O caminho anterior não está mais disponível.) Isso é para mantermos consistência com o endpoint projetado para recuperar um card por ID. - O parâmetro obrigatório da solicitação agora se chama card_uris (plural).
- GET accounts/:account_id/line_item_apps
- GET accounts/:account_id/media_creatives
- GET accounts/:account_id/promoted_accounts
- GET accounts/:account_id/preroll_call_to_actions
Alterado
draft_only | with_draft | |
Direcionamento por duração de ativação de rede
A X Ads API corrigiu um problema de exibição em que, após adicionar o direcionamento por Duração de Ativação de Rede, o tipo de direcionamento na resposta incluía o sufixo _IN_SEC. Ter uma referência a segundos era confuso, pois a Duração de Ativação de Rede é sempre representada em meses. Essa correção torna a representação consistente e reduz a confusão.
| v4 | v5 |
| :--- | :--- | :--- |
| NETWORK_ACTIVATION_DURATION_IN_SEC | NETWORK_ACTIVATION_DURATION | |
Contagens totais e cursores
No v5, with_total_count e cursor são mutuamente exclusivos. Especificar ambos em uma solicitação retornará o código de erro EXCLUSIVE_PARAMETERS. Antes do v5, with_total_count era ignorado quando cursor era especificado. Essa alteração torna a relação explícita.
Removidos
- Na v4, foi anunciado que o parâmetro de resposta preview_url para cards era sempre null. A etapa final dessa migração é remover preview_url de todas as respostas de cards.
- O atributo de resposta account_id está sendo removido para os seguintes recursos, dado que o ID da conta de anúncios já está presente na URL, assim como em request.params. (É intencional excluir instrumentos de financiamento desta lista, pois os parent IDs devem estar presentes em objetos de resposta, quando possível, e os account IDs são entidades parent dos instrumentos de financiamento.)
- Mídia da conta
- Provedores de eventos de App
- Tags de eventos de App
- Campanhas
- Cards
- Itens de linha
- users promovíveis
- Critérios de segmentação
- Para solicitações GET accounts/:account_id/targeting_criteria, não retornamos mais o field parent_ids, pois ele sempre foi um array vazio.
- Observação: Isso não afeta image e video app download cards.
- Assets
AMPLIFY_VIDEOadicionados à Media Library são automaticamente adicionados como asset de Account Media com o creative typePREROLL. - Imagens com dimensões específicas adicionadas à Media Library são automaticamente adicionadas como assets de Account Media. O creative type (por exemplo,
INTERSTITIAL) depende das dimensões da imagem. (Para dimensões, consulte nossa página de Enumerations.)
v4
Novo
- TON Upload:
- GET accounts/:account_id/tailored_audience_changes
- GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
- POST accounts/:account_id/tailored_audience_changes
- PUT accounts/:account_id/tailored_audiences/global_opt_out
- Real Time Audiences:
- POST tailored_audience_memberships
list_type será removido da solicitação e da resposta em todos os endpoints de Tailored Audiences na versão 4.
Endpoints de Configurações
Agora oferecemos a capacidade para administradores de conta definirem e atualizarem configurações de usuário, de conta e fiscais. As configurações de usuário correspondem às preferências de contato específicas do usuário para uma determinada conta de anúncios. Usando o endpoint PUT accounts/:account_id, os anunciantes agora podem atualizar o nome da conta e o setor da indústria. Por fim, os endpoints de configurações fiscais permitem que anunciantes em países onde é cobrado imposto sobre valor agregado (VAT) atualizem informações como o nome da empresa, o endereço, o VAT ID e se a conta pertence ao anunciante ou a uma agência que anuncia em nome de um anunciante.
Alterações
lookalike_expansion nos endpoints POST accounts/:account_id/line_items e PUT accounts/:accountit/line_items/:line_item_id.
| v3 | v4 |
|---|---|
NARROW | DEFINED |
BALANCED | EXPANDED |
country_code em todos os lugares
Como parte de um esforço maior de consistência na X Ads API, estamos renomeando os parâmetros nos seguintes endpoints de app_country_code para country_code.
- POST accounts/:account_id/cards/image_app_download
- PUT accounts/:account_id/cards/image_app_download/:card_id
- POST accounts/:account_id/cards/video_app_download
- PUT accounts/:account_id/cards/video_app_download/:card_id
preview_url sempre null
Conforme prometido no anúncio da v3, todos os cards existentes agora têm um card_uri. Como resultado, o valor de preview_url será sempre null.
Como lembrete, associe um card a um Tweet usando seu valor card_uri. Veja o exemplo de solicitação a seguir.
$ twurl -X POST -H ads-api.x.com “/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496”
Removidos
-
endpoint de vídeos da v3:
twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos" -
endpoint da Media Library da v4 para vídeos:
twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
as_user_id em visualização de Tweet
O parâmetro as_user_id disponível no endpoint GET accounts/:account_id/tweet/preview/:tweet_id não será mais aceito. A visualização será sempre renderizada como o autor do Tweet.
v3
- A partir de um público de entrada, recuperar as hashtags, @handles e eventos mais relevantes.
- A partir de um público de entrada, recuperar informações demográficas essenciais (como idade, gênero e renda familiar).
- A partir de uma palavra-chave, recuperar a série temporal do volume de Tweets
Outras alterações
- A resposta do endpoint GET insights/keywords/search agora inclui o atributo related_keywords com 30 termos relacionados às palavras-chave de entrada.
- O tamanho máximo do lote de critérios de segmentação agora é 500.
- Os atributos de resposta card_uri e preview_url agora são mutuamente exclusivos. Quando um card tiver um card_uri, o preview_url será null. Quando um card não tiver um card_uri, apenas o preview_url será retornado.
- Todos os cards criados a partir de 2018-01-29 terão um card_uri.
- Até a versão 4, todos os cards existentes terão um card_uri.
- Não é mais possível criar cards com imagens 5:2. Embora os cards existentes baseados em imagem 5:2 ainda funcionem, recomendamos que os parceiros migrem para as proporções de imagem com melhor desempenho, 1,91:1 ou 1:1 (quando compatíveis).
- O endpoint PUT accounts/:account_id/targeting_criteria não está mais disponível. Decidimos fazer essa mudança porque o comportamento de substituição desse endpoint causava confusão para anunciantes e não era consistente com nossos outros endpoints PUT, que atualizam um único recurso por vez. Em vez disso, os parceiros devem usar o endpoint POST batch/accounts/:account_id/targeting_criteria, que oferece maior flexibilidade, incluindo a capacidade de adicionar e remover segmentações em uma única solicitação.
- O atributo de resposta paused não é mais retornado para instrumentos de financiamento. Em vez disso, consulte o atributo de resposta entity_status para determinar se um instrumento de financiamento está pausado. Além disso, como paused e cancelled correspondem ao mesmo valor, cancelled também não é mais retornado na resposta.
- Removemos o parâmetro card_id do endpoint GET accounts/:account_id/tweet/preview.
- Como não é possível recuperar Scheduled Tweets excluídos, o parâmetro with_deleted não é mais compatível.
- O parâmetro draft_only foi removido dos seguintes endpoints, pois essas entidades nunca podem estar em estado de rascunho:
v2
-
total_countagora é um atributo de resposta opcional. Ele só estará disponível sewith_total_countestiver definido comotrue -
Os campos
pausededraft_onlynos objetos de requisição e resposta deline_itemsecampaignsforam substituídos por um único parâmetroentity_status -
O parâmetro
statusfoi renomeado paratextnos endpoints POST accounts/:account_id/tweet e GET accounts/:account_id/tweet/preview -
Os enums
location_typedo endpoint GET targeting_criteria/locations agora estão no plural.COUNTRYagora éCOUNTRIES,REGIONagora éREGIONSe assim por diante. A única exceção é que, na v2,CITYagora éMETROS, para refletir corretamente o fato de que o tipo de localização se refere a Designated Market Areas (DMAs) ou “metros”. -
display_propertiesnos endpoints PUT accounts/:account_id/promoted_tweets. Esse valor também não será mais retornado como parte da resposta - Como resultado do ponto anterior, não é mais possível atualizar (PUT) entidades promoted_tweets
-
O parâmetro
line_item_idno endpoint GET accounts/:account_id/promoted_tweets foi removido - Não será mais possível criar Website Cards 5:2 nos endpoints v2
-
O atributo de resposta
data_typenão é mais retornado
- Cards v2
- Criação e ativação de campanhas/itens de linha em rascunho
- Tweets agendados
- Resumos de jobs assíncronos
- O parâmetro de requisição
card_urideve ser usado em vez de anexar opreview_urlao texto do Tweet ao associar um card a um Tweet - Se o parâmetro
card_urinão for retornado na resposta (durante a etapa de criação do card), use opreview_url - Todos os novos formatos de card estarão disponíveis nativamente na API, aproveitando o parâmetro
card_uri.
- Video Website Cards:
- O valor do parâmetro
entity_statusnos endpoints POST accounts/:account_id/line_items e POST accounts/:account_id/campaigns pode ser definido comoDRAFTpara criar novas campanhas ou itens de linha em rascunho. - Conjunto de parâmetros obrigatórios para um rascunho recém-criado:
| Campanha em rascunho | Item de linha em rascunho |
|---|---|
funding_instrument_id | campaign_id |
name | objective |
start_time | product_type |
placements |
- Itens de linha ou campanhas em rascunho só podem ser convertidos de um
entity_statusdeDRAFTparaPAUSEDouACTIVE. - Para ativar uma campanha inteira (com vários itens de linha), cada item de linha da campanha, bem como a própria campanha, deve ter o
entity_statusdefinido comoACTIVE. - Para alterar o
entity_statusde qualquer campanha ou item de linha, use o endpoint PUT correspondente.
- Tweets agendados consistem nos seguintes novos endpoints
- Tweets agendados:
- Gerenciamento de campanhas:
- Novos Tweets agendados podem ser programados para qualquer data futura.
- Atualmente, não é possível visualizar a prévia de um tweet agendado.
-
Somente Tweets agendados no estado
SCHEDULEDpodem ser editados/excluídos. -
Tweets agendados não são propagados para o Firehose Enterprise nem para qualquer outra API de dados até a data/hora de
scheduled_at.
v1
- Compatibilidade com versões
- O objetivo
CUSTOMnão é mais compatível - Endpoints em lote agora estão disponíveis de forma geral
- Alterações na estimativa de alcance:
- Para fornecer uma melhor estimativa de alcance, o endpoint agora é sensível ao orçamento. Os seguintes parâmetros agora são obrigatórios:
- [novo]
campaign_daily_budget_amount_local_micro currencybidobjective
- [novo]
- O objeto de resposta foi atualizado e agora retorna faixas para os valores de resposta.
infinite_countfoi renomeado parainfinite_bid_countpara evitar confusão quanto à sua finalidade- Além de
counteinfinite_bid_count, esses novos pontos de dados passarão a ser retornados:impressionsengagementsestimated_daily_spend_local_micro
- Alteração de tipo de dados para tailored audiences
- O
data_typede Tailored Audiences foi alterado detailored_audiencesparatailored_audienceem todas as nossas respostas. - As Audiências Personalizadas Compartilhadas agora estão disponíveis como beta exclusivo via API. As audiências personalizadas compartilhadas permitem que uma única audiência seja usada em várias contas de anúncios. Use o endpoint POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions (e relacionados) para gerenciar as permissões de uma audiência personalizada que você deseja compartilhar entre contas de anúncios.
- Melhorias significativas na forma de coletar métricas de desempenho para contas de anunciantes:
- Para alinhar com nossas melhores práticas, passaremos a permitir a extração de dados apenas para períodos de até 7 dias nos endpoints de estatísticas síncronas.
- Para simplificar a coleta de metrics, substituímos o parâmetro
metricspor um novo parâmetrometric_groups. Os desenvolvedores devem simplesmente especificar quais grupos de metrics desejam receber em uma determinada solicitação.- Qualquer solicitação de metrics que não sejam apropriadas para uma determinada entidade será excluída da resposta e representada como valores
null. Essas metrics não serão contabilizadas no seu limite de custos de analytics.
- Qualquer solicitação de metrics que não sejam apropriadas para uma determinada entidade será excluída da resposta e representada como valores
- A resposta foi significativamente simplificada e agora estará mais alinhada à forma como as metrics são expostas na nossa interface.
- Anteriormente, expúnhamos uma métrica separada para cada local de veiculação (Promoted Tweets em Search, Promoted Tweets em Timelines, Promoted Tweets em Profiles & Tweet Details, X Audience Platform). Agora retornaremos um conjunto padronizado de métricas para cada um (em vez de
promoted_tweet_timeline_impressions,promoted_tweet_search_impressions,promoted_tweets_profile_impressions,promoted_tweets_tpn_impressions), que serão expostas, quando solicitadas em uma das seguintes categorias, como uma única métrica,impressions(isso se aplica a todas as métricas): ALL_ON_TWITTERPUBLISHER_NETWORK- Ao fazer uma solicitação, você receberá uma única métrica
impressions, para facilitar a correspondência de valores na nossa interface. - Você deve fazer duas consultas para obter os dados de
ALL_ON_TWITTERePUBLISHER_NETWORK, pois eles não podem ser combinados.
- Anteriormente, expúnhamos uma métrica separada para cada local de veiculação (Promoted Tweets em Search, Promoted Tweets em Timelines, Promoted Tweets em Profiles & Tweet Details, X Audience Platform). Agora retornaremos um conjunto padronizado de métricas para cada um (em vez de
- Endpoints assíncronos de estatísticas agora estão disponíveis, com base no feedback dos nossos desenvolvedores!
- Um novo conjunto de endpoints para solicitar estatísticas de forma assíncrona, para dados de que você não precisa imediatamente ou para extrações de dados históricos.
- Enfileire um job de estatísticas usando um único novo endpoint. Buscaremos os dados que você solicitou à medida que os recursos permitirem.
- Você pode consultar um endpoint de status do job para verificar se os dados estão disponíveis.
- Quando os dados estiverem disponíveis, forneceremos um id de coleta para você baixar a resposta JSON, que espelhará a resposta do endpoint síncrono.
- Consulte até 90 dias de dados em até 20 entidades em um único job.
- Dê uma olhada em nosso guia de migração para o analytics v1, que inclui o mapeamento de metrics da v0 para as metrics da v1
- Melhorias no Sandbox * Agora você pode criar várias contas de anúncios de teste no ambiente Sandbox. * Agora você pode criar vários instrumentos de financiamento para uma conta de anúncios de teste apenas no ambiente Sandbox. Isso permite testar todos os nossos tipos de instrumentos de financiamento. Antes, apenas a fonte de financiamento
CREDIT_CARDestava disponível para testes. * Quer testar um recurso beta? Agora você pode ativar ou desativar recursos para uma conta no ambiente Sandbox, conforme necessário para seus testes.