Ad Rules Engine
2.9より追加されたAd Rules Engineの公式翻訳記事になります。
https://developers.facebook.com/docs/marketing-api/ad-rules-getting-started/v2.9
マーケティングAPIに定期的に問い合わせを行い、広告の掲載結果を監視し、特定の条件でアクションを実行します。
アクション条件となるルールには2つのタイプが存在し、設定した期間を繰り返し評価するスケジュールベース、リアルタイムに定義したルールを評価するトリガーベースが存在します。
また、ルールを適応する対象を限定するフィルターを用いることで、複数のAdやCampaignに対して個別の条件を適応することが可能となります。
アクションの詳細については後述されますが、まとめると次のようなアクションが可能です。
通知、配信の停止、Budgetの引き上げ、現在のAdを停止して指定したAdを配信、Webhookへの通知です。それぞれのアクションはルールベースのタイプによって利用できるものが限定されており、トリガーベースについては、Webhookへの通知のみとなるようです。
- 実行するアクションの定義：Execution Spec
- 評価するルールの定義：Evaluation Type
- 設定期間毎に評価： SCHEDULEルール
- リアルタイムに評価：TRIGGERルール
- 評価対象の定義：filter
ここからほぼ翻訳したものになります。
一部のサンプルやフィールドの詳細な説明は割愛してますので、公式HPをあわせて確認してください。
Ad Rules
広告ルールは、広告ルールライブラリに作成されて保存され、名前、evaluation_spec、およびexecution_specを最小限含むスタンドアロンオブジェクトです。 これがルールの基本構造です。
Facebookは、Insightsメトリックまたはオブジェクトメタデータフィールドが変更されたときに、トリガーベースのルールを評価します。 スケジュールベースのルールをスケジュールされた間隔で評価します。
Evaluation Spec
ルールのevaluation_specの主な目的は、ルールがアクションを実行するオブジェクトを決定することです。 evaluation_typeは、評価メソッドのタイプを決定し、次のオプションを持ちます。
evaluation_specにはfilters配列も含まれているため、一致するオブジェクトのリストをさらに絞り込むことができます。 たとえば、Ad、Adset、CampaignのメタデータとInsightsメトリックにフィルタを組み込むことができます。 すべてのフィルターは、AND演算子を使用して一緒に評価されます。
この配列には、フィルタオブジェクトのリストが含まれています。フィルタオブジェクト自体は、フィールド、値、および演算子のキーを持つディクショナリです。
各フィルタには、サポートされている論理演算子のリストがあります。 SCHEDULEルールとTRIGGERルールでサポートされているすべての論理演算子のリストを次に示します。
(要OHP参照：https://developers.facebook.com/docs/marketing-api/ad-rules-getting-started/v2.9 )
evaluation_specにはオプションで（TRIGGER評価タイプに必要）、トリガが含まれています。トリガには、型とその基礎となるフィルタ指定（フィールド、値、演算子）が含まれています。
違いは、トリガーはルールを評価するかどうかを動的に判断し、ルールを1つしか持たないことです。詳細については、下記のトリガーベースのルールのセクションを参照してください。
以下では、いくつかの特別なフィルターと、使用できるフィルターの一般的なグループを定義します。
フィルタについて
Special Filters
time_presetフィルタは、インサイトの指標を集計する期間を決定します。現在のところ、time_presetは1つのみを許可し、ルール内のすべての統計フィルタに適用されます（存在する場合は、トリガーに使用される統計も含む）。 time_presetのサポートされる唯一の演算子はEQUALです。これは、Insightsフィルタまたはトリガーが存在する限り必要です。
ルールの時間プリセットは他のインターフェイスとは異なる動作をすることに注意してください。ほとんどのプリセットには今日のデータが含まれています。これは、今日のデータが日常よりも頻繁に実行されるルールにとって重要なためです。他のインターフェイスの場合、LAST_N_DAYSのプリセット値には今日のデータは含まれません。詳細については、以下の説明を参照してください。
attribution_windowフィルタは、インプレッションメトリックを集計するルックバックウィンドウを決定します。 詳細については、変換アトリビューションを参照してください。 現在、1つのattribution_windowのみを許可しており、ルール内のすべての統計フィルタに適用されます。 attribution_windowでサポートされる唯一の演算子はEQUALです。これはスケジュールベースのルールでのみサポートされています。 このフィルタを指定しない場合、デフォルト値はDEFAULT値になります。
Metadata filters
メタデータフィルタを使用すると、メタデータフィールドの現在の状態に基づいてオブジェクトをフィルタリングできます。 これらはマルチレベルフィルタリングもサポートしています。つまり、接頭辞を使用してオブジェクトの親または祖父母にもメタデータフィルタを適用できます。 これは他のフィルタには影響しません。 注釈フィルタは通常のオブジェクトにも適用されます。
すべてのメタデータフィルタはスケジュールされたルールでサポートされていますが、現在サブセットのみがトリガールールでサポートされています。
たとえば、目標がWEBSITE_CLICKSのキャンペーンの広告セットに適用されるルールが必要な場合は、次の2つのフィルタを含めることができます。
以下は、トリガおよびスケジュールベースのルールでサポートされているメタデータフィルタのリストです。
(いっぱいあるので抜粋)
評価タイプSCHEDULEまたはTRIGGERのすべてのルールに対して、entity_typeまたはidのいずれかのフィルタを指定する必要があります。
entity_typeフィルタを指定することにより、ルールを適用する動的オブジェクトレベルを指定します。たとえば、entity_typeがADの場合、ルールの作成時に関係なく、アカウントで追加されたすべての新しいAdが自動的に評価されます。代わりにidフィルタを指定することによって、ルールはオブジェクトリストのこの静的オブジェクトにのみ適用されます。
これらは、複数レベルのフィルタリングと組み合わせて使用できます。たとえば、特定の広告セットの下にあるすべての広告に適用するルールを設定するには、ADのentity_typeフィルタと、指定した広告セットを持つadset.idフィルタが必要です。
デフォルトでは、delivery_infoフィルタを指定しないと、ルールを評価するときに暗黙的に追加されます。このデフォルトフィルタには、演算子INと['ACTIVE'、 'LIMITED']という値があります。つまり、ルールは配信がアクティブまたは制限されているオブジェクトのみを評価します。
これは、現在サポートされているすべての実行タイプがアクティブなオブジェクトに対してのみ作用するため、内部最適化です。将来、非アクティブなオブジェクト（たとえば、UNPAUSE）に作用する実行タイプをサポートする必要がある場合は、この最適化を削除します。アクティブではあるがオブジェクトを配信しないようにする必要がある場合は、独自のdelivery_infoフィルタを指定する必要があります。
ようは現状この形態で最適化されているけど、将来的には廃止するかもしれないから注意しろよ
Insights Filters
指定したtime_presetのInsights APIから返された現在の値に対してインサイトフィルタを評価します。
これらのフィルタは、オブジェクトのリストまたはレベルに直接適用され、マルチレベルフィルタリングはサポートされません。
また、ここに表示されるユニットは、Ads APIの通貨のベースに基づいています。 たとえば、USDの場合、基本単位はセントです。つまり、1000の値が$ 10.00に相当します。
下記の各フィールドの説明については、Insights APIのドキュメントを参照してください。
すべてのInsightsフィルタは、次の演算子をサポートしています：GREATER_THAN、LESS_THAN、EQUAL、IN_RANGE、NOT_IN_RANGE
以下は、Insightsフィルタのリストと、それらがトリガベースのルールでサポートされているかどうかです。
(いっぱいあるので抜粋)
Execution Spec
execution_specは、評価をパスするすべてのオブジェクトに適用されるアクションを決定します。 スケジュールとトリガベースのルールは異なるアクションをサポートしており、execute_typeフィールドのアクションを示します。
これらのアクションのいくつかを実行するには、追加情報が必要な場合があります。 execution_specは、ユーザーがこれらの追加パラメーターを指定するためのオプションのexecution_options配列を提供します。 配列にはexecution_optionオブジェクトのリストが含まれています。これらのオブジェクト自体は、上記のフィルタオブジェクトと同様に、フィールド、値、演算子のキーを持つ辞書です。
以下では、使用できるサポートされている実行オプション、サポートする実行_タイプの値、およびそれらの構造化方法を定義します。 現在、すべてのオプションでサポートされている唯一の演算子はEQUALです。 トリガベースのルールには実行オプションは必要ありません。
Status
ルールのステータスによって、ルールを実行する必要があるかどうかが決まります。 ENABLEDとDISABLEDの2つのステータスがあります。 一時的にルールをオフにするには、ルールを編集し、ステータスを「無効」に設定します。 ルールを再度アクティブにするには、ルールを編集し、ステータスを有効に戻します。 ルールを完全に削除するには、ルールを削除します。
Schedule Based Rules
設定された間隔で広告の状態を確認し、広告がevaluation_spec基準を満たしているかどうかを確認して、広告の状態を監視します。 スケジュールベースのルールの場合は、ルール仕様に追加のschedule_specが必要です。
Schedule Spec
ルールのschedule_specは、ルールの実行頻度を決定します。 この間隔をschedule_typeフィールドに示します。
サンプル
次に、evaluation_specの例を示します。 このルールは、過去7日間に10000回以上のインプレッションが発生したID 101,102、または103の広告セットで、積極的に配信するすべての広告に適用されます。
execution_specの例を次に示します。 このルールは、一致するすべてのオブジェクトの予算を10％増やし、最大実行制限を5倍にします。
Trigger Based Rules
トリガーベースのルールとアクションを設定して、広告をモニターして最適化します。 精度を向上させる広告を手動で管理する必要がなくなり、何千もの広告でルールを拡張できます。 広告メタデータと統計情報の変更をほぼリアルタイムで監視できるようになりました。
Webhooksを設定する が長くなるので割愛
サポートされている実行タイプPING_ENDPOINTのみを使用するには、Webhooksを使用してアプリケーションのサブスクリプションを設定する必要があります。
コールバックURL、Facebook App、およびWebhooksを設定して、Rules APIからの通知を取得します。
1.コールバックURLを設定する
「Webhooksガイド」を参照して、検証中にチャレンジとレスポンスを処理できるコールバックURLを作成してください。 コールバックURLは、ルールがトリガされたときに送信されるデータ構造を処理します。
Trigger Object
トリガオブジェクトは、残りのフィルタを適用するかどうかを決定するために使用される条件です。 1つのトリガーしか持てません。 複数の条件が満たされているルールがある場合、トリガーとすべてのフィルタが論理ANDで評価されるため、これらの追加条件をフィルタに配置する必要があります。
トリガオブジェクトは以下の構造を持ち、evaluation_specに属します：
広告ルールは、STATS_MILESTONEやSTATS_CHANGEの2つの方法で作成できます。
Creating a Stats Change Rule
トリガータイプとしてSTATS_CHANGEを使用すると、time_presetで指定された所定の時間枠内で、トリガーとすべてのフィルターの論理積が偽から真に評価されると、execution_specがトリガーされます。論理ANDの後続の評価も真である場合、execution_specは実行されません。しかし、論理ANDの評価が真から偽に変わると、execution_specは再びtrueに戻ったときに実行されます。
この特定のタイプのルールでは、トリガー演算子はGREATER_THAN、LESS_THAN、IN_RANGE、またはNOT_IN_RANGEのいずれかになります。
トリガーサンプル
次に、統計情報変更ルールの例を示します。 過去7日間に評価されたcpcが10を超えるたびに、トリガーが適用されます。 過去7日間に10000回以上のインプレッションがあり、このトリガーを満たしているID 101,102、または103の広告セットの下に広告が送信されます。
−−−−
Creating a Stats Milestone Rule
型としてSTATS_MILESTONEを指定すると、fieldsがfilters配列内の条件に一致するオブジェクトの値の倍数に達すると、evaluation_specがトリガーされます。
この特定のタイプのルールでは、トリガー演算子はEQUALでなければならず、time_presetフィルタの値はLIFETIMEでなければなりません。
より限定的なサポートされたフィールドもあります。 以下にリストされていないフィールドはトリガーフィールドとしてサポートされていませんが、引き続きフィルターのリスト内のフィルターとして使用できます。 さらに、フィールドに応じてトリガーの値に必要な最小値があります。
(フィールドと最小値については割愛)
Updating a Rule
ルールを更新するには、変更されていないフィールドを含むすべてのフィールドを指定する必要があります。 ここでは、1000回のインプレッションごとにルールトリガーを更新する例を示します。 ルールのステータスを更新するには、スペックを変更する必要はありません。
(この辺りにサンプルだが割愛)
Access a Rule's Execution History
スケジュールベースルールの実行ごとに履歴データにアクセスするエンドポイントを提供します。 デフォルトでは、このエンドポイントは結果やアクションなどの関連データを提供します。 各実行時にルールの状態をチェックして、編集内容を追跡することもできます。
さらに、このエンドポイントは、データに対してobject_id、action、およびhide_no_changesの3つのフィルタリング・メカニズムをサポートしています。 結果をobject_idまたはアクションでフィルタリングして、そのobject_idまたはアクションタイプの結果のみを表示することができます。 また、hide_no_changesフラグを使用して結果をフィルタリングして、変更がまったくないすべての実行を除外することもできます。 これらのフィルタを組み合わせて、結果をさらに絞り込むことができます。