API Marketing

Gestione delle versioni

La versione corrente dell'API Marketing è v21.0.

La piattaforma di Facebook ha un modello di gestione delle versioni core ed esteso. Grazie alla gestione delle versioni dell'API Marketing, tutte le modifiche sostanziali verranno implementate in una nuova versione. Possono coesistere contemporaneamente più versioni di API Marketing o SDK, ciascuna con diverse funzionalità.

Gli sviluppatori dovrebbero comprendere in anticipo quando un SDK o l'API Marketing cambieranno. Sebbene tu abbia una finestra di 90 giorni per l'adozione delle modifiche, puoi scegliere liberamente come e quando passare alla nuova versione.

Programmazioni della versione

Al rilascio di una nuova versione dell'API Marketing, continueremo a supportare la versione precedente per almeno 90 giorni, periodo di tolleranza durante il quale potrai passare alla nuova versione. Durante il periodo di tolleranza di 90 giorni potrai chiamare entrambe le versioni e avrai modo di passare alla nuova versione. Al termine del periodo di tolleranza di 90 giorni, la versione obsoleta cesserà di funzionare. Una volta che una versione non è più disponibile, qualsiasi chiamata effettuata a quel numero di versione può avere esito negativo o essere passata alla successiva versione disponibile.

Ad esempio, la versione dell'API Marketing v17.0 è stata rilasciata il 23 maggio 2023 e la versione dell'API Marketing v16.0 ha scadenza il 6 febbraio 2024, con un intervallo di tempo di almeno 90 giorni durante il quale passare alla nuova versione.

Ecco un esempio di timeline. Tieni presente che non sempre viene rilasciata una nuova versione al termine del periodo di tolleranza di 90 giorni dell'eliminazione della versione precedente. Nell'esempio, l'eliminazione della v16.0 era prevista qualche tempo prima che venisse rilasciata la v18.0:

Per gli SDK, una versione resta sempre disponibile essendo un pacchetto scaricabile. Tuttavia, dopo il termine della sua vita, potrebbe usare API Marketing o metodi non più funzionanti, pertanto devi considerarla come non più funzionante.

Richieste con versioni

Tutti gli endpoint dell'API Marketing sono disponibili attraverso un percorso con versione. Inserisci la versione all'inizio del percorso della richiesta. Ad esempio:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v21.0/me/adaccounts"

Questa forma generica funziona con tutte le versioni:

https://graph.facebook.com/v{n}/{request-path}

n indica la versione richiesta. Nel registro modifiche è disponibile una lista completa delle versioni disponibili. Tutti i Riferimenti per l'API Marketing riportano informazioni specifiche per versione.

Migrazioni

Le migrazioni sono destinate solo a scenari speciali in cui le modifiche necessarie non possono essere inserite nella gestione delle versioni. Di solito, si tratta di modifiche al modello di dati sottostante. Le migrazioni si applicano a tutte le versioni.

Le migrazioni attualmente in corso sono elencate nella nostra pagina delle migrazioni. Le migrazioni presentano una finestra di almeno 90 giorni per la migrazione della tua app. Una volta iniziata la finestra, il comportamento post-migrazione diventerà predefinito per le nuove app. Al termine della finestra di migrazione, il comportamento pre-migrazione non sarà più disponibile.

Gestione delle migrazioni attraverso l'API Graph

Le migrazioni possono essere gestite tramite il campo migrazioni nel nodo /app:

Puoi effettuare una chiamata di aggiornamento nel segmento per attivare e disattivare le migrazioni.

Gestione delle migrazioni attraverso la Dashboard gestione app

Puoi attivare e disattivare le migrazioni disponibili nella Dashboard gestione app, in Impostazioni > Migrazioni. Tieni presente che la lista delle migrazioni potrebbe differire dall'immagine qui sotto poiché le migrazioni disponibili sono diverse per le varie app, in momenti diversi. Le migrazioni Use Graph API v2.0 by default si riferiscono solo all'API Graph e non all'API Marketing.

Attivazione lato client temporanea delle migrazioni

Anziché attivare la migrazione nella Dashboard gestione app o attraverso l'API Marketing, è possibile aggiungere un flag speciale alla chiamate API Marketing per l'impostazione della migrazione. Il flag è migrations_override e richiede di specificare un blob JSON che descriva le migrazioni che desideri attivare o disattivare. Ad esempio, per effettuare una chiamata non elaborata puoi passare:

http://graph.facebook.com/path?
  migrations_override={"migration1":true, "migration2":false}

In questo modo, puoi chiamare la nuova API Marketing attraverso gli aggiornamenti del client anziché aggiornare tutti gli elementi che effettuano una chiamata per fare in modo che chiamino contemporaneamente l'API Marketing. Ciò si rivela molto utile per l'esecuzione del debug.

I nomi di queste migrazioni sono riportati nel nodo /app menzionato sopra.

Upgrade automatico della versione

Data la rapida rotazione delle versioni dell'API Marketing circa ogni quattro mesi, stiamo semplificando il processo di upgrade. A partire da maggio 2024, abiliteremo la funzione di upgrade di versione automatico per gli endpoint dell'API Marketing non interessati tra una versione e l'altra. Questo significa che tra una versione da disattivare e la successiva versione disponibile, se un endpoint non è interessato, la piattaforma eseguirà un upgrade della chiamata alla versione successiva disponibile piuttosto che respingere direttamente la richiesta. Questa modifica è progettata per garantire un'esperienza API più fluida ed efficiente.

Ad esempio, la v17.0 diventerà obsoleta il 14 maggio 2024. Secondo il registro delle modifiche della v18.0, saranno interessati i seguenti endpoint:

  • POST /act_{ad-account-id}/reachfrequencypredictions
  • GET /act_{ad-account-id}/reachestimate
  • GET /act_{ad-account-id}/delivery_estimate
  • POST /act_{ad-account-id}/adsets
  • POST /{adset-id}
  • POST /act_{ad-account-id}/saved_audiences
  • POST /{saved-audience-id}
  • POST /act_{ad-account-id}/credit_cards

Se la tua app effettua una chiamata POST /{adset-id} con la v17.0 dopo la disattivazione del 14 maggio 2024, la richiesta API non andrà a buon fine in quanto l'upgrade automatico non si applica agli endpoint interessati dalla successiva versione disponibile (v18.0).

Se la tua app effettua una chiamata GET /{ad-account-id}/insights con la v17.0 dopo la disattivazione, la piattaforma effettuerà l'upgrade della chiamata alla successiva versione disponibile v18.0.

Nota: se la tua app ha giù iniziato a effettuare chiamate con versioni successive alla v17.0, non dovrebbero esserci cambiamenti alla data di disattivazione della versione.

Per controllare gli endpoint interessati per ogni versione, consulta il Registro modifiche dell'API Marketing.

FAQ

Programmazioni della versione

We refer to this as an unversioned call. Unversioned calls are invalid and will fail when made against Marketing API endpoints.

Permalink

You can call the version of the Marketing API that was the latest available when the app was created, as long as it has not been deprecated. It can also make calls to any newer, undeprecated versions launched after the app is created.

Starting May 14, 2024, if a deprecated version is provided, the platform may upgrade selected endpoints to the next available version instead of failing the request. To learn more about the behavior, refer to Marketing API Auto-version upgrade.

For example:

  • If your app was created before the launch of v17.0, while v16.0 was available, then it will be able to make calls to v16.0 until the expiration date of that version. After v16.0 has been deprecated, calls to v16.0 will fail.
  • If your app was created after v17.0 was released, it will be able to make calls to v17.0 until the expiration date of that version, and any subsequent versions (v18.0, etc) until their expiration dates. After v17.0 has been deprecated, calls to v17.0 will fail.
  • Your app will not be able to make calls to v16.0, since 1) that was before your app was created and 2) that version is deprecated and calls to v16.0 may fail or be upgraded to the next available version.

If an app was not used - to make any Marketing API calls or requests - after being created, it will not have the ability to use those versions if any newer version is launched. Here's another example to explain this:

  • If your app was created while v16.0 was the latest version available, but not used until after v17.0 had launched, it will only be to use v17.0, and not v16.0.
  • If your app was created while v16.0 was the latest version available, and then used before v17.0 had launched, it will still be able to use v16.0 even after the launch of v17.0.
Permalink

There are a few differences between how Marketing API and the rest of Graph API. For the details on Platform API versioning, see Graph API, Versioning.

  1. Marketing API is versioned on a 90-day deprecation schedule, whereas Platform API has core and extended APIs with a 2 year guarantee for core APIs.
  2. Marketing API does not support unversioned calls. If you do not specify a working version in your call, it fails.
Permalink

Richieste con versioni

With migrations, you set migration on or off in App Dashboard, as described in the Migrations section. With versioning, we are making Marketing API functionality more transparent by moving the setting into the endpoint:

https://graph.facebook.com/v{n}/{request-path}

You can know what behavior to expect out without having to manually visit your app's migration panel.

Permalink

Upgrade automatico della versione

The upgrade will apply on any deprecated version to the next available version. This means hypothetically if your app is making calls to v15.0 after v16.0 is deprecated, the call will also be upgraded to v17.0 if the endpoint is not listed as affected endpoint on both v16.0 and v17.0.

Permalink

No. We highly encourage developers to perform version upgrades before a version gets deprecated for the following reasons

  • You may still need to manually upgrade endpoints being impacted by next version.
  • You might want to upgrade to newer versions to benefit from new features instead of the lowest available version.
Permalink

You can look up affected endpoints from Marketing API Changelog.

Permalink

You can disable the version auto-upgrade via the Marketing API Version setting under Marketing API App Product Page > Settings.

Permalink

If an API call targets a version that has been deprecated and has been automatically upgraded, an API response header is included for any call that has been auto-upgraded.

Example notification header

X-Ad-Api-Version-Warning: 'X-Ad-Api-Version-Warning: 'The call has been auto-upgraded to vXXX as vXXX has been deprecated''
Permalink