Insights API

Insights bietet eine einzelne, durchgängige Oberfläche zum Abrufen von Statistiken für Werbeanzeigen.

• Aufschlüsselungen: Gruppierung von Ergebnissen.
• Aufschlüsselungen von Handlungen: Verstehen der Reaktion auf Aufschlüsselungen von Handlungen.
• Asynchrone Jobs: Verwende asynchrone Jobs für Anfragen mit vielen Ergebnissen.
• Einschränkungen und Best Practices: Einschränkungen für Aufrufe sowie Filter und Best Practices.

Bevor du Daten zur Performance deiner Werbeanzeige abrufen kannst, solltest du deine Werbeanzeigen so einrichten, dass die für dich relevanten Kennzahlen verfolgt werden. Dazu kannst du URL-Tags, Meta-Pixel und die Conversions API verwenden.

Bevor du beginnst

Voraussetzungen:

• Die Berechtigung ads_read
• Eine App. Weitere Informationen findest du unterMeta-App-Entwicklung.

Kampagnenstatistiken

So rufst du die Statistiken über die Performance einer Kampagne in den vergangenen 7 Tagen ab:

curl -G \
  -d "date_preset=last_7d" \
  -d "access_token=ACCESS_TOKEN" \
  "https://graph.facebook.com/API_VERSION/AD_CAMPAIGN_ID/insights"

Weitere Informationen findest du in der Referenz zu Werbeanzeigen-Insights.

Aufrufe tätigen

Die Insights API ist als Edge für jedes beliebige Werbeanzeigenobjekt verfügbar.

Anfrage

Du kannst bestimmte Felder mit einer durch Komma getrennten Liste in den fields-Parametern anfragen. Beispiel:

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"
    

Antwort

{
  "data": [
    {
      "impressions": "2466376",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Ebenen

Fasse Ergebnisse auf einer definierten Objektebene zusammen. Dadurch werden doppelte Daten automatisch eliminiert.

Anfrage

Du kannst beispielsweise die Insights einer Kampagne auf Werbeanzeigenebene abrufen.

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/CAMPAIGN_ID/insights"

Antwort

{
  "data": [
    {
      "impressions": "9708",
      "ad_id": "6142546123068",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "impressions": "18841",
      "ad_id": "6142546117828",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Wenn du nicht auf alle Werbeobjekte auf der angefragten Ebene zugreifen kannst, werden beim Insights-Aufruf keine Daten zurückgegeben. Beim Anfordern von Insights, wenn für levelad festgelegt wird, gibt dieser API-Aufruf beispielsweise einen Berechtigungsfehler zurück, wenn du mit diesem Werbekonto nicht auf mindestens ein Werbeobjekt Zugriff hast.

Attributionsfenster

Im Conversion-Attributionsfenster sind Zeitrahmen angegeben, die definieren, wann wir ein Event einer Werbeanzeige in einer Meta-App zuordnen. Hintergrundinformationen hierzu findest du unter Meta-Hilfebereich für Unternehmen, Info über Attributionsfenster. Wir messen die Handlungen, die bei einem Conversion-Event vorgenommen werden. Dazu gehen wir zeitlich 1 Tag und 7 Tage zurück. Sende eine Anfrage an /{ad-account-id}/insights, um die Handlungen anzuzeigen, die verschiedenen Attributionsfenstern zugeordnet sind. Wenn du kein action_attribution_windows angibst, geben wir unter value7d_click an.

Beispiel: Gib action_attribution_windows an und „value“ wird im Attributionsfenster 7d_click festgelegt. Sende eine Anfrage an act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view'] und erhalte das folgende Ergebnis:

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

Felderweiterung

Frage Felder auf Node-Ebene und nach den Feldern ab, die unter Felderweiterung angegeben sind.

Anfrage

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_ID"

Antwort

{
  "id": "6042542123268",
  "name": "My Website Clicks Ad",
  "insights": {
    "data": [
      {
        "impressions": "9708",
        "date_start": "2016-03-06",
        "date_stop": "2016-04-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Sortieren

Sortiere die Ergebnisse und gib dazu den sort-Parameter mit {fieldname}_descending oder {fieldname}_ascending an:

Anfrage

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID/insights"

Antwort

{
  "data": [
    {
      "reach": 10742,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "reach": 5630,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-03"
    },
    {
      "reach": 3231,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-02"
    },
    {
      "reach": 936,
      "date_start": "2009-03-29",
      "date_stop": "2016-04-02"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Werbeanzeigen-Labels

Statistiken für alle Labels mit identischen Namen. Zusammengefasst in einem einzelnen Wert auf Werbeanzeigenobjekt-Ebene. Weitere Informationen findest du in der Referenz zu Werbeanzeigen-Labels.

Anfrage

curl -G \  
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"

Antwort

{
  "data": [
    {
      "unique_clicks": 74,
      "cpm": 0.81081081081081,
      "total_actions": 49,
      "date_start": "2015-03-01",
      "date_stop": "2015-03-31",
    },
  ], 
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "MA==",
    }
  }
}

Definition zu Klicks

Lies zum besseren Verständnis der Klick-Kennzahlen, die Meta derzeit anbietet, die folgenden Definitionen und die einzelnen Verwendungsmöglichkeiten:

• Link-Klicks, actions:link_click: Die Anzahl der Link-Klicks in Werbeanzeigen, um zu Zielen oder Erlebnissen auf oder außerhalb von Meta zu gelangen. Weitere Informationen findest du unter Hilfebereich für Werbung, Link-Klicks

• Klicks (alle), clicks: Die Kennzahl zählt mehrere Arten von Klicks auf deine Werbeanzeige, darunter bestimmte Arten von Interaktionen mit dem Werbeanzeigen-Container, Links zu anderen Zielen und Links zu erweiterten Werbeerlebnissen. Weitere Informationen findest du unter Hilfebereich für Werbung, Klicks (alle)

Gelöschte und archivierte Objekte

Werbeeinheiten können DELETED (gelöscht) oder ARCHIVED (archiviert) werden. Die Statistiken von gelöschten und archivierten Objekten werden angezeigt, wenn du deren übergeordnete Objekte abrufst. Wenn du impressions also auf Anzeigengruppenebene abfragst, umfassen die Ergebnisse impressions von allen Werbeanzeigen in der Anzeigengruppe, unabhängig davon, ob die Anzeigen sich in einem gelöschten oder archivierten Zustand befinden. Weitere Informationen findest du unter Speichern und Abrufen von Werbeobjekten – Best Practices.

Wenn du jedoch Abfragen mit Filtern tätigst, werden standardmäßig Statusfilter angewendet und nur aktive Objekte werden zurückgegeben. Daraus resultierend sind die Gesamtstatistiken des übergeordneten Nodes möglicherweise größer als die der untergeordneten.

Du kannst jedoch die Statistikwerte von ARCHIVED (archivierten) Objekten von den übergeordneten Nodes abrufen, indem du einen zusätzlichen filtering-Parameter angibst.

Anfrage

So rufst du die Statistikwerte von allen ARCHIVED (archivierten) Werbeanzeigen in einem Werbekonto ab, die einzeln aufgeführt sind:

curl -G \
  -d "level=ad" \
  -d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/insights/"

Antwort

Beachte, dass nur archivierte Objekte in dieser Antwort zurückgegeben werden.

{
  "data": [
    {
      "impressions": "1741",
      "date_start": "2016-03-11",
      "date_stop": "2016-03-12"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Insights der gelöschten Objekte

Du kannst die Statistikwerte zu gelöschten Objekten abrufen, wenn du deren IDs hast oder den ad.effective_status-Filter verwendest.

Anfrage

Wenn du zum Beispiel die ID der Anzeigengruppe hast:

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID"
    

In diesem Beispiel führen wir eine Abfrage mit ad.effective_status durch:

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

Antwort

{
  "id": "6042147342661",
  "name": "My Like Campaign",
  "status": "DELETED",
  "insights": {
    "data": [
      {
        "impressions": "1741",
        "date_start": "2016-03-11",
        "date_stop": "2016-03-12"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Problembehebung

Zeitüberschreitungen

Am häufigsten werden Fehler bei diesem Endpunkt durch zu viele Anfragen und Zeitüberschreitungen verursacht:

• Bei /GET- oder synchronen Anfragen erhältst du möglicherweise Speicherplatz- oder Zeitüberschreitungsfehler.
• Bei /POST- oder asynchronen Anfragen erhältst du möglicherweise Zeitüberschreitungsfehler. Asynchrone Anfragen können bis zu einer Stunde dauern, wiederholte Versuche eingeschlossen. Beispiel: Abfragen, die große Datenmengen für viele Objekte auf Werbeanzeigen-Ebene abrufen.

Empfehlungen

• Es gibt keine explizite Grenze für Abfragefehler. Versuche bei Zeitüberschreitungen die Abfrage in kleinere Abfragen aufzuteilen, indem du Filter wie Datumsbereiche anwendest.
• Die Berechnung von einzelnen Kennzahlen ist zeitaufwendig. Rufe einzelne Kennzahlen in einem separaten Abruf ab. Dies verbessert die Performance von nicht einzelnen Kennzahlen.

Durchsatzratenbegrenzung

Die Insights API von Meta stellt anhand der Durchsatzratenbegrenzung eine optimale Erfahrung bei der Berichterstellung für alle Partner sicher. Weitere Informationen und Vorschläge findest du in den Begrenzungen und Best Practices für unsere Insights API.

Unterschied zum Werbeanzeigenmanager

Das Standardverhalten der API unterscheidet sich vom Standardverhalten im Werbeanzeigenmanager. Wenn du das gleiche Verhalten wie im Werbeanzeigenmanager bevorzugst, setze das Feld use_account_attribution_setting auf „true“.

Mehr dazu

• Werbekonto-Insights
• Werbekampagnen-Insights
• Anzeigengruppen-Insights
• Werbeanzeigen-Insights

In dieser Liste nicht enthaltene Endpunkte werden von dieser API nicht abgedeckt. Wenn du Berichte von Meta in deine Lösung einbinden möchtest, findest du weitere Informationen in den Nutzungsbedingungen für die Meta-Plattform und den Entwicklungsrichtlinien für Marketing API.