Marketing API

Aturan Iklan Berbasis Pemicu

Pantau status iklan Anda secara realtime. Aturan Berbasis Pemicu dievaluasi segera setelah metadata atau insight objek iklan yang relevan diubah. Latensi untuk perubahan metadata biasanya dalam waktu beberapa detik, dan latensi untuk perubahan insight biasanya dalam waktu beberapa menit (p99 saat ini sekitar 7,5 menit).

Untuk Aturan Berbasis Pemicu, schedule_spec tidak didukung, karena selalu diperiksa secara realtime.

Saat ini, Aturan Berbasis Pemicu hanya tersedia di API, dan tidak dapat diakses melalui Pengelola Iklan.

Objek Pemicu

Objek trigger menentukan cara sebuah aturan dievaluasi. Semua jenis pemicu memerlukan field pemicu, kecuali METADATA_CREATION. Aturan Berbasis Pemicu hanya memeriksa kondisi saat kolom ini diubah.

Aturan Berbasis Pemicu hanya dapat memiliki satu trigger. Jika Anda memiliki kondisi atau pembatasan pada beberapa metrik, Anda dapat menambahkan sisanya sebagai filters.

Kolom filters digunakan dengan cara yang sama seperti dalam Aturan Berbasis Jadwal. Aturan Berbasis Pemicu lulus dalam evaluasi hanya jika trigger dan semua filters memenuhi syarat yang ditetapkan. Jadi pemicu dan filter dapat dipertukarkan jika perubahan satu kolom menyebabkan perubahan kolom lainnya. Misalnya, jika Anda ingin suatu aturan terpicu saat cost_per_mobile_app_install > X DAN spent > Y, Anda dapat menggunakan cost_per_mobile_app_install atau spent sebagai pemicu, dan lainnya sebagai salah satu filter, karena dua kolom tersebut bersifat dependen.

Objek trigger termasuk dalam evaluation_spec, dan mengikuti struktur berikut:

Kunci Objek Pemicu Deskripsi

type

Jenis Aturan Berbasis Pemicu. Opsi yang didukung saat ini:

METADATA_CREATION: Pemicu saat objek iklan dibuat

METADATA_UPDATE: Pemicu saat field metadata diperbarui

STATS_CHANGE: Pemicu saat field insight berubah untuk memenuhi syarat yang ditetapkan

STATS_MILESTONE: Pemicu saat field insight mencapai kelipatan value

field

Kolom yang mendasari. Tidak digunakan untuk METADATA_CREATION

value

Nilai filter yang mendasari. Tidak digunakan untuk METADATA_CREATION. Opsional untuk METADATA_UPDATE.

operator

Operator filter yang mendasari. Tidak digunakan untuk METADATA_CREATION. Opsional untuk METADATA_UPDATE.

Anda dapat membuat Aturan Iklan yang dipicu dalam empat cara berbeda:

  • Yang terkait Metadata: METADATA_CREATION atau METADATA_UPDATE
  • Yang terkait Insight: STATS_MILESTONE atau STATS_CHANGE

Aturan Pemicu yang Terkait Metadata

Aturan Pembuatan Metadata

Aturan ini digunakan untuk memantau saat sebuah objek iklan dibuat. Hanya type yang diperlukan dalam spesifikasi trigger. Untuk filter, tentukan entity_type yang ingin Anda pantau.

Berikut ini contoh aturan pembuatan metadata untuk memantau pembuatan semua iklan yang termasuk ke dalam tujuan tertentu. Setiap kali iklan baru dibuat di bawah kampanye iklan tujuan APP_INSTALLS, sinyal ping dikirim.

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"

Aturan Pembaruan Metadata

Aturan ini digunakan untuk memantau saat sebuah objek metadata diubah. Lihat daftar kolom metadata yang didukung. Dalam spesifikasi trigger, field bersifat wajib, sedangkan value dan operator bersifat opsional.

Jika Anda tertarik dengan perubahan kolom, tanpa memandang nilainya, Anda hanya perlu menentukan opsi field. Berikut adalah contoh untuk mengirimi Anda Notifikasi Facebook setiap kali anggaran harian set iklan diubah.

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"

Jika Anda hanya tertarik pada subset peristiwa, Anda dapat memberikan opsi operator dan value untuk mempersempit kondisi trigger. Berikut adalah contoh untuk mendapatkan notifikasi saat anggaran harian set iklan diubah dan melebihi 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"

Aturan Pemicu yang Terkait Insight

Aturan Pencapaian Statistik

Dengan STATS_MILESTONE sebagai type, evaluation_spec memicu saat field mencapai kelipatan value untuk objek yang cocok dengan kondisi dalam array filters.

Untuk jenis aturan spesifik ini, operator pemicu harus EQUAL, dan filter time_preset harus memiliki nilai LIFETIME.

Ada set kolom yang didukung yang lebih membatasi. Kolom yang tidak tercantum di bawah ini tidak didukung sebagai field pemicu, tetapi masih dapat digunakan sebagai filter di daftar filters. Selain itu, ada nilai minimum yang diperlukan untuk value pemicu, bergantung pada field.

Nilai Kolom Pemicu yang Didukung Nilai Minimum

impressions

1.000

unique_impressions

1.000

reach

1.000

clicks

10

unique_clicks

10

spent

1.000 (sen)

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

Berikut adalah contoh aturan pencapaian statistik, yang mengirimkan ping setiap kali seseorang mengomentari postingan Anda:

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

Aturan Perubahan Statistik

Saat menggunakan STATS_CHANGE sebagai type pemicu, execution_spec dipicu saat logika AND pemicu dan semua filter dievaluasi dari false ke true dalam time_preset tertentu.

Jika evaluasi logika AND berikutnya juga bernilai true, execution_spectidak dijalankan. Namun, jika evaluasi AND logis berubah dari true menjadi false, execution_spec dijalankan saat berubah kembali ke true.

Untuk jenis aturan spesifik ini, operator pemicu dapat berupa GREATER_THAN, LESS_THAN, IN_RANGE, atau NOT_IN_RANGE.

Berikut adalah contoh aturan perubahan statistik. Setiap kali iklan mencapai lebih dari 5.000 pemirsa dan lebih dari 10 USD per pembelian selama 3 hari terakhir, lakukan jeda.

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

Aturan Perubahan Insight Penayangan (Beta)

Saat menggunakan DELIVERY_INSIGHTS_CHANGE sebagai type pemicu, aturan dipicu saat semua filter yang ditetapkan dalam evaluation_spec dievaluasi menjadi true, dan pemicu yang ditentukan dalam evaluation_spec hanya berubah dari false menjadi true.

Jika evaluasi berikutnya menunjukkan bahwa filter dan pemicunya tetap bernilai true, aturan tidak terpicu lagi.

Pengaturan Webhooks

Untuk menggunakan PING_ENDPOINT jenis eksekusi, Anda perlu mengatur langganan aplikasi Anda melalui Webhooks. Siapkan URL panggilan balik, Aplikasi Facebook, dan Webhooks untuk mendapatkan notifikasi dari Rules API:

Langkah 1: Siapkan URL panggilan balik

Lihat Panduan Webhooks dan buat URL panggilan balik yang dapat menangani tantangan dan tanggapan selama verifikasi. URL panggilan balik menangani struktur data yang dikirim saat aturan dipicu:

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

Kolom current_value adalah string yang berenkode JSON. Nilainya dapat berupa string dalam tanda kutip ganda, angka, atau array dimulai dengan [ (kurung buka) dan diakhiri dengan ] (kurung tutup).

Langkah 2: Tambahkan Webhooks ads_rules_engine ke aplikasi Anda

Setelah URL panggilan balik menangani tantangan dan tanggapan untuk verifikasi, daftarkan di aplikasi Anda saat aturan dipicu:

  • Buat Langganan Baru untuk Aplikasi dan pilih ad_rules_engine.

Atau, ini bisa dilakukan melalui Graph API, dengan menggunakan token akses Aplikasi dan bukan token akses pengguna:

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"

Lihat Referensi Langganan untuk detail tentang APP_ID/subscriptions.