Insight API

Menyediakan satu antarmuka yang konsisten untuk mengambil statistik iklan.

• Perincian - Kelompokkan hasil
• Perincian Tindakan - Memahami tanggapan dari perincian tindakan.
• Pekerjaan Asinkron - Untuk permintaan dengan hasil yang luas, gunakan pekerjaan asinkron
• Batas dan Praktik Terbaik - Batas panggilan, pemfilteran, dan praktik terbaik.

Sebelum Anda dapat memperoleh data tentang kinerja iklan, Anda harus menyiapkan iklan Anda untuk melacak metrik yang Anda minati. Untuk itu, Anda dapat menggunakan Tanda URL, Meta Pixel, dan Conversions API.

Sebelum Anda memulai

Anda memerlukan:

• Izin ads_read.
• Aplikasi. Lihat Pengembangan Aplikasi Meta untuk informasi selengkapnya.

Statistik Kampanye

Untuk mendapatkan statistik kinerja 7 hari terakhir kampanye:

curl -G \
  -d "date_preset=last_7d" \
  -d "access_token=ACCESS_TOKEN" \
  "https://graph.facebook.com/API_VERSION/AD_CAMPAIGN_ID/insights"

Untuk mempelajari selengkapnya, lihat Referensi Insight Iklan.

Membuat Panggilan

Insights API tersedia sebagai sebuah edge pada objek iklan.

Permintaan

Anda dapat meminta kolom tertentu dengan daftar yang dipisahkan oleh koma di parameter fields. Contoh:

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"
    

Tanggapan

{
  "data": [
    {
      "impressions": "2466376",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Level

Agregat hasil pada level objek yang ditentukan. Data akan dideduplikasi secara otomatis.

Permintaan

Contoh: dapatkan insight kampanye pada level iklan.

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/CAMPAIGN_ID/insights"

Tanggapan

{
  "data": [
    {
      "impressions": "9708",
      "ad_id": "6142546123068",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "impressions": "18841",
      "ad_id": "6142546117828",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Jika Anda tidak memiliki akses ke semua objek iklan pada level yang diminta, maka panggilan insight tidak akan menghasilkan data. Contohnya: saat meminta insight dengan level diatur ke ad, jika Anda tidak memiliki akses ke satu atau beberapa objek iklan di bawah akun iklan tersebut, maka panggilan API ini akan menghasilkan kesalahan izin.

Jendela atribusi

Periode atribusi konversi menyediakan jangka waktu yang menjelaskan kapan kami mengatribusikan peristiwa ke iklan di aplikasi Meta. Untuk informasi latar belakang, lihat Pusat Bantuan Bisnis Meta, Tentang periode atribusi. Kami mengukur tindakan yang terjadi saat peristiwa konversi muncul dan melihatnya kembali dalam waktu 1 hari dan 7 hari. Untuk melihat tindakan yang diatribusikan ke periode atribusi yang berbeda, buat permintaan ke /{ad-account-id}/insights. Jika Anda tidak menyediakan action_attribution_windows, kami menggunakan 7d_click dan menyediakannya di bawah value.

Contoh: tentukan action_attribution_windows dan "nilai" ditetapkan di periode atribusi 7d_click. Buat permintaan ke act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view'] dan dapatkan hasil ini:

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

Perluasan Kolom

Minta kolom pada level node dan berdasarkan kolom yang sudah ditentukan di perluasan kolom.

Permintaan

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_ID"

Tanggapan

{
  "id": "6042542123268",
  "name": "My Website Clicks Ad",
  "insights": {
    "data": [
      {
        "impressions": "9708",
        "date_start": "2016-03-06",
        "date_stop": "2016-04-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Pengurutan

Urutkan hasil dengan menyediakan parameter sort dengan {fieldname}_descending atau {fieldname}_ascending:

Permintaan

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID/insights"

Tanggapan

{
  "data": [
    {
      "reach": 10742,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "reach": 5630,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-03"
    },
    {
      "reach": 3231,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-02"
    },
    {
      "reach": 936,
      "date_start": "2009-03-29",
      "date_stop": "2016-04-02"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Label Iklan

Statistik untuk semua label yang namanya identik. Teragregasi menjadi satu nilai pada level objek iklan. Lihat Referensi Label Iklan untuk informasi selengkapnya.

Permintaan

curl -G \  
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"

Tanggapan

{
  "data": [
    {
      "unique_clicks": 74,
      "cpm": 0.81081081081081,
      "total_actions": 49,
      "date_start": "2015-03-01",
      "date_stop": "2015-03-31",
    },
  ], 
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "MA==",
    }
  }
}

Definisi klik

Untuk lebih memahami metrik klik yang ditawarkan oleh Meta saat ini, silakan baca definisi dan penggunaan masing-masing di bawah ini:

• Klik Tautan, actions:link_click - Jumlah klik pada tautan iklan untuk memilih tujuan atau pengalaman, di dalam atau di luar properti milik Meta. Lihat Pusat Bantuan Iklan, Klik Tautan

• Klik (Semua), clicks - Metrik ini menghitung beberapa jenis klik pada iklan Anda, termasuk jenis interaksi tertentu dengan kontainer iklan, tautan ke tujuan lain, dan tautan ke pengalaman iklan yang diperluas. Lihat Pusat Bantuan Iklan, Klik (Semua)

Objek yang Dihapus dan Diarsipkan

Unit iklan dapat berupa DELETED atau ARCHIVED. Statistik objek yang dihapus atau yang diarsipkan akan muncul ketika Anda meng-kueri induknya. Artinya, jika Anda meng-kueri impressions pada level set iklan, maka hasil akan menyertakan impressions dari semua iklan di dalam set terlepas dari apakah iklan tersebut tengah dihapus atau diarsipkan. Lihat juga Menyimpan dan Mengambil Praktik Terbaik Objek Iklan.

Namun, jika Anda membuat kueri menggunakan pemfilteran, pemfilteran status akan diterapkan secara default untuk menampilkan objek Aktif saja. Sebagai hasilnya, statistik total dari node induk akan lebih besar daripada statistik turunannya.

Anda bisa mendapatkan statistik objek ARCHIVED dari node induknya, dengan cara menyediakan parameter filtering tambahan.

Permintaan

Untuk mendapatkan statistik semua iklan ARCHIVED di akun iklan yang terdaftar satu per satu:

curl -G \
  -d "level=ad" \
  -d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/insights/"

Tanggapan

Perhatikan bahwa hanya objek yang diarsipkan yang ditampilkan dalam tanggapan ini.

{
  "data": [
    {
      "impressions": "1741",
      "date_start": "2016-03-11",
      "date_stop": "2016-03-12"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Insight Objek yang Dihapus

Anda dapat meminta insight tentang objek yang dihapus jika Anda memiliki ID-nya atau dengan menggunakan filter ad.effective_status.

Permintaan

Contoh: jika Anda memiliki ID set iklan:

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID"
    

Di dalam contoh ini, kami meng-kueri dengan ad.effective_status:

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

Tanggapan

{
  "id": "6042147342661",
  "name": "My Like Campaign",
  "status": "DELETED",
  "insights": {
    "data": [
      {
        "impressions": "1741",
        "date_start": "2016-03-11",
        "date_stop": "2016-03-12"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Pemecahan Masalah

Waktu habis

Masalah paling umum yang menyebabkan kegagalan pada endpoint ini adalah karena terlalu banyak permintaan dan kehabisan waktu:

• Pada permintaan /GET atau sinkron, Anda dapat mengalami kesalahan karena memori atau waktu habis.
• Pada permintaan /POST atau asinkron, Anda mungkin mengalami kesalahan karena waktu habis. Untuk permintaan asinkron, ini memerlukan waktu hingga satu jam untuk menyelesaikan permintaan, termasuk percobaan ulang. Misalnya jika Anda membuat kueri yang mencoba mengambil data dalam jumlah besar untuk banyak objek pada level iklan.

Rekomendasi

• Tidak ada batasan eksplisit kapan kueri akan gagal. Jika kehabisan waktu, cobalah untuk memerinci kueri menjadi kueri yang lebih kecil dengan cara menaruhnya di filter seperti rentang tanggal.
• Metrik unik memerlukan waktu untuk dihitung. Cobalah untuk meng-kueri metrik unik di panggilan terpisah untuk meningkatkan kinerja metrik yang tidak unik.

Pembatasan Laju

Insights API Meta memanfaatkan pembatasan laju untuk memastikan pengalaman pelaporan yang optimal bagi partner kami. Untuk informasi dan saran selengkapnya, lihat Batas & Praktik Terbaik API Insight kami.

Perbedaan dengan Pengelola Iklan

Perilaku default API berbeda dari perilaku default di Pengelola Iklan. Jika Anda ingin melihat perilaku yang sama seperti di Pengelola Iklan, harap atur bidang use_account_attribution_setting ke true.

Pelajari Selengkapnya

• Insight Akun Iklan
• Insight Kampanye Iklan
• Insight Set Iklan
• Insight Iklan

Endpoint apa saja dalam daftar di atas tidak termasuk dalam API ini. Jika Anda berencana untuk menyertakan laporan dari Facebook dalam solusi Anda, lihat Ketentuan Platform Meta dan Kebijakan Developer untuk Marketing API.