Trigger-basierte Anzeigenregeln

Überwache den Status deiner Werbeanzeigen in Echtzeit. Eine Trigger-basierte Regel wird geprüft, sobald die Metadaten oder Insights-Daten der relevanten Anzeigenobjekte geändert werden. Die Latenz für Metadatenänderungen beträgt normalerweise wenige Sekunden. Bei Insights-Änderungen beträgt sie normalerweise wenige Minuten (derzeit liegt die p99 bei etwa 7,5 Minuten).

Bei Trigger-basierten Regeln wird schedule_spec nicht unterstützt, da sie immer in Echtzeit überprüft werden.

Trigger-basierte Regeln sind derzeit nur in der API verfügbar und nicht über den Werbeanzeigenmanager.

Trigger-Objekt

Das trigger-Objekt definiert, wie eine Regel geprüft wird. Alle Trigger-Typen außer METADATA_CREATION erfordern ein Trigger-field. Eine Trigger-basierte Regel prüft seine Bedingung nur, wenn dieses Feld geändert wird.

Eine Trigger-basierte Regel kann nur einen trigger haben. Wenn du Bedingungen oder Einschränkungen zu mehreren Kennzahlen nutzt, kannst du diese als filters hinzufügen.

Das filters-Feld wird genauso wie bei zeitplanbasierten Regeln verwendet. Eine Trigger-basierte Regel wird nur dann ausgelöst, wenn der trigger und alle filters erfüllt sind. Ein Trigger und ein Filter sind also austauschbar, wenn die Änderung eines Feldes zur Änderung des anderen führt. Angenommen, eine Regel soll ausgelöst werden, wenn cost_per_mobile_app_install > X UND spent > Y. Dann kannst du entweder cost_per_mobile_app_install oder spent als Trigger verwenden und das jeweils andere Element als Filter, da diese beiden Felder voneinander abhängig sind.

Das trigger-Objekt gehört unter evaluation_spec und entspricht der folgenden Struktur:

Trigger-Objektschlüssel	Beschreibung
`type`	Der Typ der Trigger-basierten Regel. Derzeit werden folgende Optionen unterstützt: `METADATA_CREATION`: Wird ausgelöst, wenn ein Werbeanzeigenobjekt erstellt wird `METADATA_UPDATE`: Wird ausgelöst, wenn das Metadaten-`field` aktualisiert wird `STATS_CHANGE`: Wird ausgelöst, wenn das Insights-`field` geändert wird und den Vergleich besteht `STATS_MILESTONE`: Wird ausgelöst, wenn das Insights-`field` ein Vielfaches des `value` erreicht
`field`	Das zugrunde liegende Feld. Wird nicht für `METADATA_CREATION` verwendet.
`value`	Der zugrunde liegende Filterwert. Wird nicht für `METADATA_CREATION` verwendet. Optional für `METADATA_UPDATE`.
`operator`	Der zugrunde liegende Filteroperator. Wird nicht für `METADATA_CREATION` verwendet. Optional für `METADATA_UPDATE`.

Werbeanzeigenregeln können auf vier verschiedene Arten ausgelöst werden:

Metadatenabhängig: METADATA_CREATION oder METADATA_UPDATE
Insights-abhängig: STATS_MILESTONE oder STATS_CHANGE

Metadatenabhängige Trigger-Regeln

Metadaten-Erstellungsregel

Mit dieser Regel wird überwacht, wann ein Werbeanzeigenobjekt erstellt wird. Nur type wird in der trigger-Spezifikation benötigt. Für die Filter musst du den entity_type angeben, den du überwachen möchtest.

Hier siehst du ein Beispiel für eine Metadaten-Erstellungsregel, mit der die Erstellung aller Werbeanzeigen mit einem bestimmten Ziel überwacht wird. Jedes Mal, wenn eine neue Werbeanzeige in einer Kampagne mit dem Ziel APP_INSTALLS erstellt wird, wird ein Ping gesendet.

curl -i -X POST \
-F 'name=Metadata Creation Example 1' \
-F 'evaluation_spec={
      "evaluation_type" : "TRIGGER",
      "trigger" : {
        "type": "METADATA_CREATION",
      },
      "filters" : [
       {
         "field": "entity_type",
         "value": "AD",
         "operator": "EQUAL",
       },
       {
         "field": "campaign.objective",
         "value": ["APP_INSTALLS"],
         "operator": "IN",
       },
     ]
   }' \
-F 'execution_spec={
      "execution_type": "PING_ENDPOINT"
   }' \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library"

Metadaten-Aktualisierungsregel

Mit dieser Regel wird überwacht, wann die Metadaten eines Werbeanzeigenobjekts geändert werden. Hier findest du eine Liste der unterstützten Metadatenfelder. In der trigger-Spezifikation wird field benötigt. value und operator sind optional.

Wenn du unabhängig vom Wert wissen möchtest, wann ein Feld geändert wird, musst du nur die field-Option angeben. Hier siehst du ein Beispiel, das dir eine Facebook-Benachrichtigung sendet, wenn das Tagesbudget einer Anzeigengruppe geändert wird.

curl -i -X POST \
-F 'name=Metadata Update Example 1' \
-F 'evaluation_spec={
      "evaluation_type" : "TRIGGER",
      "trigger" : {
        "type": "METADATA_UPDATE",
        "field": "daily_budget",
      },
      "filters" : [
       {
         "field": "entity_type",
         "value": "ADSET",
         "operator": "EQUAL",
       },
     ]
   }' \
-F 'execution_spec={
      "execution_type": "NOTIFICATION"
   }' \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library"

Wenn du dich nur für eine Untergruppe der Events interessierst, kannst du mit den Optionen operator und value die trigger-Bedingung einschränken. Hier siehst du ein Beispiel, das dir eine Benachrichtigung sendet, wenn das Tagesbudget einer Anzeigengruppe geändert wird und über 1000 steigt:

curl -i -X POST \
-F 'name=Metadata Update Example 2' \
-F 'evaluation_spec={
      "evaluation_type" : "TRIGGER",
      "trigger" : {
        "type": "METADATA_UPDATE",
        "field": "daily_budget",
        "value": 1000,
        "operator": "GREATER_THAN"
      },
      "filters" : [
       {
         "field": "entity_type",
         "value": "ADSET",
         "operator": "EQUAL",
       },
     ]
   }' \
-F 'execution_spec={
      "execution_type": "PING_ENDPOINT"
   }' \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library"

Insights-abhängige Trigger-Regeln

Statistik-Meilensteinregel

Mit STATS_MILESTONE als type wird die evaluation_spec ausgelöst, wenn das field ein Vielfaches des value für die Objekte erreicht, die die Bedingungen im filters-Array erfüllen.

Für diese Regelart muss der Trigger-operatorEQUAL sein und der time_preset-Filter den Wert LIFETIME aufweisen.

Es gibt eine stärker eingegrenzte Gruppe unterstützter Felder. Alle Felder, die unten nicht aufgeführt sind, werden nicht als Trigger-field unterstützt, aber können trotzdem als Filter in der filters-Liste verwendet werden. Außerdem gibt es abhängig vom field erforderliche Mindestwerte für den value des Triggers.

Unterstützte Trigger-Feldwerte	Mindestwert
`impressions`	1000
`unique_impressions`	1000
`reach`	1000
`clicks`	10
`unique_clicks`	10
`spent`	1000 (Cent)
`results`	5
`app_custom_event`	1
`app_custom_event_fb_mobile_achievement_unlocked`	1
`app_custom_event_fb_mobile_activate_app`	1
`app_custom_event_fb_mobile_add_payment_info`	1
`app_custom_event_fb_mobile_add_to_cart`	1
`app_custom_event_fb_mobile_add_to_wishlist`	1
`app_custom_event_fb_mobile_complete_registration`	1
`app_custom_event_fb_mobile_content_view`	1
`app_custom_event_fb_mobile_initiated_checkout`	1
`app_custom_event_fb_mobile_level_achieved`	1
`app_custom_event_fb_mobile_purchase`	1
`app_custom_event_fb_mobile_rate`	1
`app_custom_event_fb_mobile_search`	1
`app_custom_event_fb_mobile_spent_credits`	1
`app_custom_event_fb_mobile_tutorial_completion`	1
`app_custom_event_other`	1
`leadgen`	1
`like`	1
`link_click`	1
`mobile_app_install`	1
`offsite_conversion`	1
`offsite_conversion_add_to_cart`	1
`offsite_conversion_checkout`	1
`offsite_conversion_fb_pixel_add_payment_info`	1
`offsite_conversion_fb_pixel_add_to_cart`	1
`offsite_conversion_fb_pixel_add_to_wishlist`	1
`offsite_conversion_fb_pixel_complete_registration`	1
`offsite_conversion_fb_pixel_initiate_checkout`	1
`offsite_conversion_fb_pixel_lead`	1
`offsite_conversion_fb_pixel_other`	1
`offsite_conversion_fb_pixel_purchase`	1
`offsite_conversion_fb_pixel_search`	1
`offsite_conversion_fb_pixel_view_content`	1
`offsite_engagement`	1
`post`	1
`post_comment`	1
`post_engagement`	1
`post_like`	1
`post_reaction`	1
`view_content`	1
`video_play`	1
`video_view`	1
`vote`	1

Hier siehst du ein Beispiel für eine Statistik-Meilensteinregel. Sie sendet einen Ping, wenn jemand deinen Beitrag kommentiert:

curl \
-F 'name=Rule 1' \
-F 'evaluation_spec={
      "evaluation_type" : "TRIGGER",
      "trigger" : {
        "type": "STATS_MILESTONE",
        "field": "post_comment",
        "value": 1,
        "operator": "EQUAL"
      },
      "filters" : [
       {
         "field": "entity_type",
         "value": "CAMPAIGN",
         "operator": "EQUAL",
       },
       {
         "field": "time_preset",
         "value": "LIFETIME",
         "operator": "EQUAL",
       },
     ]
   }' \
-F 'execution_spec={
      "execution_type": "PING_ENDPOINT"
   }' \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library

Statistik-Änderungsregel

Wenn du STATS_CHANGE als Trigger-type verwendest, wird die execution_spec ausgelöst, wenn sich das logische AND des Triggers und aller Filter im von time_preset vorgegebenen Zeitraum von false in true ändert.

Wenn weitere Prüfungen des logischen AND ebenfalls „true“ ergeben, wird die execution_specnicht ausgeführt. Wenn sich die Prüfung des logischen AND jedoch von true in false ändert, wird die execution_spec ausgeführt, wenn sie sich wieder in true ändert.

Für diese Regelart kann der Trigger-operatorGREATER_THAN, LESS_THAN, IN_RANGE oder NOT_IN_RANGE verwendet werden.

Hier siehst du ein Beispiel für eine Statistik-Änderungsregel. Wenn eine Werbeanzeige mehr als 5.000 Personen erreicht hat und in den letzten 3 Tagen 10 US-Dollar pro Kauf überschritten hat, wird sie pausiert.

curl \
-F 'name=Rule 1' \
-F 'evaluation_spec={
      "evaluation_type" : "TRIGGER",
      "trigger" : {
        "type": "STATS_CHANGE",
        "field": "cost_per_purchase_fb",
        "value": 1000,
        "operator": "GREATER_THAN",
      },
      "filters" : [
       {
         "field": "entity_type",
         "value": "AD",
         "operator": "EQUAL"
       },
       {
         "field": "time_preset",
         "value": "LAST_3_DAYS",
         "operator": "EQUAL"
       },
       {
         "field": "reach",
         "value": 5000,
         "operator": "GREATER_THAN"
       }
     ]
   }' \
-F 'execution_spec={
      "execution_type": "PAUSE"
   }' \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library

Auslieferungs-Insights-Änderungsregeln (Beta)

Wenn du DELIVERY_INSIGHTS_CHANGE als Trigger-type verwendest, wird die Regel ausgelöst, wenn alle in evaluation_spec definierten Filter true ergeben und der in evaluation_spec definierte Trigger sich von false in true ändert.

Wenn die Filter und der Trigger bei nachfolgenden Prüfungen weiterhin true ergeben, wird die Regel nicht erneut ausgelöst.

Webhook-Setup

Um den Ausführungstyp PING_ENDPOINT zu verwenden, musst du ein Abonnement für deine App über Webhooks einrichten. Richte eine Callback-URL, eine Facebook-App und Webhooks ein, um Benachrichtigungen von der Rules API zu erhalten:

Schritt 1: Callback-URL einrichten

Lese den Webhooks-Leitfaden und erstelle eine Callback-URL, die die Frage und Antwort während der Verifizierung verarbeiten kann. Die Callback-URL verarbeitet die Datenstruktur, die gesendet wird, wenn eine Regel ausgelöst wird:

{
  object: 'application',
  entry: [{
    id: '<APPLICATION_ID>',
    time: 1468938744,
    changes: [{
      field: 'ads_rules_engine',
      value: {
        'rule_id': 1234,
        'object_id': 5678,
        'object_type': 'ADSET',
        'trigger_type': 'STATS_CHANGE',
        'trigger_field': 'COST_PER_LINK_CLICK',
        'current_value': '15.8',
      }
    }],
  }],
}

Das current_value-Feld ist ein JSON-codierter String. Sein Wert kann ein String in doppelten Anführungszeichen, eine Zahl oder ein Array sein, das mit [ (linke eckige Klammer) beginnt und mit ] (rechte eckige Klammer) endet.

Schritt 2: `ads_rules_engine`-Webhook deiner App hinzufügen

Nachdem die Callback-URL die Frage und Antwort für die Verifizierung bearbeitet hat, registriere sie in deiner App, wenn eine Regel ausgelöst wird:

Erstelle eine neue Facebook-App oder verwende eine vorhandene.
Füge das Webhooks-Produkt hinzu.

Erstelle ein neues Abonnement für eine App und wähle die ad_rules_engine aus.

Alternativ kannst du das über die Graph API mit einem App-Zugriffsschlüssel (keinem Nutzerzugriffsschlüssel) durchführen:

curl \
-F "object=application" \
-F "callback_url=<CALLBACK_URL>" \
-F "fields=ads_rules_engine" \
-F "verify_token=<VERIFY_TOKEN>" \
-F "access_token=<APP_ACCESS_TOKEN>" \
"https://graph.facebook.com/<VERSION>/<APP_ID>/subscriptions"

In der Abonnementreferenz findest du Details zu APP_ID/subscriptions.