| Versione | Percorso | Data di introduzione | Data di deprecazione | Data di fine vita |
|---|---|---|---|---|
| 12.0 | /12/ | 27 ottobre 2022 | Da definire | Da definire |
| 11.0 | /11/ | 31 marzo 2022 | Da definire | Da definire |
| 10.0 | /10/ | 31 agosto 2021 | 31 marzo 2022 | 27 ottobre 2022 |
| 9.0 | /9/ | 2 marzo 2021 | 31 agosto 2021 | 31 marzo 2022 |
| 8.0 | /8/ | 8 settembre 2020 | 2 marzo 2021 | 31 agosto 2021 |
| 7.0 | /7/ | 3 marzo 2020 | 1 settembre 2020 | 2 marzo 2021 |
| 6.0 | /6/ | 28 agosto 2019 | 3 marzo 2020 | 1 settembre 2020 |
| 5.0 | /5/ | 28 febbraio 2019 | 28 agosto 2019 | 3 marzo 2020 |
| 4.0 | /4/ | 28 agosto 2018 | 28 febbraio 2019 | 28 agosto 2019 |
| 3.0 | /3/ | 1 febbraio 2018 | 28 agosto 2018 | 28 febbraio 2019 |
| 2.0 | /2/ | 10 luglio 2017 | 1 febbraio 2018 | 1 agosto 2018 |
| 1.0 | /1/ | 31 marzo 2016 | 7 luglio 2017 | 10 gennaio 2018 |
| 0.0 | /0/ | 21 febbraio 2013 | N/D | 31 ottobre 2016 |
Panoramica
- Rimozione di un parametro dalla richiesta/risposta dell’API
- Modifica del nome di qualsiasi parametro o endpoint
- Modifica della rappresentazione dei valori (preview_url → card_uri)
- Modifica del comportamento degli endpoint (ad es., statistiche async vs sync)
- Aggiunta/modifica di parametri opzionali o obbligatori (ad es., rendere name un campo obbligatorio nella richiesta)
Strategia di versioning
- Tutte le modifiche che rompono la compatibilità saranno incluse in una nuova versione
- Il periodo di deprecazione per le versioni esistenti, quando viene annunciata una nuova versione, è di 6 mesi
- In qualsiasi momento, l’API accetterà richieste da due versioni contemporaneamente; tuttavia, la più vecchia delle due non sarà supportata
- Per favorire un’adozione più rapida dei nuovi prodotti, questi verranno rilasciati in modo continuo (al di fuori della cadenza di versioning)
-
Tutte le risposte dell’API conterranno un’intestazione
x-current-api-version, impostata sulla versione corrente dell’API, oltre a un’intestazionex-api-warnquando si chiamano endpoint dell’API deprecati.
v9
Nota: Con questo rilascio, la versione 7 (v7) della Ads API ha raggiunto la fine del ciclo di vita e non è più disponibile.
v8
v7
v6
v5
accounts/:account_id/account_media sono stati dichiarati obsoleti.
Come per le versioni precedenti, è previsto un periodo di transizione di 6 mesi per la migrazione alla v5. Il 2019-08-28, la versione 4 della X Ads API non sarà più disponibile. Invitiamo tutti i partner a migrare alla versione più recente dell’API il prima possibile per evitare interruzioni del servizio. La versione 3 della X Ads API ha raggiunto la fine del ciclo di vita e non è più disponibile.
Novità
CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE e PROMOTED_TWEET.
Statistiche MEDIA_CREATIVE
Gli endpoint di analytics della X Ads API ora forniscono metriche per le entità Media Creative. I Media Creative sono il modo in cui vengono promossi gli annunci in‑stream o le immagini sulla X Audience Platform. L’interfaccia X Ads mostra le metriche dei Media Creative nelle schede “In-stream videos” e “Display creatives”. Gli endpoint di analytics sia sincroni sia asincroni ora supportano l’enum di entità MEDIA_CREATIVE.
Recuperare più card
Rispetto alla versione v3 dell’endpoint progettato per recuperare una singola card in base al suo valore di URI, ora è possibile recuperare più card utilizzando l’endpoint GET accounts/:account_id/cards/all. Invece di effettuare una richiesta per ciascuna card, puoi recuperarne fino a 200 con una singola richiesta.
Due aspetti da notare:
- Il percorso URL è ora
accounts/:account_id/cards/all. (Il percorso precedente non è più disponibile.) Questo per mantenere la coerenza con l’endpoint progettato per recuperare una card tramite ID. - Il parametro di richiesta obbligatorio ora si chiama card_uris (plurale).
- 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
Modifiche
draft_only | with_draft | |
Targeting per la durata di attivazione della rete
La X Ads API ha risolto un problema di visualizzazione per cui, dopo aver aggiunto il targeting Network Activation Duration, il tipo di targeting nella risposta includeva il suffisso _IN_SEC. Il riferimento ai secondi risultava fuorviante, poiché Network Activation Duration è sempre espresso in mesi. Questa correzione rende la rappresentazione coerente e riduce la confusione.
| v4 | v5 |
| :--- | :--- | :--- |
| NETWORK_ACTIVATION_DURATION_IN_SEC | NETWORK_ACTIVATION_DURATION | |
Conteggi totali e cursori
In v5, with_total_count e cursor sono mutuamente esclusivi. Specificare entrambi in una richiesta restituisce il codice di errore EXCLUSIVE_PARAMETERS. Prima della v5, with_total_count veniva ignorato quando era specificato cursor. Questa modifica rende esplicita la relazione.
Rimosso
- In v4 è stato comunicato che il parametro di risposta preview_url per le card era sempre null. Il passo finale di questa migrazione è rimuovere preview_url da tutte le risposte delle card.
- L’attributo di risposta account_id viene rimosso per le seguenti risorse, dato che l’ID dell’account pubblicitario è già presente nell’URL e in request.params. (È intenzionale escludere gli strumenti di finanziamento da questo elenco, poiché, ove possibile, gli ID padre dovrebbero essere presenti negli oggetti di risposta e gli ID account sono entità padre degli strumenti di finanziamento.)
- Account media
- Provider di eventi App
- Tag di eventi App
- Campaigns
- Cards
- Line items
- Promotable users
- Targeting criteria
- Per le richieste GET accounts/:account_id/targeting_criteria non restituiamo più il campo parent_ids, poiché era sempre un array vuoto.
- Nota: questo non influisce sulle image and video app download cards.
- Gli asset
AMPLIFY_VIDEOaggiunti alla Media Library vengono automaticamente aggiunti come asset Account Media con il tipo creativoPREROLL. - Le immagini con dimensioni specifiche aggiunte alla Media Library vengono automaticamente aggiunte come asset Account Media. Il tipo creativo (ad es.
INTERSTITIAL) dipende dalle dimensioni dell’immagine. (Per le dimensioni, consultare la nostra pagina Enumerations.)
v4
Novità
- 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/:accounti_d/tailored_audiences/global_opt_out
- Real Time Audiences:
- POST tailored_audience_memberships
list_type verrà rimosso dalla richiesta e dalla risposta su tutti gli endpoint Tailored Audiences nella versione 4.
Endpoint delle impostazioni
Ora offriamo agli amministratori di account la possibilità di impostare e aggiornare le impostazioni utente, dell’account e fiscali. Le impostazioni utente corrispondono alle preferenze di contatto specifiche dell’utente per un determinato account pubblicitario. Utilizzando l’endpoint PUT accounts/:account_id, gli inserzionisti possono ora aggiornare il nome dell’account e il settore. Infine, gli endpoint delle impostazioni fiscali consentono agli inserzionisti nei paesi in cui è applicata l’imposta sul valore aggiunto (IVA) di aggiornare informazioni come la ragione sociale, l’indirizzo, l’ID IVA e se l’account è di proprietà dell’inserzionista o di un’agenzia che pubblicizza per conto di un inserzionista.
Modifiche
lookalike_expansion sugli endpoint POST accounts/:account_id/line_items e PUT accounts/:account_id/line_items/:line_item_id.
| v3 | v4 |
|---|---|
NARROW | DEFINED |
BALANCED | EXPANDED |
country_code ovunque
Nell’ambito di un’iniziativa più ampia per la coerenza sulla X Ads API, rinominiamo i parametri sui seguenti endpoint da app_country_code a 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
Come annunciato nella v3, tutte le card esistenti ora hanno un card_uri. Di conseguenza, il valore di preview_url sarà sempre null.
Promemoria: associa una card a un Tweet usando il valore card_uri. Vedi la seguente richiesta di esempio.
$ twurl -X POST -H ads-api.x.com “/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496”
Rimosso
-
endpoint video v3:
twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos" -
endpoint media library v4 per i video:
twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
as_user_id in Tweet View
Il parametro as_user_id disponibile sull’endpoint GET accounts/:account_id/tweet/preview/:tweet_id non sarà più accettato. L’anteprima verrà sempre resa come autore del Tweet.
v3
- Dato un pubblico di input, recupera gli hashtag, gli @handle e gli eventi più rilevanti.
- Dato un pubblico di input, recupera informazioni demografiche chiave (come età, genere e reddito familiare).
- Data una parola chiave, recupera la serie temporale del volume di Tweet.
Altre modifiche
- La risposta dell’endpoint GET insights/keywords/search ora include l’attributo related_keywords con 30 termini correlati alle keyword di input.
- La dimensione massima del batch per i criteri di targeting è ora 500.
- Gli attributi di risposta card_uri e preview_url sono ora mutuamente esclusivi. Quando una card ha un card_uri, preview_url sarà null. Quando una card non ha un card_uri, verrà restituito solo preview_url.
- Tutte le card create a partire dal 2018-01-29 avranno un card_uri.
- Entro la versione 4, tutte le card esistenti avranno un card_uri.
- Non è più possibile creare card con immagini 5:2. Sebbene le card esistenti basate su immagini 5:2 continueranno a funzionare, invitiamo i partner a passare ai rapporti d’aspetto con prestazioni migliori 1,91:1 o 1:1 (dove supportati)
- L’endpoint PUT accounts/:account_id/targeting_criteria non è più disponibile. Abbiamo deciso di apportare questa modifica perché il comportamento di sostituzione di questo endpoint causava confusione agli inserzionisti e non era coerente con gli altri endpoint PUT che aggiornano una singola risorsa alla volta. Invece, i partner dovrebbero usare l’endpoint POST batch/accounts/:account_id/targeting_criteria, che offre maggiore flessibilità, inclusa la possibilità di aggiungere e rimuovere il targeting in un’unica richiesta.
- L’attributo di risposta paused non è più restituito per gli strumenti di finanziamento. In alternativa, fare riferimento all’attributo di risposta entity_status per stabilire se uno strumento di finanziamento è in pausa. Inoltre, poiché paused e cancelled corrispondono allo stesso valore, anche cancelled non è più restituito nella risposta.
- Abbiamo rimosso il parametro card_id dall’endpoint GET accounts/:account_id/tweet/preview.
- Poiché non è possibile recuperare i Scheduled Tweets eliminati, il parametro with_deleted non è più supportato.
- Il parametro draft_only è stato rimosso dai seguenti endpoint poiché queste entità non possono mai essere in stato di bozza:
v2
-
total_countè ora un attributo di risposta facoltativo. Sarà disponibile solo sewith_total_countè impostato sutrue -
I campi
pausededraft_onlysugli oggetti di richiesta e rispostaline_itemsecampaignssono sostituiti da un unico parametroentity_status -
Il parametro
statusè stato rinominato intextsugli endpoint POST accounts/:account_id/tweet e GET accounts/:account_id/tweet/preview -
Gli enum
location_typedell’endpoint GET targeting_criteria/locations sono ora al plurale.COUNTRYè oraCOUNTRIES,REGIONè oraREGIONSe così via. Un’eccezione: in v2,CITYè oraMETROS, per riflettere correttamente il fatto che il tipo di località si riferisce alle Designated Market Areas (DMA) o “metropolitane”. -
display_propertiessui PUT accounts/:account_id/promoted_tweets. Questo valore non verrà più restituito come parte della risposta - Come risultato del punto precedente, non è più possibile aggiornare (PUT) le entità promoted_tweets
-
Il parametro
line_item_idsull’endpoint GET accounts/:account_id/promoted_tweets è stato rimosso - Non sarà più possibile creare Website Card 5:2 sugli endpoint v2
-
L’attributo di risposta
data_typenon viene più restituito
- Cards v2
- Creazione e attivazione di campagne/line item in bozza
- Tweet pianificati
- Riepiloghi dei job asincroni
- Il parametro di richiesta
card_uriva utilizzato invece di aggiungere ilpreview_urlal testo del Tweet quando si associa una card a un Tweet - Se il parametro
card_urinon viene restituito nella risposta (durante la creazione della card), utilizzare allora ilpreview_url - Tutti i nuovi formati di card saranno nativamente disponibili tramite l’API, sfruttando il parametro
card_uri.
- Video Website Cards:
- Il valore del parametro
entity_statussugli endpoint POST accounts/:account_id/line_items e POST accounts/:account_id/campaigns può essere impostato suDRAFTper creare nuove campagne o line item in bozza. - Il set di parametri obbligatori per una bozza appena creata:
| Campagna in bozza | Line item in bozza |
|---|---|
funding_instrument_id | campaign_id |
name | objective |
start_time | product_type |
placements |
- I line item o le campagne in bozza possono essere convertiti solo da un
entity_statusdiDRAFTaPAUSEDoACTIVE. - Per attivare un’intera campagna (con più line item), ogni line item della campagna, così come la campagna stessa, deve avere
entity_statusimpostato suACTIVE. - Per modificare l’
entity_statusdi qualsiasi campagna o line item, utilizzare il corrispondente endpoint PUT.
- I Tweet programmati includono i seguenti nuovi endpoint
- Tweet programmati:
- Gestione campagne:
- I nuovi Tweet programmati possono essere impostati per qualsiasi data futura
- Attualmente non è possibile visualizzare in anteprima un Tweet programmato
-
Solo i Tweet programmati nello stato
SCHEDULEDpossono essere modificati/eliminati -
I Tweet programmati non vengono propagati alla Firehose Enterprise né ad alcuna altra API di data fino alla data/ora
scheduled_at.
v1
- Supporto per il controllo delle versioni
- L’obiettivo
CUSTOMnon è più supportato - Gli endpoint batch sono ora disponibili in generale
- Modifiche alla stima della copertura:
- Per fornire una stima della copertura più accurata, l’endpoint è ora sensibile al budget. I seguenti parametri sono ora obbligatori:
- [nuovo]
campaign_daily_budget_amount_local_micro currencybidobjective
- [nuovo]
- L’oggetto della risposta è cambiato e ora restituisce intervalli per i valori della risposta.
infinite_countè stato rinominatoinfinite_bid_countper evitare ambiguità sulla sua finalità- Oltre a
counteinfinite_bid_count, ora verranno restituiti anche questi nuovi punti di dati:impressionsengagementsestimated_daily_spend_local_micro
- Modifica del tipo di dati per le audience personalizzate
- Il
data_typeper Tailored Audiences è stato modificato datailored_audiencesatailored_audiencein tutte le nostre risposte. - Le Shared Tailored Audiences sono ora disponibili come beta solo tramite API. Le Shared Tailored Audiences consentono di utilizzare un’unica audience su più account pubblicitari. Usa l’endpoint POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions (e quelli correlati) per gestire le autorizzazioni di una tailored audience che desideri condividere tra account pubblicitari.
- Miglioramenti significativi nel modo in cui raccogli le analitiche sulle prestazioni degli account inserzionista:
- Per allinearci alle nostre best practices, da ora consentiremo di estrarre i dati per un massimo di 7 giorni tramite gli endpoint di statistiche sincroni.
- Per semplificare il recupero delle metriche, abbiamo sostituito il parametro
metricscon il nuovo parametrometric_groups. Gli sviluppatori devono semplicemente indicare quali gruppi di metriche desiderano ricevere per una determinata richiesta.- Qualsiasi richiesta di metriche non appropriate per una determinata entità sarà esclusa dalla risposta e rappresentata come valori
null. Queste metriche non verranno conteggiate nel limite dei costi di analytics.
- Qualsiasi richiesta di metriche non appropriate per una determinata entità sarà esclusa dalla risposta e rappresentata come valori
- La risposta è stata notevolmente semplificata e ora sarà più in linea con il modo in cui le metriche sono presentate nella nostra UI.
- In precedenza esponevamo una metrica separata per ciascuna posizione di posizionamento (Promoted Tweets in Search, Promoted Tweets in Timelines, Promoted Tweets in Profiles & Tweet Details, X Audience Platform). Ora restituiremo un set standardizzato di metriche per ciascuna: invece di
promoted_tweet_timeline_impressions,promoted_tweet_search_impressions,promoted_tweets_profile_impressions,promoted_tweets_tpn_impressions, saranno ora esposte, quando richieste, in una delle seguenti categorie come un’unica metrica,impressions(questo vale per tutte le metriche): ALL_ON_TWITTERPUBLISHER_NETWORK- Quando effettui una richiesta, riceverai un’unica metrica
impressionsper facilitare la corrispondenza dei valori nella nostra UI. - Devi effettuare due query per ottenere sia i dati
ALL_ON_TWITTERsiaPUBLISHER_NETWORK, poiché non possono essere combinati.
- In precedenza esponevamo una metrica separata per ciascuna posizione di posizionamento (Promoted Tweets in Search, Promoted Tweets in Timelines, Promoted Tweets in Profiles & Tweet Details, X Audience Platform). Ora restituiremo un set standardizzato di metriche per ciascuna: invece di
- Gli endpoint per le statistiche asincrone sono ora disponibili, in risposta al feedback dei nostri sviluppatori!
- Un nuovo set di endpoint per richiedere statistiche in modo asincrono, per dati di cui non avete bisogno immediatamente o per estrazioni storiche.
- Mettete in coda un job di statistiche utilizzando un nuovo endpoint unico. Recupereremo i dati richiesti in base alle risorse disponibili.
- Potete interrogare un endpoint dello stato del job per verificare se i dati sono disponibili.
- Quando i dati saranno disponibili, vi forniremo un id di ritiro per scaricare la risposta JSON, che rispecchierà la risposta dell’endpoint sincrono.
- Interrogate fino a 90 giorni di dati su un massimo di 20 entità in un singolo job.
- Dai un’occhiata alla nostra guida alla migrazione di analytics v1, che include la corrispondenza tra le metriche v0 e le metriche v1
- Miglioramenti del Sandbox * Ora puoi creare più account pubblicitari di test nell’ambiente Sandbox. * Ora puoi creare più strumenti di pagamento per un account pubblicitario di test, ma solo nell’ambiente Sandbox. Questo ti consente di testare tutti i nostri tipi di strumenti di pagamento. In precedenza, per i test era disponibile solo la fonte di pagamento
CREDIT_CARD. * Vuoi provare una funzionalità beta? Ora puoi attivare o disattivare le funzionalità per un account nell’ambiente Sandbox in base alle tue esigenze di test.