Agen Pengguna Aplikasi
Sebagai bagian dari upaya kami yang lebih luas untuk memerangi spam, kami telah mengembangkan spesifikasi standar untuk header Agen Pengguna yang dikirim oleh produk analisis/iklan atas nama pengguna aplikasi. Agen Pengguna aplikasi dapat berasal dari kode native untuk mematuhi spesifikasi berikut:
name version (os_and_version; locale; device; build; Proxy)
Definisi kolom ini adalah sebagai berikut:
Komponen Agen-Pengguna | |
---|---|
name | Nama produk analisis/iklan. ( Perhatikan bahwa jika agen pengguna dibuat di sisi klien, Android// Specified by API consumer. iOS// Specified by API consumer. |
version | Versi produk analisis/iklan.
( Android// Specified by API consumer. iOS// Specified by API consumer. |
os_and_version | Versi sistem operasi dan sistem operasi tempat
aplikasi dijalankan. ( AndroidString osAndVersion = "Android " + Build.VERSION.RELEASE; iOSUIDevice *uid = [UIDevice currentDevice]; NSString *osAndVersion = [NSString stringWithFormat:@"%@ %@", [uid systemName], [uid systemVersion]]; |
locale | Tag lokal IETF untuk perangkat, yang menggunakan bahasa
dua huruf dan kode negara yang dipisahkan oleh garis bawah.
( AndroidString locale = Locale.getDefault(); iOSNSString *locale = [[NSLocale currentLocale] localeIdentifier] |
device | Nama perangkat fisik yang menjalankan produk analisis/iklan.
( AndroidString device = Build.MODEL; iOS@import Darwin.sys.sysctl; NSString *device(void) { size_t bufferSize = 64; NSMutableData *buffer = [[NSMutableData alloc] initWithLength:bufferSize]; int status = sysctlbyname("hw.machine", buffer.mutableBytes, &bufferSize, NULL, 0); if (status != 0) { return nil; } return [[NSString alloc] initWithCString:buffer.mutableBytes encoding:NSUTF8StringEncoding]; } |
build | "Build/" diikuti dengan nomor build sistem
operasi.
( AndroidString build = "Build/" + Build.ID; iOS@import Darwin.sys.sysctl; NSString *build(void) { size_t bufferSize = 64; NSMutableData *buffer = [[NSMutableData alloc] initWithLength:bufferSize]; int status = sysctlbyname("kern.osversion", buffer.mutableBytes, &bufferSize, NULL, 0); if (status != 0) { return nil; } return [[NSString alloc] initWithCString:buffer.mutableBytes encoding:NSUTF8StringEncoding]; } |
Hanya sertakan ; Proxy
di akhir aplikasi User-Agent saat membuat
sisi server Agen Pengguna aplikasi. Jika Agen Pengguna aplikasi sepenuhnya dibuat di
sisi klien, kecualikan ; Proxy
. Dengan demikian, Agen Pengguna aplikasi dapat:
- Android:
AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M; Proxy)
- iOS:
AdMob/7.10.1 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
Permintaan Tracking Konversi
Tujuan permintaan tracking konversi adalah untuk memberi tahu Google Ads tentang peristiwa aplikasi yang harus dilacak sebagai konversi dan/atau digunakan untuk mengisi daftar pemasaran ulang, dan untuk mengambil metadata yang menjelaskan klik yang terjadi sebelum peristiwa.
Semua panggilan API dilakukan ke domain www.googleadservices.com
. Permintaan
konversi adalah permintaan POST
melalui HTTPS di jalur berikut:
/pagead/conversion/app/versiondengan version adalah versi API tracking konversi yang dimaksud. Saat ini, satu-satunya versi yang valid adalah
1.0
.
Permintaan konversi aplikasi standar akan berisi parameter berikut.
Permintaan Tracking Konversi | |
---|---|
dev_token |
Wajib Lokasi: Kueri Token developer statis unik yang dikeluarkan untuk konsumen API. Z_eErE4DkvcKjDM1OVE4c4 |
link_id |
Wajib Lokasi: Kueri ID link yang mengikat token developer konsumen API ke aplikasi tertentu. 31FF8D67E5BB5DD5029DCC2734C2F884 |
app_event_type |
Wajib Lokasi: Kueri Nama peristiwa aplikasi yang terjadi. Kolom ini adalah enumerasi, dan hanya akan menerima nilai berikut: • first_open • session_start • in_app_purchase • view_item_list • view_item • view_search_results • add_to_cart • ecommerce_purchase • custom Peristiwa |
app_event_name |
Wajib dalam kondisi tertentu Lokasi: Kueri Nama peristiwa aplikasi kustom yang tidak diterima di kolom level_achieved Level Achieved Kolom ini tidak boleh berisi nilai apa pun yang dicadangkan untuk
|
app_event_data |
Opsional Lokasi: Isi Teruskan semua data peristiwa kaya tambahan sebagai string pemetaan objek JSON sederhana ke nilai. Nilai yang dapat diterima adalah string dan array string. {"level": 5, "attempts": 20} |
rdid |
Wajib Lokasi: Kueri String UUID yang valid yang mewakili ID perangkat mentah. f10e1de2-e237-4f50-b6aa-843c45cc63d6 Jika ID perangkat tidak ada, misalnya ID perangkat dari pengguna yang tidak memberi izin ATT, tetapkan sebagai nol. 00000000-0000-0000-0000-000000000000 |
id_type |
Wajib Lokasi: Kueri Jenis ID yang disimpan di kolom Androidadvertisingid iOSidfa |
lat |
Wajib Lokasi: Kueri Status pelacakan iklan batas untuk perangkat.
|
app_version |
Wajib Lokasi: Kueri Versi aplikasi saat ini. Ini seharusnya distandardisasi sebagai berikut. AndroidpackageManager.getPackageInfo(packageName(), PackageManager.GET_META_DATA).versionName iOS[[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleShortVersionString"] 1.2.4 |
os_version |
Wajib Lokasi: Kueri Versi OS host aplikasi saat ini. Ini harus distandardisasi sebagai berikut. Androidandroid.os.Build.VERSION.RELEASE iOS[[UIDevice currentDevice] systemVersion] |
sdk_version |
Wajib Lokasi: Kueri Versi SDK yang mengukur peristiwa. Karena digunakan terutama untuk
debug, versi harus mencerminkan versi rilis persis seperti yang dipublikasikan
dengan rilis SDK Anda. Jika aplikasi tidak menggunakan SDK, teruskan nilai
yang sama seperti 1.9.5r6 |
timestamp |
Wajib Lokasi: Kueri Stempel waktu UNIX saat peristiwa konversi terjadi, dalam detik dengan presisi hingga mikrodetik. 1432681913.123456 |
value |
Opsional Lokasi: Kueri Nilai uang dari peristiwa, jika ada. Ini harus selalu diformat sebagai nilai floating point yang dapat dibaca mesin menggunakan titik desimal untuk memisahkan bilangan bulat dan bagian pecahan dari nilai. 1.99 |
currency_code |
Wajib dalam kondisi tertentu Lokasi: Kueri Kode mata uang ISO 4217 untuk parameter USD |
gclid |
Wajib dalam kondisi tertentu Lokasi: Kueri Nilai parameter kueri Cj0KEQjw0dy4BRCuuL_e5M |
market_referrer_gclid |
Wajib dalam kondisi tertentu Lokasi: Kueri Nilai parameter kueri BX3QojHp4mY5MrJtFM_d1u |
gclid_only_request |
Wajib dalam kondisi tertentu Lokasi: Kueri ID untuk atribusi berbasis 1 |
gbraid |
Wajib dalam kondisi tertentu Lokasi: Kueri Terakhir dilihat nilai ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O |
app_open_source |
Wajib dalam kondisi tertentu Lokasi: Kueri Nilai untuk mengidentifikasi deep link klik iklan atau sesi aplikasi organik. ad_click or organic |
User-Agent |
Wajib Lokasi: Header Agen pengguna aplikasi seperti yang dijelaskan di bagian sebelumnya. AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M) |
X-Forwarded-For |
Wajib Lokasi: Header Alamat IPv4 atau IPv6 publik perangkat tempat peristiwa diukur. 216.58.194.174 |
Semua permintaan harus dikirim melalui HTTPS. Ping yang diterima melalui HTTP akan ditolak.
Perhatikan bahwa jika isi permintaan kosong (jika tidak ada data peristiwa lengkap yang diteruskan dalam payload app_event_data
), server kami mengharuskan Anda menetapkan header Content-Length: 0
secara eksplisit pada permintaan.
Contoh Permintaan
Contoh permintaan tracking konversi yang valid dengan jenis peristiwa non-kustom dan informasi pendapatan adalah:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=in_app_purchase &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfa &lat=0 &app_version=1.2.4 &os_version=9.3.2 &sdk_version=1.9.5r6 ×tamp=1432681913.123456 &value=1.99 ¤cy_code=USD Host: www.googleadservices.com User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy) X-Forwarded-For: 216.58.194.174 Content-Type: application/json; charset=utf-8
{"app_event_data":{"item_id":["Crayons","Markers"]}}
Contoh permintaan tracking konversi yang valid dengan jenis peristiwa non-kustom dan informasi pendapatan dengan rdid (advertisingid) tidak tersedia adalah:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=in_app_purchase &rdid=00000000-0000-0000-0000-000000000000 &id_type=advertisingid &lat=1 &app_version=1.2.4 &os_version=9.3.2 &sdk_version=1.9.5r6 ×tamp=1432681913.123456 &value=1.99 ¤cy_code=USD &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u &gclid=Cj0KEQjw0dy4BRCuuL_e5M &gclid_only_request=1 Host: www.googleadservices.com User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; Android,1; Build/13D15; Proxy) X-Forwarded-For: 216.58.194.174 Content-Type: application/json; charset=utf-8
{"app_event_data":{"item_id":["Crayons","Markers"]}}
Contoh permintaan awal sesi yang valid adalah:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=session_start &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfa &lat=0 &app_version=1.2.4 &os_version=9.3.2 &sdk_version=1.9.5r6 ×tamp=1432681913.123456 Host: www.googleadservices.com User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy) X-Forwarded-For: 216.58.194.174 Content-Type: application/json; charset=utf-8
Contoh permintaan atribusi ulang awal sesi yang valid untuk sesi
yang dimulai dari deep link
example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M
adalah:
POST /pagead/conversion/app/1.0 ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=session_start &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfa &lat=0 &app_version=1.2.4 &os_version=9.3.2 &sdk_version=1.9.5r6 ×tamp=1432681913.123456 &gclid=Cj0KEQjw0dy4BRCuuL_e5M Host: www.googleadservices.com User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy) X-Forwarded-For: 216.58.194.174 Content-Type: application/json; charset=utf-8
Encoding Data Peristiwa
Untuk parameter isi app_event_data
, gunakan konvensi berikut untuk jenis data primitif:
Mengambang
- Gunakan karakter titik sebagai pemisah desimal terlepas dari pelokalan aplikasi
- Gunakan presisi desimal dua digit untuk mewakili nilai moneter. Misalnya, 2,99
- Jangan menggunakan notasi eksponensial, misalnya 2E+9
- Jangan gunakan karakter koma untuk memisahkan kelompok digit, misalnya 1.000.000
- Contoh yang valid:
-0.5
2.99
1000000.123
Integer
- Hanya kirimkan nilai bilangan bulat tanpa digit desimal
- Jangan gunakan karakter koma untuk memisahkan kelompok digit, misalnya 1.000. 000
- Contoh yang valid:
1000
-11
0
Tanggal
- Format tanggal: yyyy-mm-dd
yyyy
= tahun empat digit, mis. 2016mm
= bulan dua digit, misalnya 09 untuk Septemberdd
= hari dua digit, misalnya 23 untuk hari ke-23
- Selalu kirim jumlah digit yang ditentukan di atas, mis. jika mengirim nilai untuk dd untuk hari ke-5 pada bulan tersebut, kirim
05
. - Contoh yang valid:
"2016-09-23"
"1990-12-31"
- Format tanggal: yyyy-mm-dd
Stempel waktu
- Format waktu: Stempel waktu Unix/Epoch ditentukan dalam zona waktu UTC dengan presisi hingga mikrodetik
- Contoh yang valid:
1478713087
untuk Rab, 09 Nov 2016 17.38.07 GMT1073513982.123000
untuk Rab, 07 Jan 2004 22:19:42.123 GMT
Array
- Hanya kirim array nilai primitif (string, angka, dan boolean)
- Contoh yang Valid:
[123, 456, 789]
["abc"]
Respons Tracking Konversi
Respons tracking konversi memiliki format berikut:
{ "ad_events": [<ad event objects>], "errors": [<error strings>], "attributed": true|false }
Array ad_events dan errors mungkin kosong.
Kami memperkirakan error tersebut akan menjadi kode error yang dapat dibaca mesin, mis., invalid_timestamp
.
Peristiwa iklan adalah objek inti dari atribusi aplikasi, dan akan berisi properti berikut.
Respons Tracking Konversi | |
---|---|
ad_event_id |
Selalu ada string
Q2owS0VRancwZHk0QlJDdXVMX2U1TQ |
conversion_metric |
Selalu ada string Metrik konversi yang digunakan untuk atribusi. Awalnya kami akan mendukung satu metrik konversi. conversion |
timestamp |
Selalu ada number Stempel waktu UNIX saat peristiwa iklan terjadi, dalam detik dengan presisi hingga mikrodetik. Nilai ini harus digunakan untuk atribusi klik terakhir. 1432681913.123456 |
campaign_type |
Selalu ada string Kolom ini akan mengidentifikasi jenis kampanye yang menghasilkan peristiwa iklan. Kemungkinan nilainya adalah sebagai berikut. ACI ACE Search Display Video Shopping Hotel Performance_Max Other ACI adalah singkatan dari App Campaign for Install. ACE adalah singkatan dari App Campaigns for Engagement. |
campaign_id |
Selalu ada number ID kampanye numerik dari kampanye yang menghasilkan peristiwa iklan. Nilai ini dijamin unik. 123456789 |
campaign_name |
Selalu ada string Nama kampanye yang ditentukan pengiklan dari kampanye yang menghasilkan peristiwa iklan. Nilai ini tidak dijamin unik. Occasional Gamers (Video) |
ad_type |
Selalu ada string Jenis iklan yang menghasilkan peristiwa iklan. Nilai ini dapat digunakan untuk membedakan berbagai jenis inventaris sebagai berikut. Promosi AplikasiClickToDownloadEngagement Aplikasi AppDeepLinkEngagement Aplikasi — Alur Instal dan Lanjutkan AppDeepLinkContinueGenerik untuk nilai lainnya Unknown |
external_customer_id |
Selalu ada number ID pengiklan untuk pengiklan yang memiliki kampanye yang menghasilkan peristiwa iklan. Nilai ini dapat digunakan untuk membedakan akun Google Ads. 123456789 |
location |
Selalu ada number Kode ID lokasi untuk lokasi geografis peristiwa iklan. Lihat referensi Google Ads API untuk menafsirkan kode lokasi. |
network_type |
Selalu ada string Kolom ini akan mengidentifikasi jaringan iklan Google Ads tempat peristiwa iklan terjadi. Kemungkinan nilainya adalah sebagai berikut. Search Display YouTube |
network_subtype |
Akan menjadi string Kolom ini akan mengidentifikasi "subjenis" jaringan iklan Google Ads tempat peristiwa iklan terjadi. Nilai yang memungkinkan dapat bervariasi menurut jenis jaringan utama. PenelusuranGoogle Penelusuran BiasaGoogleSearchPartner Penelusuran Google SearchPartners LayarPenayang Web SelulermGDNPenayang Aplikasi Google AdMob YouTubeJaringan Video YouTubeYouTubeVideosJaringan Penelusuran YouTube YouTubeSearchVideo Partner VideoPartners |
video_id |
Hanya diberikan jika string ID video YouTube yang terkait dengan peristiwa iklan. dQw4w9WgXcQ |
keyword |
Hanya diberikan jika string Kata kunci penelusuran yang terkait dengan peristiwa iklan. +food +delivery |
match_type |
Hanya diberikan jika string Jenis pencocokan untuk kata kunci penelusuran. PersiseFrasa pLuas b |
placement |
Hanya diberikan jika string Penempatan yang terkait dengan peristiwa iklan. mobileapp::1-343200656 |
ad_group_id |
Selalu ada number ID numerik grup iklan yang dihasilkan dengan peristiwa iklan. Nilai ini dijamin unik. 123456789 |
ad_group_name |
Hanya diberikan jika string Nama grup iklan yang ditentukan pengiklan dari grup iklan yang menghasilkan peristiwa iklan. Nilai ini tidak dijamin unik. My App AdGroup |
creative_id |
Hanya diberikan jika number ID numerik unit iklan materi iklan yang menghasilkan peristiwa iklan. Nilai ini dijamin unik. 123456789 |
interaction_type |
Kolom ini akan selalu berupa engagement. string |
Respons Contoh
Contoh respons tracking konversi jika permintaan berisi error adalah:
{ "ad_events": [], "errors": ["INVALID_CURRENCY_CODE"], "attributed": false }
Contoh respons tracking konversi negatif adalah:
{ "ad_events": [], "errors": [], "attributed": false }
Respons tracking konversi akan ditampilkan untuk semua permintaan tracking konversi.
Contoh respons tracking konversi afirmatif untuk Kampanye Aplikasi Universal adalah:
{ "ad_events": [{ "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ", "conversion_metric": "conversion", "interaction_type": "engagement", "campaign_type": "ACI", "campaign_id": 123456789, "campaign_name": "My App Campaign", "ad_type": "ClickToDownload", "external_customer_id": 123456789, "location": 21144, "network_type": "Search", "network_subtype": "GoogleSearch", "video_id": null, "keyword": null, "match_type": null, "placement": null, "ad_group_id": null, "ad_group_name": "", "creative_id": null, "timestamp": 1432681913.123456 }], "errors": [], "attributed": true }
Contoh respons tracking konversi afirmatif untuk kampanye Penelusuran adalah:
{ "ad_events": [{ "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ", "conversion_metric": "conversion", "interaction_type": "engagement", "campaign_type": "Search", "campaign_id": 123456789, "campaign_name": "My App Campaign", "ad_type": "ClickToDownload", "external_customer_id": 123456789, "location": 21144, "network_type": "Search", "network_subtype": "GoogleSearch", "video_id": null, "keyword": "+space +birds", "match_type": "b", "placement": null, "ad_group_id": 123456789, "ad_group_name": "My App AdGroup", "creative_id": 123456789, "timestamp": 1432681913.123456 }], "errors": [], "attributed": true }
Contoh respons tracking konversi afirmatif untuk kampanye Display adalah:
{ "ad_events": [{ "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ", "conversion_metric": "conversion", "interaction_type": "engagement", "campaign_type": "Display", "campaign_id": 123456789, "campaign_name": "My App Campaign", "ad_type": "ClickToDownload", "external_customer_id": 123456789, "location": 21144, "network_type": "Display", "network_subtype": "mGDN", "video_id": null, "keyword": null, "match_type": null, "placement": "mobile-app::2-343200656", "ad_group_id": 123456789, "ad_group_name": "My App AdGroup", "creative_id": 123456789, "timestamp": 1432681913.123456 }], "errors": [], "attributed": true }
Contoh respons tracking konversi afirmatif untuk kampanye YouTube adalah:
{ "ad_events": [{ "ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ", "conversion_metric": "conversion", "interaction_type": "engagement", "campaign_type": "Video", "campaign_id": 123456789, "campaign_name": "My App Campaign", "ad_type": "ClickToDownload", "external_customer_id": 123456789, "location": 21144, "network_type": "YouTube", "network_subtype": "YouTubeVideos", "video_id": "dQw4w9WgXcQ", "keyword": null, "match_type": null, "placement": null, "ad_group_id": 123456789, "ad_group_name": "My App AdGroup", "creative_id": 123456789, "timestamp": 1432681913.123456 }], "errors": [], "attributed": true }
Permintaan Atribusi Lintas Jaringan
Saat Google Ads merespons permintaan tracking konversi secara afirmatif, konsumen API harus memberi tahu Google Ads tentang keputusan atribusi lintas-jaringan setelah mengidentifikasi klik terakhir.
Permintaan atribusi lintas-jaringan identik dengan permintaan tracking konversi asli, tetapi dengan jalur permintaan:
/pagead/conversion/app/1.0/cross_network
dan penambahan dua parameter yang diperlukan:
Permintaan Atribusi Lintas Jaringan | |
---|---|
ad_event_id |
Wajib Lokasi: Kueri ID |
attributed |
Wajib Lokasi: Kueri Apakah Google Ads menerima kredit untuk konversi oleh konsumen API atau tidak. |
Contoh permintaan atribusi lintas-jaringan yang valid adalah:
POST /pagead/conversion/app/1.0/cross_network ?dev_token=Z_eErE4DkvcKjDM1OVE4c4 &link_id=31FF8D67E5BB5DD5029DCC2734C2F884 &app_event_type=custom &app_event_name=level_achieved &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D &id_type=idfa &lat=0 &app_version=1.2.4 &os_version=9.3.2 &sdk_version=1.9.5r6 ×tamp=1432681913.123456 &value=1.99 ¤cy_code=USD &ad_event_id=Q2owS0VRancwZHk0QlJDdXVMX2U1TQ &attributed=1 Host: www.googleadservices.com User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy) X-Forwarded-For: 216.58.194.174 Content-Type: application/json; charset=utf-8
Permintaan atribusi lintas-jaringan yang valid akan selalu menerima respons 200 umum tanpa isi respons.