Version 2.11

Marketing API

Veröffentlicht 7. November 2017 | Blogeintrag

• Neue Funktionen
• Funktionsgefährdende Änderungen
• Veraltete Elemente
• Sofort veraltete Elemente

Neue Funktionen

Neues Design der Business Manager API

Wir bieten jetzt eine neue Beziehung an, die Kunden und Agenturen repräsentiert. Außerdem führen wir user neu ein. Bisher haben wir den Zugriff auf und Einladungen zu einem Unternehmen und seinen Elementen über bid/userpermissions gehandhabt, was zu Performance-Problemen führte. Einige wichtige Änderungen in der neuen API:

• Unternehmensbezogene Nutzer: Der neue Nutzer ist mit einem bestimmten Unternehmen verknüpft und hat Berechtigungen, die sich auf dieses Unternehmen beziehen. Nutzer können ihr Profil und ihre Berechtigungen verwalten und auf Elemente zugreifen, die mit diesem Unternehmen verknüpft sind.
• Einladungen: Neue Endpunkte, über die du Personen zum Zugriff auf ein Unternehmen einladen kannst. Du kannst mit diesen Endpunkten den Status von Einladungen überprüfen und aktualisieren.
• Elementkategorien: Du kannst jetzt Elemente verschiedener Arten in Kategorien aufteilen und für jede Kategorie eigene Endpunkte bereitstellen. So lassen sich die Ergebnisse beim Lesen von Elementen besser paginieren. Außerdem kommt es zu weniger Performance-Problemen, wenn du für dein Unternehmen Tausende Elemente verwaltest. Wir haben für das neue Design mehrere neue Endpunkte hinzugefügt.

So greifst du auf Nutzer im Unternehmen zu:

• BUSINESS_ID/business_users
• BUSINESS_ID/system_users
• BUSINESS_ID/pending_users

So greifst du auf Elemente zu, die Nutzern zugewiesen sind:

• BUSINESS_USER_ID/assigned_pages
• BUSINESS_USER_ID/assigned_ad_accounts
• BUSINESS_USER_ID/assigned_product_catalogs
• SYSTEM_USER_ID/assigned_pages
• SYSTEM_USER_ID/assigned_ad_accounts
• SYSTEM_USER_ID/assigned_product_catalogs
• PENDING_USER_ID/assigned_pages
• PENDING_USER_ID/assigned_ad_accounts
• PENDING_USER_ID/assigned_product_catalogs

So greifst du auf Unternehmensseiten zu:

• BUSINESS_ID/owned_pages – um eine Liste der Seiten aufzurufen, die dem Unternehmen gehören
• BUSINESS_ID/client_pages – um eine Liste der Seiten aufzurufen, die Kunden des Unternehmens gehören
• BUSINESS_ID/pending_owned_pages – um eine Liste der Seiten aufzurufen, die dem Unternehmen gehören und deren Genehmigung aussteht
• BUSINESS_ID/pending_client_pages – um eine Liste der Seiten aufzurufen, die Kunden des Unternehmens gehören und deren Genehmigung aussteht

So greifst du auf Werbekonten eines Unternehmens zu:

• BUSINESS_ID/owned_ad_accounts – um eine Liste der Werbekonten aufzurufen, die dem Unternehmen gehören
• BUSINESS_ID/client_ad_accounts – um eine Liste der Werbekonten aufzurufen, die Kunden des Unternehmens gehören
• BUSINESS_ID/pending_owned_ad_accounts – um eine Liste der Werbekonten aufzurufen, die dem Unternehmen gehören und deren Genehmigung aussteht
• BUSINESS_ID/pending_client_ad_accounts – um eine Liste der Werbekonten aufzurufen, die Kunden des Unternehmens gehören und deren Genehmigung aussteht

So greifst du auf Produktkataloge eines Unternehmens zu:

• BUSINESS_ID/owned_product_catalogs – um eine Liste der Produktkataloge aufzurufen, die dem Unternehmen gehören
• BUSINESS_ID/client_product_catalogs – um eine Liste der Produktkataloge aufzurufen, die Kunden des Unternehmens gehören

So greifst du auf Apps eines Unternehmens zu:

• BUSINESS_ID/owned_apps – um eine Liste der Apps aufzurufen, die dem Unternehmen gehören
• BUSINESS_ID/client_apps – um eine Liste der Apps aufzurufen, die Kunden des Unternehmens gehören
• BUSINESS_ID/pending_client_apps – um eine Liste der Apps aufzurufen, die Kunden des Unternehmens gehören und deren Genehmigung aussteht

Weitere Informationen findest du unter Business Manager, API, Business Manager, Systemnutzer, Business Asset Management API und Business Manager API, Best Practices.

Carousel Ads, Echtzeitstandort

Du kannst jetzt eine Carousel Ad mit einem Anhang erstellen, der einen Ort in Echtzeit zeigt. Die Optionen type=REALTIME und location_source_id = PAGE_ID wurden in place_data für AD_CREATIVE_ID/object_story_spec hinzugefügt. Diese Funktion ist im Feld object_story_spec verfügbar für:

• POST /AD_ACCOUNT_ID/adcreatives
• GET CREATIVE_ID

Besuche im Geschäft, geografische Standorte ansprechen

Du kannst jetzt andere geografische Bereiche als einen Umkreis um den Standort eines Geschäfts ansprechen. Wir haben den Parameter geo_locations im targeting_specs-Feld hinzugefügt, wenn du eine Anzeigengruppe mit dem Ziel „Besuche im Geschäft“ erstellst. Begrenzte Verfügbarkeit. Wende dich an deinen Facebook-Ansprechpartner, um Zugriff zu erhalten. Siehe das Ziel „Besuche im Geschäft“

• POST AD_ACCOUNT_ID/adsets verfügt über die neue Option.
• Unterstützt alle geografischen Bereiche in Targeting-Spezifikationen, Standorte außer Targeting nach country_groups und Targeting der Standortart travel_in.
• Das Erstellen von Anzeigen mit dem Ziel STORE_VISITS ist begrenzt verfügbar. Siehe Besuche im Geschäft

Werbeanzeigengruppe, Zielarten

Dies bezieht sich auf die Art des Ziels, auf das eine Anzeige einen Link enthält – in anderen Worten, wohin jemand weitergeleitet wird, wenn er auf eine Anzeige oder den Call to Action in einer Anzeige klickt. So wird eine einheitliche Zielart für alle Anzeigen in einer Anzeigengruppe sichergestellt, sodass sich nur der Inhalt der Anzeige unterscheidet. Siehe Werbeanzeigengruppe, Zielart.

• destination_type für Anzeigengruppen hinzugefügt
• Verfügbar in /ADSET_ID

Key Performance Indicator

Neues Feld kpi_type in AD_ACCOUNT_ID/CAMPAIGN_ID hinzugefügt. Es gibt an, welche Art Key Performance Indicator du für die Kampagne oder die Anzeigenobjekte in der Kampagne erfassen möchtest. Führe die folgenden Aufrufe aus, um Statistikdaten nach kpi_type in kpi_results aufzurufen:

• GET CAMPAIGN_ID/insights
• GET ADSET_ID/insights
• GET AD_ID/insights

Weitere Informationen findest du in Werbekampagne, Referenz.

Funktionsgefährdende Änderungen

Verwaltung von Werbeanzeigen

• Ungültige Anzeigen fürright_hand_column: Werbeanzeigen für diese Position mit ungültigem Inhalt für right_hand_column in AD_ACCOUNT_ID/adsets geben einen Fehler zurück. Für Platzierungen ausschließlich in der right_hand_column sind die Werbeformate Video, Sammlung und Canvas nicht zulässig. Für Platzierungen ausschließlich in der right_hand_column kannst du nur das Einzelbild- und das Karussell-Format verwenden.

• Änderung anGET VERSION/RF_PREDICTION_ID/pause_periods: Gibt jetzt Array anstatt String zurück, um die Verarbeitung zu erleichtern.

Business Manager API

• Felder umbenannt: Das Feld admin_system_user wurde in admin umbenannt, und das Feld system_user wurde in employee umbenannt. Dies wirkt sich auf die folgenden Edges aus:

  • /{business-id}/userpermissions
  • /{business-id}/system_users

Veraltete Elemente

Verwaltung von Werbeanzeigen

Veraltete Optimierungen fürVIDEO_VIEWS: Kampagnen mit dem Ziel VIDEO_VIEWS können die Optimierungsziele CLICKS, IMPRESSIONS, PAGE_ENGAGEMENT, POST_ENGAGEMENT und REACH nicht mehr verwenden.

• Wenn du eine Anzeigengruppe mit einem dieser Optimierungsziele erstellst, erhältst du eine Fehlermeldung.
• Wenn du Anzeigengruppen mit dem Optimierungsziel REACH duplizierst, werden sie automatisch auf das Optimierungsziel VIDEO_VIEWS umgestellt.
• Wenn du Anzeigengruppen mit dem Optimierungsziel CLICKS, IMPRESSIONS, PAGE_ENGAGEMENT oder POST_ENGAGEMENT duplizierst, erhältst du eine Fehlermeldung. Das liegt daran, dass beim Erstellen oder Duplizieren einer Anzeige in einer bestehenden Anzeigengruppe versucht wird, diese Optimierungsziele erneut zu verwenden.

Von dieser Änderung betroffene Edges:

• POST ACCOUNT_ID/adsets
• POST AD_ACCOUNT_ID/ads
• POST CAMPAIGN_ID/copies
• POST ADSET_ID/copies
• POST AD_ID/copies

Veraltung vonreach: Als optimization_goal für das Ziel „Markenbekanntheit“. Entfernt für /adset; nur zur Optimierung der Werbeerinnerung verfügbar. Dies soll Verwirrung vermeiden, wenn jemand versucht, Reichweite als spezielles Ziel zu verwenden.

Veraltung der OptimierungBRAND_AWARENESS: Ersetzt durch AD_RECALL_LIFT. Dies ist ein Teil eines neuen, effizienteren Modells zur Auslieferung von Werbeanzeigen. Das neue Optimierungsziel unterstützt eine Mischung von Inhalten, z. B. Standbilder und Video Ads in derselben Anzeigengruppe, und manuelle Gebote. BRAND_AWARENESS ist nicht mehr verfügbar in:

• POST /ADSET_ID
• GET /ADSET_ID
• POST /AD_ACCOUNT_ID/adsets

Veraltung vonfrequency_cap einschließlich der Felder lifetime_frequency_cap und frequency_cap_reset_period in:

• POST AD_ACCOUNT_ID/adsets
• GET /ADSET_ID
• POST /ADSET_ID

Verwende stattdessen frequency_control_specs.

Veraltung von POST_ENGAGEMENT mit Kosten pro Handlung: du kannst POST_ENGAGEMENT nicht mehr als billing_event für dieses Ziel verwenden. So wird die Auslieferung der Werbeanzeige besser mit der Messung in Einklang gebracht. Dies wirkt sich auf den Endpunkt /AD_SET_ID aus.

Werbestatistiken und Messung

Veraltung vonvideo_15_sec_watched_actions in:

• GET AD_ACCOUNT_ID/insights
• GET CAMPAIGN_ID/insights
• GET ADSET_ID/insights
• GET AD_ID/insights
• POST AD_ACCOUNT_ID/insights
• POST CAMPAIGN_ID/insights
• POST ADSET_ID/insights
• POST AD_ID/insights

Veraltung vonrecurrence_value: Aus der Advanced Measurement API. In der Atlas API wurde dieses Feld auch Berichtszeitplan genannt. Wir haben es durch recurrence_values ersetzt. Siehe Erweiterte Messung, Berichtszeitpläne.

Business Manager

Veraltete Endpunkte in der neu gestalteten Business Manager API:

• BUSINESS_ID/userpermissions
• BUSINESS_ID/business_persona
• business_persona_id

Veraltete Endpunkte für die Verwaltung deiner Elemente:

• BUSINESS_ID/pages
• BUSINESS_ID/adaccounts
• BUSINESS_ID/product_catalogs
• BUSINESS_ID/apps

Verwende BUSINESS_ID/owned_ASSET oder BUSINESS_ID/client_ASSET, um auf Elemente zuzugreifen.

Veraltete Endpunkte für die Verwaltung von Elementen, die einem anderen Unternehmen gehören:

• BUSINESS_ID/assigned_ad_accounts
• BUSINESS_ID/assigned_pages
• BUSINESS_ID/assigned_product_catalogs

Verwende stattdessen BUSINESS_USER_ID/assigned_ASSET.

Sofort veraltete Elemente

Diese Veraltungen betreffen alle API-Versionen und treten am 14. November 2017 in Kraft.

Event Ads und Link Ads

Veraltung des Erstellens und Bearbeitens von Event Ads und Link Ads, die nicht mit einer gültigen Seite verknüpft sind. Das folgende Format ist nicht mehr gültig und gibt einen Fehler zurück.

Veraltete Signaturen:

• Event Ads

  • Ziel: EVENT_RESPONSES
  • Inhaltsfelder: body, object_id
• Link Ads

  • Ziel: LINK_CLICKS
  • Inhaltsfelder: title, body, object_url (image_file oder image_hash)

Unterstützte Signaturen

• Event Ads

  • Ziel: EVENT_RESPONSES
  • Inhaltsfelder: object_story_id oder object_story_spec
• Link Ads

  • Ziel: LINK_CLICKS
  • Inhaltsfelder: object_story_id oder object_story_spec

Bestehende Event Ads oder Link Ads, die du vor der Änderung erstellt hast, laufen weiterhin. Du kannst den Inhalt der Anzeige jedoch nicht verändern und keine neuen Anzeigen erstellen, nachdem die Änderung in Kraft tritt, da ein Fehler auftritt. Siehe Event Ads und Local Ads und Werbeanzeige, Referenz