トリガーベースの広告ルール

リアルタイムで広告の状態をモニタリングします。広告オブジェクトのメタデータまたはインサイトデータに変更が加えられると、すぐにトリガーベースのルールが評価されます。メタデータ変更の遅延は通常なら数秒、インサイトの変更の遅延は通常なら数分以内です(現在のp99では約7.5分)。

トリガーベースのルールでは、常にリアルタイムでチェックされるため、schedule_specはサポートされていません。

トリガーベースのルールは、現時点ではAPIでのみ利用可能であり、広告マネージャではアクセスできません。

トリガーオブジェクト

triggerオブジェクトは、ルールの評価方法を定義します。METADATA_CREATIONを除くすべてのトリガータイプには、トリガーfieldが必要です。トリガーベースのルールが条件をチェックするのは、このフィールドが変更された時点だけです。

トリガーベースのルールに指定できるtriggerは1つだけです。複数の指標に対する条件や制約がある場合、残りをfiltersとして追加することができます。

filtersフィールドの使い方は、スケジュールベースのルールと同じです。トリガーベースのルールの評価がパスするのは、triggerとすべてのfiltersとが比較条件を満たす場合だけです。つまり、あるフィールドの変更がもう一方のフィールドの変更につながる場合、トリガーとフィルターは交換可能です。例えば、cost_per_mobile_app_install > Xかつspent > Yの場合にトリガーするルールであれば、cost_per_mobile_app_installまたはspentのどちらか一方をトリガーとして、もう一方をフィルターの1つとして使うことができます。それらの2つのフィールドは依存関係にあるからです。

triggerオブジェクトはevaluation_specの下に属し、その構造は次のとおりです。

トリガーオブジェクトキー	説明
`type`	トリガーベースのルールのタイプ。現在サポートされているオプションは次のとおりです。 `METADATA_CREATION`: 広告オブジェクト作成時点でトリガー `METADATA_UPDATE`: メタデータ`field`が更新された時点でトリガー `STATS_CHANGE`: インサイト`field`が変化して比較条件が満たされるようになった時点でトリガー `STATS_MILESTONE`: インサイト`field`が`value`の倍数に達した時点でトリガー
`field`	基礎となるフィールド。`METADATA_CREATION`では使用されない
`value`	基礎となるフィルター値。`METADATA_CREATION`では使用されない。`METADATA_UPDATE`では任意。
`operator`	基礎となるフィルター演算子。`METADATA_CREATION`では使用されない。`METADATA_UPDATE`では任意。

作成する広告ルールのトリガー方法には、以下の4種類があります。

メタデータ関連: METADATA_CREATIONまたはMETADATA_UPDATE
インサイト関連: STATS_MILESTONEまたはSTATS_CHANGE

メタデータ関連のトリガールール

メタデータ作成ルール

このルールは、広告オブジェクト作成のモニタリングに使われます。triggerのスペックのうち必須なのはtypeだけです。フィルターの場合は、モニタリング対象のentity_typeを指定します。

以下は、特定の目的に分類される広告すべての作成を監視するメタデータ作成ルールの例です。APP_INSTALLSを目的とする広告キャンペーンで新しい広告が作成されると、pingが送信されます。

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"

メタデータ更新ルール

このルールは、広告オブジェクトのメタデータが変化した時点をモニタリングするために使います。サポートされているメタデータフィールドのリストをご覧ください。triggerスペック内ではfieldが必須ですが、valueとoperatorは任意です。

フィールドの変化が重要である場合は、その値が何であってもfieldオプションを指定する必要があります。以下は、広告セットの1日の予算が変化するたびにFacebook通知を送信する例です。

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"

イベントの一部のみが重要である場合は、operatorとvalueのオプションを提供して、trigger条件を絞り込むことができます。以下は、広告セットの1日の予算が変化して、1000を超えた時点で通知を受ける例です。

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"

インサイト関連のトリガールール

統計マイルストーンルール

typeがSTATS_MILESTONEの場合、evaluation_specは、filters配列内の条件に一致するオブジェクトについてfieldがvalueの倍数になった時点でトリガーします。

このタイプの規則の場合、トリガーのoperatorはEQUALでなければならず、time_presetフィルターの値はLIFETIMEでなければなりません。

サポートされるフィールドは、さらに限られることになります。下記に記載されていないフィールドは、トリガーfieldとしてはサポートされませんが、filtersのリスト内のフィルターとして使うことは可能です。さらに、トリガーのvalueには、fieldに応じて求められる最小値があります。

サポートされているトリガーフィールド値	最小値
`impressions`	1000
`unique_impressions`	1000
`reach`	1000
`clicks`	10
`unique_clicks`	10
`spent`	1000 (セント)
`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

以下は、統計マイルストーンルールの例です。誰かが投稿にコメントするたびにpingが送信されます。

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

統計変更ルール

トリガーSTATS_CHANGEとしてtypeを使う場合、指定されたtime_preset内でトリガーと全フィルターの論理ANDの評価結果がfalseからtrueに変化した時点で、execution_specがトリガーされます。

その論理ANDのその後の評価結果がやはりtrueなら、execution_specは実行されません。ただし、その論理ANDの評価結果がtrueからfalseに変化した後、再びtrueに戻った時点でexecution_specが実行されます。

この特定のタイプのルールにおいて、トリガーのoperatorとして使用可能なのは、GREATER_THAN、LESS_THAN、IN_RANGE、NOT_IN_RANGEのいずれかです。

以下に、統計変更ルールの例を示します。過去3日間に、広告が5000人を超える人にリーチし、広告購入単価が$10を超えた場合に一時停止します。

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

配信インサイト変更ルール(ベータ版)

DELIVERY_INSIGHTS_CHANGEをトリガーのtypeとして使う場合、ルールがトリガーされるのは、evaluation_specで定義されているすべてのフィルターの評価結果がtrueであり、かつ、evaluation_specで定義されているトリガーだけがfalseからtrueに変化する場合です。

その後の評価でフィルターとトリガーの評価結果がtrueでままである限り、ルールが再びトリガーされることはありません。

Webhooksの設定

実行タイプPING_ENDPOINTを使うには、Webhooksによるアプリのサブスクリプションを設定する必要があります。ルールAPIから通知を受け取るため、コールバックURL、Facebookアプリ、Webhooksを以下のように設定します。

ステップ1: コールバックURLを設定する

Webhooksガイドを参照して、認証時のチャレンジと応答を処理できるコールバックURLを作成します。コールバックURLは、ルールがトリガーされた際に送信されるデータ構造を処理します。

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

current_valueフィールドは、JSONエンコード文字列です。その値は、文字列を二重引用符で囲んだもの、数値、[ (左ブラケット)で始まり] (右ブラケット)で終わる配列のいずれかです。

ステップ2: アプリに`ads_rules_engine` Webhookを追加する

コールバックURLによって認証のチャレンジと応答が処理されたら、ルールがトリガーされる際にそれをアプリに登録します。

新しいFacebookアプリを作成するか、既存のアプリを使います。
Webhooks商品を追加します。

アプリの新しいサブスクリプションを作成し、ad_rules_engineを選択します。

別の方法として、グラフAPIを使うこともできます。ただし、使うのはアプリアクセストークンであり、ユーザーアクセストークンではありません。

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"

APP_ID/subscriptionsについて詳しくは、サブスクリプションのリファレンスをご覧ください。