Règles avec déclencheur pour les publicités

Surveillez en temps réel l’état de vos publicités. Une règle avec déclencheur est prise en compte à chaque fois que les métadonnées et les données Insights des objets publicitaires concernés sont modifiées. La latence est généralement de quelques secondes pour les modifications des métadonnées et de quelques minutes pour les modifications des données Insights (actuellement, P99 ≃ 7,5 minutes).

schedule_spec n’est actuellement pas accepté dans les règles avec déclencheur, car celles-ci sont toujours vérifiées en temps réel.

Les règles avec déclencheur sont actuellement disponibles uniquement dans l’API, pas dans le Gestionnaire de publicités.

Objet déclencheur

L’objet déclencheur (trigger) définit le mode d’évaluation d’une règle. Tous les types de déclencheurs nécessitent le paramètre field, à l’exception de METADATA_CREATION. Les conditions des règles avec déclencheur sont vérifiées uniquement en cas de modification de ce champ.

Une règle avec déclencheur ne peut comprendre qu’un seul objet trigger. Pour ajouter des conditions ou contraintes à plusieurs indicateurs, utilisez plutôt filters.

Le champ filters fonctionne de la même manière que dans les règles avec calendrier. Pour passer l’évaluation, une règle avec déclencheur doit satisfaire les critères de l’objet trigger et de tous les champs filters. Ainsi, si la modification d’un champ entraîne la modification d’un autre, vous pouvez utiliser l’un ou l’autre comme déclencheur ou filtre : ils sont interchangeables. Par exemple, si vous souhaitez qu’une règle se déclenche quand cost_per_mobile_app_install > X ET spent > Y, vous pouvez utiliser cost_per_mobile_app_install ou spent comme déclencheur, et l’autre comme filtre, car ces deux champs sont dépendants.

L’objet trigger appartient au paramètre evaluation_spec et suit la structure ci-dessous :

Clés de l’objet déclencheur	Description
`type`	Type de règle avec déclencheur. Pour le moment, les options prises en charge sont : `METADATA_CREATION` : se déclenche quand un objet publicitaire est créé `METADATA_UPDATE` : se déclenche quand le `field` des métadonnées est modifié `STATS_CHANGE` : se déclenche quand le `field` des Insights est modifié pour correspondre à la comparaison `STATS_MILESTONE` : se déclenche quand le `field` des Insights atteint un multiple de `value`
`field`	Champ sous-jacent. Non utilisé pour `METADATA_CREATION`
`value`	Valeur sous-jacente du filtre. Non utilisé pour `METADATA_CREATION`. Facultatif pour `METADATA_UPDATE`.
`operator`	Opérateur sous-jacent du filtre. Non utilisé pour `METADATA_CREATION`. Facultatif pour `METADATA_UPDATE`.

Il existe quatre façons de créer des règles publicitaires avec déclencheur :

En fonction des métadonnées : avec METADATA_CREATION ou METADATA_UPDATE
En fonction des Insights : avec STATS_MILESTONE ou STATS_CHANGE

Règles avec déclencheur en fonction des métadonnées

Règle basée sur la création des métadonnées

Cette règle permet de surveiller quand un objet publicitaire est créé. Seul le paramètre type est obligatoire dans la spécification trigger. Pour les filtres, spécifiez le type d’entité (entity_type) que vous souhaitez surveiller.

La règle basée sur la création des métadonnées ci-dessous surveille la création de toutes les publicités correspondant à un certain objectif. Un ping est envoyé à chaque fois qu’une nouvelle publicité est créée dans une campagne publicitaire avec l’objectif APP_INSTALLS.

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"

Règle basée sur la modification des métadonnées

Cette règle permet de surveiller quand les métadonnées d’un objet publicitaire sont modifiées. Consultez la liste des champs de métadonnées pris en charge. Dans la spécification trigger, field est obligatoire, tandis que value et operator sont facultatifs.

Si vous souhaitez que la règle soit déclenchée quand un champ est modifié, quelle que soit sa valeur, vous pouvez renseigner uniquement l’option field. Dans l’exemple ci-dessous, vous recevez une notification Facebook quand le budget quotidien d’un ensemble de publicités est modifié.

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"

Si seul un sous-ensemble d’évènements vous intéresse, vous pouvez renseigner les options operator et value pour affiner la condition trigger. Dans cet exemple, vous recevez une notification quand le budget quotidien d’un ensemble de publicités est modifié au-delà de 1 000 :

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"

Règles avec déclencheur en fonction des Insights

Règle basée sur une étape statistique importante

Quand vous utilisez le type de déclencheur STATS_MILESTONE, evaluation_spec se déclenche quand field atteint un multiple de value pour les objets correspondant aux conditions du tableau filters.

Pour ce type de règle, l’operator du déclencheur doit être défini sur EQUAL et le filtre time_preset doit être défini sur LIFETIME.

Les champs pris en charge sont plus limités. Seuls les champs indiqués ci-dessous sont pris en charge comme field déclencheur. En revanche, les autres champs peuvent toujours être utilisés comme filtres dans la liste filters. De plus, la valeur du champ value doit respecter une certaine limite minimale, qui varie en fonction du field.

Valeurs acceptées pour le champ déclencheur	Valeur minimale
`impressions`	1 000
`unique_impressions`	1 000
`reach`	1 000
`clicks`	10
`unique_clicks`	10
`spent`	1 000 (cents)
`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

Voici un exemple de règle basée sur une étape statistique importante, qui envoie un ping dès que quelqu’un commente l’une de vos publications :

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

Règle basée sur une modification statistique

Lorsque vous utilisez le type de déclencheur STATS_CHANGE, execution_spec se déclenche quand l’opérateur logique AND du déclencheur et tous les filtres passent de false à true dans un time_preset donné.

Si l’opérateur logique AND reste « true » lors des évaluations suivantes, execution_spec n’est PAS exécutée. Toutefois, si AND passe de true à false lors de l’évaluation, execution_spec sera exécutée lorsque l’opérateur logique repassera sur true.

Pour ce type de règle, l’operator du déclencheur peut être GREATER_THAN, LESS_THAN, IN_RANGE ou NOT_IN_RANGE.

Voici un exemple de règle basée sur une modification statistique. À chaque fois qu’une publicité atteint plus de 5 000 personnes et que le montant de chaque achat dépasse 10 $ sur les trois derniers jours, la publicité est mise en pause.

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

Règles basées sur une modification des Insights de diffusion (bêta)

Lorsque vous utilisez le type de déclencheur DELIVERY_INSIGHTS_CHANGE, la règle est déclenchée quand tous les filtres définis dans evaluation_spec sont true à l’évaluation ET quand le déclencheur défini dans evaluation_spec passe de false à true.

Si le déclencheur et les filtres restent sur true lors des évaluations suivantes, la règle n’est plus déclenchée.

Configuration des webhooks

Afin d’utiliser le type d’exécution PING_ENDPOINT, vous devez configurer un abonnement aux webhooks pour votre application. Configurez une URL de rappel, une application Facebook et des webhooks pour recevoir des notifications de l’API Rules :

Étape 1 : configurer une URL de rappel

Consultez le guide sur les webhooks et créez une URL de rappel capable de gérer la demande de réponse lors de la vérification. L’URL de rappel gère la structure des données envoyées quand une règle est déclenchée :

{
  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',
      }
    }],
  }],
}

Le champ current_value est une chaîne encodée en JSON. La valeur peut être une chaîne entre guillemets doubles, un chiffre ou un tableau encadré par des crochets ([ au début et ] à la fin).

Étape 2 : ajouter le webhook `ads_rules_engine` pour votre application

Lorsque l’URL de rappel gère la demande de réponse lors de la vérification, enregistrez-la dans votre application quand une règle est déclenchée :

Créez une nouvelle application Facebook ou utilisez une application existante.
Ajoutez le produit Webhooks.

Créez un nouvel abonnement pour une application et sélectionnez ad_rules_engine.

Vous pouvez également réaliser cette action dans l’API Graph, en utilisant un token d’accès à l’application à la place d’un token d’accès utilisateur·ice :

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"

Consultez la référence sur les abonnements pour en savoir plus sur APP_ID/subscriptions.