Marketing API

Versionierung

Die aktuelle Version der Marketing API ist v21.0.

Facebooks Plattform verfügt über die Versionierungsmodelle „Core“ und „Extended“. Mit der Versionierung der Marketing API werden alle wichtigen Änderungen in einer neuen Version eingeführt. Mehrere Versionen von Marketing APIs oder SDKs können gleichzeitig existieren, wobei jede Version über andere Funktionen verfügt.

Entwickler sollten im Voraus wissen, wann eine Änderung für die Marketing API oder das SDK vorgenommen wird. Du hast zwar 90 Tage Zeit, um die Änderungen umzusetzen, kannst aber selbst entscheiden, wie und wann du zur neuen Version wechseln möchtest.

Versionszeitpläne

Wenn eine neue Version der Marketing API veröffentlicht wird, unterstützen wir die vorherige Version weiterhin für mindestens 90 Tage. Somit hast du eine Frist von mindestens 90 Tagen, um zur neuen Version zu wechseln. Während der 90-tägigen Frist kannst du beide Versionen der API aufrufen (die aktuelle Version und die veraltete Version), und du hast 90 Tage Zeit, um zur neuen Version zu wechseln. Nach Ablauf dieser 90-tägigen Frist funktioniert die veraltete Version nicht mehr. Wenn eine Version nicht mehr verfügbar ist, können alle Aufrufe an diese Versionsnummer fehlschlagen oder mit einem Upgrade auf die nächste verfügbare Version aktualisiert werden.

Beispiel: Version v17.0 der Marketing API wurde am 23. Mai 2023 veröffentlicht und Version v16.0 ist am 6. Februar 2024 abgelaufen. Somit blieb für den Umstieg auf die neue Version eine Frist von mindestens 90 Tagen.

Hier ein Beispiel für einen Zeitplan. Beachte, dass wir nicht immer eine neue Version veröffentlichen, wenn die Frist von 90 Tagen für die Veraltung der Vorversion abgelaufen ist. Im folgenden Beispiel war v16.0 bereits einige Zeit veraltet, bevor v18.0 veröffentlicht wurde:

Bei SDKs bleibt eine Version immer verfügbar, da es sich um herunterladbare Pakete handelt. Nach dem Ende ihrer Lebensdauer nutzt ein SDK jedoch möglicherweise Marketing APIs oder Methoden, die nicht mehr funktionieren. Du solltest also davon ausgehen, dass ein SDK nach dem Ende seiner Lebensdauer nicht mehr funktioniert.

Stellen von versionierten Anfragen

Alle Marketing API-Endpunkte sind über einen versionierten Pfad verfügbar. Stelle dazu einfach die Versions vor den Anfang des Anfragepfads. Beispiel:

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

Das funktioniert in dieser allgemeinen Form für alle Versionen:

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

wobei n für die gewünschte Version steht. Eine vollständige Liste der verfügbaren Versionen findest du in unserem Änderungsprotokoll. Alle unsere Marketing API-Referenzen liefern versionsbezogene Informationen.

Migrationen

Migrationen sind nur für bestimmte Szenarien vorgesehen, in denen Änderungen vorgenommen werden müssen, die nicht in die Versionierung einfließen können. Dies ist meistens der Fall, wenn das zugrunde liegende Datenmodell geändert wurde. Migrationen gelten für alle Versionen.

Derzeit laufende Migrationen werden auf unserer Migrationsseite aufgelistet. Bei Migrationen gilt ein Zeitfenster von mindestens 90 Tagen, in dem du deine App migrieren musst. Nach Beginn des Zeitfensters wird das Verhalten nach der Migration zum Standard für neue Apps. Nach dem Ende des Migrationsfensters ist das Verhalten vor der Migration nicht mehr verfügbar.

Verwalten von Migrationen über die Graph API

Du kannst Migrationen über das Migrationsfeld im Node /app verwalten:

Mit einem Update-Aufruf an die Edge kannst du Migrationen aktivieren oder deaktivieren.

Verwalten von Migrationen über das App-Dashboard

Du kannst verfügbare Migrationen im App-Dashboard unter Einstellungen > Migrationen aktivieren oder deaktivieren. Beachte, dass sich die Liste der Migrationen möglicherweise vom folgenden Bild unterscheidet. Die verfügbaren Migrationen sind bei verschiedenen Apps zu verschiedenen Zeitpunkten unterschiedlich. Wenn du eine Migration Use Graph API v2.0 by default siehst, gilt sie nur für die Graph API, nicht für die Marketing API.

Temporäre clientseitige Aktivierung von Migrationen

Anstatt die Migration im App-Dashboard oder über die Marketing API zu aktivieren, kannst du deinen Marketing API-Aufrufen auch ein spezielles Flag hinzufügen, das die Migration festlegt. Dieses Flag heißt migrations_override. Du musst dafür einen JSON-Blob angeben, der beschreibt, welche Migrationen du aktivieren bzw. deaktivieren möchtest. Wenn du z. B. einen Rohaufruf tätigst, kannst du Folgendes übergeben:

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

Damit kannst du durch Client-Updates die neue Marketing API aufrufen, ohne dass alle Aufrufer*innen gleichzeitig ein Update durchführen müssen, um die neue Marketing API aufzurufen. Dies ist auch für das Debugging sehr nützlich.

Die Namen dieser Migrationen findest du im oben erwähnten Node /app.

Automatisches Versionsupgrade

Angesichts der schnellen Rotation der Marketing API-Versionen, die etwa alle vier Monate stattfindet, sind wir dabei, den Upgradeprozess zu optimieren. Ab Mai 2024 wird die Funktion zum automatischen Versionsupgrade für Marketing API-Endpunkte aktiviert, die zwischen Versionen nicht betroffen sind. Dies bedeutet Folgendes: Wenn ein Endpunkt zwischen einer Version, die als veraltet markiert werden soll, und der nächsten verfügbaren Version nicht betroffen ist, führt die Plattform ein Upgrade des Aufrufs auf die nächste verfügbare Version durch, anstatt die Anfrage direkt fehlschlagen zu lassen. Diese Änderung soll für ein reibungsloseres und effizienteres API-Nutzungserlebnis sorgen.

Beispielsweise ist Version v17.0 ab dem 14. Mai 2024 veraltet. Gemäß dem Änderungsprotokoll von v18.0 sind die folgenden Endpunkte hiervon betroffen:

  • 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

Wenn deine App POST /{adset-id} mit v17.0 aufruft, nachdem diese Version am 14. Mai 2024 als veraltet markiert wurde, schlägt diese API-Anfrage fehlt, da das automatische Upgrade nicht auf Endpunkte angewendet wird, die von der nächsten verfügbaren Version (v18.0) betroffen sind.

Wenn deine App GET /{ad-account-id}/insights mit v17.0 nach der Veraltung aufruft, führt die Plattform ein Upgrade des Aufrufs auf die nächste verfügbare Version (v18.0) durch.

Hinweis: Wenn deine App bereits Aufrufe mit höheren Versionen als v17.0 tätigt, sollte sich am Datum der Versionsveraltung nichts ändern.

Welche Endpunkte in den einzelnen Versionen betroffen sind, kannst du dem Änderungsprotokoll der Marketing API entnehmen.

FAQ

Versionszeitpläne

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

Stellen von versionierten Anfragen

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

Automatisches Versionsupgrade

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