Sekilas: API pelaporan kelompok memberi pemasang iklan cara terprogram untuk mendapatkan data Kelompok. Gunakan API untuk mengintegrasikan data Kelompok ke dalam BI dan sistem otomasi pemasaran.
API pelaporan kelompok
API pelaporan kelompok digunakan untuk mendapatkan data kinerja kampanye kelompok dari platform AppsFlyer. Ini secara fungsional setara dengan dashboard Kelompok.
Pertimbangan untuk pengembang
- Tanggal: Tanggal atau rentang tanggal mengacu pada tanggal nilai seumur hidup (LTV) , yang berarti tanggal pengguna diatribusikan (berkonversi) dan bukan tanggal aktivitas itu sendiri.
- Nilai Boolean: Benar atau salah (peka huruf besar-kecil).
- Lalu lintas agensi yang transparan dan tidak transparan: Sumber media dari lalu lintas yang didorong oleh agensi selalu berasal dari agensi dan bukan sumber media asli. Saat ini, kelompok versi UI berperilaku berbeda.
- Aplikasi tunggal: API Kelompok adalah solusi aplikasi tunggal. Hal ini berbeda dengan dashboard Kelompok yang mendukung banyak aplikasi dalam satu panggilan.
- Keaktualan data: Lihat ciri-ciri dan batasannya.
Instruksi API
Bagian tersebut berisi informasi yang diperlukan bagi Anda untuk membuat dan menggunakan API Kelompok.
Fakta API Kelompok
| Ringkasan | Panggilan API terdiri dari jalur, header, dan JSON yang berisi kueri data. Data dikembalikan secara default dalam file CSV. |
| Jalur |
|
| Parameter jalur (wajib) |
|
|
Parameter kueri (opsional) |
Hasil dikembalikan sebagai CSV atau JSON. Struktur file CSV berbentuk tabel sedangkan struktur file JSON berorientasi pada catatan. |
| Metode HTTP | POST |
| Jenis konten yang diterima | application/json |
| Otorisasi |
|
| Batasan tanggal |
|
| Batasan tingkat |
|
| Nilai Boolean | Selalu dalam huruf kecil: benar, salah |
Minta header
|
Kode |
Nilai | Wajib |
|---|---|---|
| Content-Type | application/json |
Ya |
| Authorization | Pembawa api_token_placeholder |
Ya |
| Terima | application/json |
Ya |
Memfilter dan mengelompokkan parameter
Gunakan parameter filter berikut untuk mendapatkan data yang diperlukan.
|
Nama parameter |
Deskripsi | Wajib |
|---|---|---|
|
cohort _type |
Jenis atribusi kelompok (konversi) adalah salah satu dari berikut ini:
|
Ya |
|
min_cohort_size |
Ukuran kelompok minimum digunakan untuk mengurangi jumlah catatan yang dikembalikan dengan mengecualikan kelompok yang memiliki sedikit pengguna. Artinya KPI pengguna memiliki nilai yang sama atau lebih besar dari yang ditentukan.
|
Tidak |
|
dari |
Batas bawah rentang tanggal atribusi LTV. Tanggal paling awal yang didukung adalah 720 hari sebelum tanggal saat ini.
|
Ya |
|
to |
Batas atas rentang tanggal atribusi LTV
|
Ya |
|
granularitas |
Perincian per jam untuk 72 jam sebelumnya dengan mengatur
"granularity": "hour",
"from": "2021-12-01 14:00:00", "to": "2021-12-03 11:00:00",
|
Tidak |
|
partial_data |
Untuk menghindari distorsi data dan salah tafsir, Kelompok mengembalikan data hari lengkap. Namun, data sebagian hari dapat bermanfaat. Jumlah hari kelompok lengkap untuk sebuah kueri dihitung sebagai selisih antara tanggal hari ini dan tanggal to .
Contoh: Pada tanggal 10 Mei, jumlah hari kelompok lengkap bagi pengguna yang melakukan konversi selama tanggal 1-30 April adalah 10.
Catatan: Data parsial hanya diperbolehkan jika jenis agregasi bersifat kumulatif. |
Tidak |
|
filter |
Filter data dan hari periode yang dikembalikan. Pilih filter dari daftar dimensi filter.
|
Tidak |
Gunakan parameter pengelompokan berikut untuk menyertakan kolom tambahan dan membuat laporan Anda tidak terlalu terperinci.
|
Parameter |
Nilai | Wajib |
|---|---|---|
|
pengelompokan |
|
Ya |
Memilih dan memformat KPI
- Tabel ini mencantumkan KPI yang tersedia dan fungsi terkaitnya. Saat Anda memanggil KPI, semua fungsinya kembali.
- KPI berikut selalu muncul: pengguna, ecpi, dan biaya
- Pilih satu KPI tambahan per panggilan.
| Fungsi | ||||||
|---|---|---|---|---|---|---|
| Default/ Opsional | KPI (Nama dimensi) | Hitung | cvr (rasio konversi) | Rating | Jumlah | Pengguna unik |
| Jumlah | Persentase | Persentase | Jumlah | Jumlah | ||
| Selalu | pengguna | Y | - | - | - | - |
| Selalu | ecpi | - | - | Y | - | - |
| Selalu | biaya | - | - | - | Y | - |
| Opsional | "event_name"(4) |
Y | Y | - | Y (3) | Y |
| Opsional | pendapatan | Y | - | - | Y | - |
| Opsional | ROAS | - | - | Y | - | - |
| Opsional | roi | - | - | Y | - | - |
| Opsional | sesi | Y | - | Y | - | Y(1) |
| Opsional | mencopot penginstalan (2) | Y | - | Y | - | - |
|
(1) Sesi unik kembali saat aggregation_type=on_day (2) Tidak tersedia ketika cohort_type=unified (3) Jumlah berarti total pendapatan yang dihasilkan oleh event tersebut. Dalam laporan, ini dilambangkan dengan (4) Catatan! Nama event peka huruf besar-kecil |
||||||
|
Parameter |
Nilai | Parameter wajib |
|---|---|---|
|
kpi |
Pilih satu KPI dari beberapa KPI yang tersedia. Di masa mendatang, kami berencana untuk mengizinkan pemilihan beberapa KPI.
|
Ya |
Presentasi fungsi KPI
Parameter format KPI berikut mengatur format KPI yang dikembalikan.
|
Parameter |
Nilai | Wajib |
|---|---|---|
|
preferred_currency |
Mata uang pendapatan KPI
|
Tidak |
|
preferred_timezone |
Zona waktu dari rentang data
|
Tidak |
|
aggregation_type |
|
Ya |
|
per_user |
Bagilah fungsi KPI dengan jumlah pengguna aplikasi. Hanya berlaku untuk KPI yang relevan.
|
Tidak |
Daftar kelompok dan filter berdasarkan dimensi
|
Nama dimensi |
Nilai API dimensi |
Pengelompokan |
Filter |
|---|---|---|---|
|
Iklan |
af_ad |
Y |
Y |
|
ID Iklan |
af_ad_id |
Y |
Y |
|
Kampanye |
c |
Y |
Y |
|
ID kampanye |
af_c_id |
Y |
Y |
|
Saluran |
af_channel |
Y |
Y |
|
Sumber Media |
pid |
Y |
Y |
|
Sub Param 1 |
af_sub1 |
Y |
Y |
|
Kata Kunci |
af_keywords |
Y |
Y |
|
Agensi |
af_prt |
Y |
Y |
|
Jenis Konversi (1) |
cohort _type |
Y |
Y |
|
ID Situs |
site_id |
Y |
Y |
|
Jenis Pendapatan (2) |
revenue_type |
x |
Y |
|
Jenis Sentuhan yang Diatribusikan (3) |
attributed_touch_type |
Y |
Y |
|
Adset |
af_adset |
Y |
Y |
|
ID Adset |
af_adset_id |
Y |
Y |
|
Negara |
geo |
Y |
Y |
|
Tanggal (tanggal penginstalan/atribusi ulang/interaksi ulang dalam konteks cohort_type yang dipilih) |
tanggal |
Y |
x |
|
Periode |
periode
|
x |
Y |
|
Catatan: Opsi dimensi: (1) Jenis Konversi:
(2) Jenis Pendapatan: click, impression, TV, pre-installed
|
|||
Contoh Curl
Contoh ini berisi panggilan API lengkap.
curl -L -X POST 'https://hq1.appsflyer.com/api/cohorts/v1/data/app/<insert your app_id here>?format=<insert results format here>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <cohort_api_token_placeholder. Note the token has more than 700 characters.>' \
-H 'Accept: application/json' \
--data-raw '{
"cohort_type": "user_acquisition",
"min_cohort_size": 1,
"preferred_timezone": false,
"from": "2020-01-01",
"to": "2020-01-31",
"filters": {
"period": [
0,
1,
2,
10,
30,
60
],
"geo": [
"US",
"CN"
],
"pid": [
"Meta ads",
"googleadwords_int"
]
},
"preferred_currency": true,
"aggregation_type": "on_day",
"per_user": false,
"groupings": [
"pid",
"date"
],
"kpis": [
"sessions"
]
}'
Contoh python
import http.client
import mimetypes
conn = http.client.HTTPSConnection("hq1.appsflyer.com")
payload = "{\r\n \"cohort_type\": \"user_acquisition\",\r\n \"min_cohort_size\": 1,\r\n \"preferred_timezone\": false,\r\n \"from\": \"2020-05-01\",\r\n \"to\": \"2020-05-10\",\r\n \"preferred_currency\": true,\r\n \"aggregation_type\": \"cumulative\",\r\n \"per_user\": false, \r\n \"groupings\": [\r\n \"pid\",\r\n \"date\"\r\n ],\r\n \"kpis\": [\r\n \"roas\"\r\n ]\r\n}"
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer [Enter token here]',
'Accept': 'application/json',
'Content-Type': 'application/json'
}
conn.request("POST", "/api/cohorts/v1/data/app/[My App ID here]?format=csv", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Contoh kasus penggunaan
Contoh 1: Retensi
Retensi sumber media (sesi) pengguna yang menginstal aplikasi selama bulan Januari pada hari ke 7, 14, dan 28
{
"per_user": false,
"groupings": [
"c"
],
"filters": {
"period": [
7, 14, 28
]
},
"partial_data": false,
"aggregation_type": "cumulative",
"min_cohort_size": 1,
"cohort_type": "user_acquisition",
"from": "2021-01-01",
"to": "2021-01-30",
"kpis": [
"Checkout Start"
]
}Contoh 2: Pembelian kampanye
Pendapatan per kampanye kelompok hari ke-3 setelah penginstalan
{
"per_user": false,
"groupings": [
"c"
],
"filters": {
"period": [
3
],
"c":[
"example_campaign_name"
]
},
"partial_data": false,
"aggregation_type": "cumulative",
"min_cohort_size": 1,
"cohort_type": "user_acquisition",
"from": "2021-01-01",
"to": "2021-01-30",
"kpis": [
"Checkout Start"
]
}Contoh 3: Aktivitas kemarin
Aktivitas apa yang dilakukan pengguna yang melakukan konversi (menginstal, berinteraksi kembali, mengatribusikan ulang) selama periode konversi tertentu kemarin?
Gunakan data yang tersedia melalui Kelompok untuk Data Locker. Periode konversi dibatasi hingga 360 hari sebelumnya.
Informasi tambahan
Kode respons dan pemecahan masalah
|
Kode respons |
Pesan |
Komentar |
|---|---|---|
| 200 | OK |
Data valid dikembalikan |
| 200 | OK |
|
| 401 | Tidak berwenang |
|
| 404 | Tidak ditemukan |
|
| 422 | Entitas yang tidak dapat diproses |
Alasan umum untuk kode kesalahan ini adalah:
|
Struktur nama file CSV
Nama yang dialokasikan ke file CSV yang dikembalikan dihasilkan dari kueri API. Strukturnya dirinci pada tabel berikut.
Contoh nama file CSV
cohort_aggregation_type_per_user_kpi_report_app_id_from_to_timezone_currency_hash.csv| Variabel | Nilai yang mungkin |
|---|---|
| aggregation_type |
|
| per_user |
|
| kpi | Contoh: sesi |
| app_id | ID aplikasi diminta |
| from | from tanggal: format hh-bb-tttt |
| to | to tanggal: format hh-bb-tttt |
| timezone | Zona waktu default UTC |
| currency | Kode mata uang default USD |
| hash |
Panjang string hash alfanumerik=5 |
Menggunakan filter periode
Periode mengacu pada hari setlah atribusi, dimana periode 0 adalah hari atribusi. Misalnya, pengguna menginstal aplikasi pada tanggal 1 Januari. Ini adalah hari atribusi. Pembelian yang dilakukan pada periode 0 berarti dilakukan pada tanggal 1 Januari. Pembelian yang dilakukan pada periode 3 berarti dilakukan pada tanggal 4 Januari. Demikian pula, pengguna yang menginstal pada tanggal 11 Januari, ini adalah periode 0. Pembelian yang dilakukan pada tanggal 14 Januari akan menjadi periode 3.
Jika rentang tanggal laporan Anda adalah 1 Januari hingga 11 Januari, pengguna yang mengatribusikan (menginstal) selama periode ini akan disertakan dalam laporan. Tidak ada data lain yang disertakan.
- Nilai periode dapat berupa satu atau lebih dari 0-180 berikut ini. Misalnya 0, 1, 2, 30, 180.
- Jika tidak ada periode yang ditentukan, nilai default 0, 1, 2, dan seterusnya hingga 30, 60, 90, dan 180 akan dikembalikan.
Contoh filter periode
- Contoh ini berisi parameter kueri JSON, data lengkap, dan file CSV yang dihasilkan.
- Kueri periode filter 0, 1, dan 2 dan KPI yang dipilih adalah revenue.
- Hasilnya, data yang dikembalikan berisi:
- Ukuran pengguna, biaya, dan ecpi yang selalu kembali
- Ukuran pendapatan yang terdiri dari penjumlahan dan penghitungan untuk setiap periode yang berarti periode 0, 1, dan 2.
Kueri
{
"cohort_type": "user_acquisition",
"min_cohort_size": 1,
"preferred_timezone": false,
"from": "2019-12-01",
"to": "2020-01-01",
"filters": {
"period": [
0,
1,
2
]
},
"aggregation_type": "on_day",
"per_user": false,
"groupings": [
"pid"
],
"kpis": [
"revenue"
]
}
Data Lengkap
Hasil
Pemetaan antarmuka pengguna ke parameter API
Gambar berikut memetakan antarmuka pengguna analitik Kelompok ke parameter API. Kedua solusi - API dan antarmuka pengguna serupa tetapi tidak identik.
Versi API memiliki opsi tambahan berikut:
- Pilihan mata uang
- Pilihan zona waktu
- Pemfilteran berdasarkan periode
Perbedaan antara jenis agregasi
Karakteristik dan batasan
| Sifat | Catatan |
|---|---|
| Akses jaringan iklan |
Tidak. Mitra pengelolaan kampanye dapat menggunakan API jika pemasang iklan memberikan izin. |
| Akses agensi | Tidak |
| Transparansi agensi | Tidak didukung |
| Zona waktu khusus aplikasi | Ya |
| Mata uang khusus aplikasi | Ya |
| Keterbatasan ukuran | Tidak ada |
| Batasan tingkat |
Batas tarif panggilan API: 60 panggilan per menit per akun |
| Data organik | Tersedia |
| Data non-organik | Tersedia |
| Batasan data biaya |
|
| Keaktualan data |
Keaktualan data bergantung pada partial_data sebagai berikut:
|
| Data historis | Kelompok harian: 2 tahun |
| Akses pengguna akun | Token otorisasi tersedia untuk pengguna admin di dashboard |
| Pendapatan Iklan |
Untuk event af_ad_revenue, metrik pengguna unik tidak tersedia jika jenis agregasinya adalah "pada hari", untuk tanggal antara 5 Oktober 2022-16 Februari 2023. |
| Pengelompokan mingguan dan bulanan |
Pengelompokan dimensi mingguan dan bulanan tidak tersedia dengan API Kelompok. Gunakan dashboard Kelompok. |
| API Kohort |
|