Offline Conversions API

Gunakan Offline Conversions API untuk mengirim peristiwa konversi offline dan melihat jumlah pelanggan yang melihat atau mengeklik iklan Meta sebelum berkonversi.

Sebelum Memulai

Untuk menggunakan API ini, Anda membutuhkan:

1. Pengelola Meta Business

Buatlah jika Anda belum punya.

2. ID Aplikasi Meta

Untuk akses ke Marketing API. Untuk membuat aplikasi Meta:

• Buka Pengelola Bisnis > Pengaturan Bisnis.
• Pilih Aplikasi.
• Klik Tambahkan Aplikasi Baru dan ikuti instruksinya.

3. Tinjauan Aplikasi dan Izin

Aturan seputar tinjauan dan izin aplikasi bergantung pada bagaimana Anda menerapkan API kami:

4. Token dan Pengguna Sistem Pengelola Bisnis

Dengan akses sistem pengguna, aplikasi Anda dapat mengirimkan data ke Meta melalui API. Untuk membuatnya:

• Buka Pengelola Bisnis > Pengaturan Bisnis.
• Pilih Pengguna Sistem.
• Klik Tambahkan Pengguna Sistem Baru.
• Pilih Pengguna Sistem Admin sebagai peran untuk pengguna sistem.

Token akses memberikan akses ke data Meta. Untuk membuat token akses pengguna sistem:

• Buka Pengelola Bisnis > Pengaturan Bisnis.
• Pilih Pengguna Sistem.
• Pilih pengguna sistem dan klik Buat Token Baru.
• Pilih aplikasi Anda > untuk lingkup, pilih ads_management.

5. Akun Iklan

Anda membutuhkan akun iklan untuk menjalankan kampanye iklan di Meta. Untuk membuatnya, lihat Marketing API atau Pusat Bantuan Bisnis: Tentang pengaturan bisnis Anda di Pengelola Meta Business.

6. Berikan Akses Pengguna Sistem ke Akun Iklan

Berikan akses pengguna sistem Anda ke akun iklan Anda.

• Buka Pengelola Bisnis > Pengaturan Bisnis.
• Pilih Pengguna Sistem.
• Pilih pengguna sistem dan klik Tetapkan Aset.
• Pilih akun iklan Anda.

7. Set Peristiwa Offline

Berikut adalah file unggahan berisi data konversi offline. Jika Anda membuat iklan, atur tracking_spec menjadi ID set peristiwa offline untuk mengatribusikan peristiwa dengan benar. Anda kemudian dapat membuat set peristiwa, melihat statistik impor Anda, menghapus, dan memodifikasi data ini di Pengelola Bisnis.

Untuk penerapan sebelumnya, Anda dapat menjalankan operasi CRUD set peristiwa offline pada tingkat Pengelola Bisnis untuk membagikan set peristiwa ke objek dan entitas lainnya.

Mengunggah Data Peristiwa

Anda membutuhkan akses yang spesifik untuk membuat set peristiwa offline, mengunggah, atau melihat data untuk sebuah set peristiwa. Anda juga memerlukan akses ini untuk menetapkan izin ini ke suatu akun iklan. Anda haruslah salah satu dari berikut ini:

• Admin Pengelola Bisnis
• Pengguna sistem admin yang membuat set peristiwa offline
• Admin pada ad_account yang terhubung ke set peristiwa offline

Lihat Set Peristiwa Konversi Offline, Referensi.

1. Buat Set Peristiwa Offline

curl 
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' 
  -F 'name=offline_event_set',
  -F 'description=conversion data used for superbowl campaign',
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

Buat HTTP POST:

POST /<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

Tanggapan yang diberikan mencakup id set peristiwa:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Parameter

2. Tetapkan Izin Akun Iklan

Untuk menetapkan izin pelacakan dan membaca ke akun iklan:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Parameter

3. Menetapkan Pelacakan Iklan

Jika Anda memperbarui tracking_spec, kami menggantinya. Pastikan Anda melakukan GET terlebih dahulu, lalu tambahkan String terkait untuk set peristiwa offline ke tracking_spec yang sudah ada. Lihat Pengelolaan Iklan atau gunakan Pengelola Iklan. Contoh: sediakan spesifikasi pelacakan yang sesuai:

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

Untuk memperbarui spesifikasi pelacakan iklan Anda:

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

Parameter

4. Unggah Peristiwa Offline

Anda harus mengunggah transaksi dalam periode 62 hari setelah konversi. Unggah data konversi:

curl \
  -F 'access_token=SYSTEM_USER_ACCESS_TOKEN' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["HASH1","HASH2"], "email": ["HASH3","HASH4"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {             
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {
        event_source: "email",
        action_type: "sent_open_click",
        email_type: "email_type_code", 
        email_provider: "gmail_yahoo_hotmail",
      }
    }, 
  ]'
  https://graph.facebook.com/VERSION/OFFLINE_EVENT_SET_ID/events

Untuk mengirim konversi, lakukan HTTP POST:

POST /<OFFLINE_EVENT_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/events

Parameter

Gunakan upload_tag yang sama untuk semua panggilan API unggahan peristiwa dalam batch yang sama untuk mengelompokkannya. Ini membantu Anda melakukan debug terhadap unggahan peristiwa, dan Anda harus menggunakan ini untuk tiap unggahan peristiwa yang dilakukan di lebih dari satu panggilan API.

Parameter dalam data mencakup:

Sebagai contoh, Anda dapat mengunggah informasi dengan kolom data:

{
  match_keys: MATCH_KEYS,
  event_time: EVENT_TIME,
  event_name: "Purchase",
  value: 400,
  currency: "USD",
  contents: [
    {
        id: "A",
        quantity: 1,
        brand: "brand_of_A",
        category: "Apparel & Accessories | Clothing",
        price: 100,
    },
    {
        id: "B",
        quantity: 2,
        brand: "brand_of_B",
        category: "Apparel & Accessories | Shoes",
        price: 50,
    },
    {
        id: "C",
        quantity: 1,
        brand: "brand_of_C",
        category: "Apparel & Accessories | Jewelry | Watches",
        price: 200,
    }
  ],
}

Gunakan upload_tag yang sama untuk semua panggilan API unggahan peristiwa dalam batch yang sama untuk mengelompokkannya. Ini membantu Anda melakukan debug terhadap unggahan peristiwa, dan Anda harus menggunakan ini untuk tiap unggahan peristiwa yang dibuat dalam lebih dari satu panggilan API.

Kunci Kecocokan

match_keys adalah set pengidentifikasi untuk mencocokkan orang dengan atribusi. Lihat Pemirsa Khusus dari Data CRM untuk menormalkan dan memberi hasing pada data Anda. Hanya SHA256 yang didukung dan kami tidak menerima data tanpa hash.

Tanggapan:

Anda melihat pengecualian di kesalahan, termasuk entri yang tidak valid dan alasannya. Perbaiki kesalahan tersebut atau lewati baris data yang berisi kesalahan dan coba lagi panggilan API-nya.

Lihat Status Unggahan

Pengurus atau pengguna sistem Pengelola Bisnis yang membuat set peristiwa offline dapat mengambil statistik unggah. Juga admin di ad_account yang terhubung ke set peristiwa offline dapat membaca data ini.

Untuk melihat statistik tentang set peristiwa offline, seperti entri yang valid dan entri yang cocok:

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

Lihat perincian harian peristiwa offline di Offline Events Manager pada Pengelola Bisnis. Untuk perincian yang lebih detail, buat panggilan ini:

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

Parameter

Buat Konversi Khusus Offline

Konversi Khusus Offline saat ini tidak memberlakukan backfill. Kami tidak mengatribusikan data dari unggahan peristiwa yang dibuat sebelum Anda membuat konversi khusus. Anda tidak dapat menggunakan data konversi khusus offline untuk pengoptimalan penayangan iklan. Lihat Konversi Khusus, Referensi.

Untuk membuat konversi khusus menggunakan peristiwa offline, lakukan POST:

POST /act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ACCOUNT_ID>/customconversions

Parameter:

Tanggapannya, jika berhasil:

{
  "id": <CUSTOM_CONVERSION_ID>
}

Mengukur dengan Data Khusus

Anda dapat menggunakan kolom custom_data untuk membuat aturan yang nantinya menentukan apakah konversi dihitung atau tidak. Ini serupa dengan Pemirsa Khusus Offline. Jumlah maksimal konversi khusus yang dapat Anda miliki untuk setiap akun iklan adalah sebanyak 40.

Contoh: sertakan kategori produk dalam unggahan dengan custom_data:

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
      product_category: "ICECREAM",
    },
  },
]

Lalu, gunakan custom_data.{YOUR_CUSTOM_PARAM} untuk membuat aturan Konversi Khusus:

curl \
  -F 'name=Ice Cream Purchasers' \
  -F 'custom_event_type=Purchase' \
  -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
  -F 'rule={"and": [{"event_name":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
  -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

Konversi Offline untuk Partner

Untuk mengatribusikan peristiwa konversi offline ke iklan klien Anda, ikuti langkah-langkah ini. Panggilan API untuk sebagian besar langkah-langkah ini sama seperti ketika seseorang mengelola set peristiwa offline dan pengelolaan kampanyenya sendiri.

1. Partner - Buat set peristiwa offline
2. Partner - Bagikan set peristiwa dengan Pengelola Bisnis klien
3. Klien - Tetapkan izin pelacakan offline akun iklan
4. Klien - Tetapkan pelacakan offline di iklan
5. Partner - Unggah peristiwa offline, lihat statistik
6. Partner - Tampilkan insight iklan untuk klien

Langkah-langkah ini bervariasi tergantung cara penetapan izin partner atau agensi dengan akun iklan klien:

• Anda dapat memiliki semua akun iklan, set peristiwa, atau aset lain dari klien Anda.
• Anda dapat memiliki izin ke aset klien Anda untuk melakukan tindakan tertentu.

Untuk menyiapkan izin ini, lihat Aset Pengelola Bisnis.

Partner - Berbagi Set Peristiwa

Bagikan set peristiwa dan tetapkan Pengelola Bisnis klien Anda. Klien Anda lalu dapat menggunakan set peristiwa untuk pelacakan iklan.

GET /<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/agencies

Parameter

Klien - Tetapkan Izin Pelacakan Offline Akun Iklan

Berbagi set peristiwa offline yang dibuat oleh partner dengan kliennya. Anda haruslah admin Pengelola Bisnis atau pengguna sistem admin yang membuat set peristiwa offline guna mengaktifkan pelacakan untuk iklan di akun iklan. Jika Anda adalah admin di akun iklan yang terhubung dengan set peristiwa offline, Anda juga dapat melakukan ini. Untuk membuat panggilan API ini, bisnis yang ada di panggilan harus memiliki akses ke set peristiwa offline.

Anda dapat menetapkan pelacakan peristiwa offline dan melihat izin ke akun iklan dengan panggilan ini:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Parameter

Menyediakan ID Eksternal

Ada kemungkinan terdapat skenario yang membuat Anda menyediakan ID eksternal Anda sendiri guna mewakili seorang pelanggan dan mencocokkannya dengan seseorang. Untuk keperluan ini, gunakan extern_id mengikuti pedoman ini.

Partner data yang menjalani proses pencocokan dapat menggunakan id partner-nya sebagai namespace id dan extern_id sebagai tpid.

Hanya sediakan match_keys

Kami menggunakan match_keys untuk mencoba menentukan apakah data konversi yang Anda bagikan dapat dicocokkan dengan pengguna Meta. Jika Anda menyediakan match_keys, parameter namespace_id tidak dapat disediakan.

Sediakan match_keys dan extern_id

Kami menggunakan match_keys untuk menemukan orang di Meta dan meneruskan pemetaan dari {dataset_id, extern_id} ke {facebook_user_id}. Jika Anda menyediakan match_keys dan extern_id, namespace_id tidak dapat disediakan.

Hanya sediakan extern_id

Jika Anda telah mengirim data dengan match_keys dan extern_id, Meta menggunakan {dataset_id, extern_id} untuk mengambil {facebook_user_id}.

Sediakan namespace_id

Parameter namespace_id berlaku untuk seluruh panggilan API. Anda dapat menggunakannya untuk membuka set peristiwa offline lain yang dapat diakses atau dimiliki oleh bisnis maupun ID profil partner. Jika Anda telah mengirim data dengan match_keys dan extern_id, Meta menggunakan {namespace_id, extern_id} untuk mengambil {facebook_user_id}. Anda sebaiknya hanya menyediakan satu extern_id per baris data.

Insight dan Atribusi

Lihat peristiwa offline yang diatribusikan ke iklan yang dilihat atau diklik oleh seseorang. Kami mengatribusikan konversi offline setelah lebih dari 1 hari. Ini artinya Anda harus mengatur durasi atribusi menjadi 28d_view, atau action_attribution_windows=['28d_view']', jika tidak, Anda tidak akan melihat konversi dalam laporan. Lihat Insights API dan Panduan Insights.

GET /act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ADACCOUNT_ID>/insights

Parameter

Hasilnya terlihat seperti ini:

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
  ]
}

Contoh: untuk melihat atribusi:

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

Hasilnya terlihat seperti ini:

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

>Opsi Pemrosesan Data untuk Pengguna di AS

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

Pelajari selengkapnya tentang Opsi Pemrosesan Data.