Penargetan Agen Pengguna

Header User-Agent secara historis telah disertakan dalam permintaan bid untuk memberikan data penargetan yang berguna seperti browser dan platform perangkat yang memulai. Namun, browser sering kali sangat menyamarkan Agen Pengguna karena kesulitan penggunaannya dan untuk melindungi privasi pengguna dengan lebih baik. Untuk merespons hal ini, Google mendukung Petunjuk Klien Agen Pengguna, yang disertakan dalam permintaan bid jika tersedia untuk melengkapi header Agen Pengguna. Petunjuk Klien ini (singkatnya) dapat bersumber dari header Sec-Ch-UA* atau dari JavaScript Client Hints API.

Bergantung pada protokol yang digunakan, header Agen Pengguna diekspos dengan salah satu kolom string berikut:

• Google: BidRequest.user_agent
• OpenRTB: BidRequest.device.ua

Pesan UserAgent akan diisi dengan Petunjuk Klien jika tersedia, tetapi akan diisi berdasarkan nilai yang diuraikan dari header Agen Pengguna. Bergantung pada protokol yang digunakan, kolom ini akan ditampilkan sebagai salah satu kolom berikut:

• Google: BidRequest.user_agent_data
• OpenRTB: BidRequest.device.sua

Bidder sangat dianjurkan untuk menggunakan pesan UserAgent, bukan string Agen Pengguna.

Cara UserAgent diisi

Tidak seperti header Agen Pengguna, pesan UserAgent mewakili informasi agen pengguna yang dibagi menjadi beberapa kolom untuk informasi tertentu.

Bergantung pada apakah Petunjuk Klien tersedia dalam permintaan iklan, pesan UserAgent dapat diisi dengan cara berikut:

• Jika permintaan berisi setidaknya Petunjuk Klien entropi rendah, UserAgent akan diisi berdasarkan kontennya.
• Jika permintaan hanya berisi header Agen Pengguna, UserAgent akan diisi berdasarkan apa yang dapat diurai dari header.

Catatan: Kolom source dapat digunakan untuk membedakan apa yang digunakan untuk mengisi UserAgent. Misalnya, jika ditetapkan ke USER_AGENT_STRING, itu akan menunjukkan bahwa UserAgent diisi berdasarkan konten header Agen Pengguna.

Contoh: Mengisi UserAgent berdasarkan header Agen Pengguna

Misalkan ada permintaan iklan yang dikirim browser untuk header berikut:

User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
            AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36

UserAgent yang diisi hanya berdasarkan header Agen Pengguna mungkin terlihat seperti berikut:

browsers: [{ brand: "Mozilla", version: ["5", "0"] },
           { brand: "AppleWebKit", version: ["537", "36"] },
           { brand: "Chrome", version: ["103", "0", "0", "0"] },
           { brand: "Safari", version: ["537", "36"] }],
platform: { brand: "Windows NT", version: ["10", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
model: "x64",
source: USER_AGENT_STRING

Contoh: Mengisi UserAgent berdasarkan Petunjuk Klien

Misalkan ada permintaan iklan yang dikirim browser untuk header berikut:

User-Agent:                 Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                            AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36
Sec-Ch-Ua:                  ".Not/A)Brand";v="99", "Google Chrome";v="103", "Chromium";v="103"
Sec-Ch-Ua-Arch:             x86
Sec-Ch-Ua-Full-Version:     103.0.5060.134
Sec-Ch-Ua-Mobile:           ?0
Sec-Ch-Ua-Platform:         Windows
Sec-Ch-Ua-Platform-Version: 15.0.0

Jika setidaknya Petunjuk Klien dengan entropi rendah disertakan, UserAgent akan diisi berdasarkan konten header tersebut meskipun header Agen Pengguna ada. URL tersebut akan terlihat seperti berikut:

browsers: [{ brand: ".Not/A)Brand", version: ["99", "0", "0", "0"] },
           { brand: "Google Chrome", version: ["103", "0", "5060", "134"] },
           { brand: "Chromium", version: ["103", "0", "5060", "134"] }],
platform: { brand: "Windows", version: ["15", "0", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
source: CLIENT_HINTS_HIGH_ENTROPY

Mengisi berdasarkan header Agen Pengguna versus Petunjuk Klien

Beberapa kolom diisi secara berbeda, bergantung pada apakah kolom tersebut didasarkan pada header Agen Pengguna atau Petunjuk Klien. Berikut ringkasan perbedaan tersebut:

• Untuk browser dan platform yang identik, UserAgent.browsers.brand dan UserAgent.platform.brand akan sering berbeda di antara UserAgent berdasarkan header Agen Pengguna atau Petunjuk Klien. Misalnya, UserAgent.platform.brand mungkin muncul sebagai “Windows NT” jika didasarkan pada header Agen Pengguna, atau “Windows” jika didasarkan pada Petunjuk Klien.
• Beberapa entri UserAgent.browsers bersifat unik untuk header Agen Pengguna atau Petunjuk Klien. Misalnya, "AppleWebKit" akan muncul jika UserAgent didasarkan pada header Agen Pengguna, sedangkan "Chromium" hanya akan muncul jika didasarkan pada Petunjuk Klien.
• Hanya UserAgent berdasarkan header Agen Pengguna yang dapat berisi nilai yang dibekukan. Misalnya, jika platformnya adalah Windows 11 22H2, UserAgent.platform.brand akan ditetapkan ke “Windows NT” dan UserAgent.platform.version akan ditetapkan ke [“10”, “0”] karena ini adalah nilai yang dibekukan untuk semua versi Windows pada atau di atas 10.

Data dalam UserAgent yang didasarkan pada Petunjuk Klien biasanya tidak akan menjadi pengganti informasi yang dibekukan atau disamarkan. Jika ada inkonsistensi antara header Agen Pengguna dan UserAgent berdasarkan Petunjuk Klien, informasi dari UserAgent harus dipilih.

Kolom objek UserAgent

Bagian ini merangkum setiap kolom, dengan fokus pada perilaku dan praktik terbaik khusus RTB Google untuk penggunaan.

Browser

Berisi daftar entri BrandVersion yang umumnya diurutkan berdasarkan kekhususan–misalnya, jika Anda mencantumkan konten browsers, brand untuk setiap entri dapat muncul dalam urutan berikut:

Merek	Meaning
Mozilla	Kompatibel dengan Mozilla
AppleWebKit	Berbasis AppleWebKit, subset dari Mozilla.
Chrome	Browser Chrome, subset browser yang kompatibel dengan AppleWebKit
Safari	Varian desktop, bukan seluler.

UserAgent tidak akan selalu mencantumkan browser dalam urutan tertentu, terutama jika didasarkan pada Petunjuk Klien. Berikut ini penjelasan tentang perbedaan lain yang akan Anda lihat berdasarkan nilai source:

• USER_AGENT: Kolom version dapat dikurangi menjadi versi utama atau dibekukan (bergantung pada kebijakan khusus agen). Perlu diperhatikan bahwa tidak akan ada indikasi bahwa nilai dibekukan.
• CLIENT_HINTS_LOW_ENTROPY dan CLIENT_HINTS_HIGH_ENTROPY: Entri tidak diurutkan berdasarkan kriteria apa pun; misalnya, browser yang sama mungkin mengirimkan entri ini dalam urutan yang berbeda di setiap permintaan. Class ini juga dapat berisi entri GREASE, yang harus diabaikan.
• CLIENT_HINTS_HIGH_ENTROPY: Semua kolom version yang ditemukan di browser dapat ditetapkan ke versi lengkap.

Platform

Entri BrandVersion yang mendeskripsikan platform. Opsi ini mungkin tidak kompatibel di seluruh header Agen Pengguna dan Petunjuk Klien, sehingga penargetan beberapa platform mungkin memerlukan pengujian dua nama. Misalnya, sistem operasi Macintosh Apple diberi merek "Macintosh" di header Agen Pengguna, tetapi "macOS" di Client Hints. Berikut ini penjelasan tentang perbedaan lain yang akan Anda lihat berdasarkan nilai source:

• USER_AGENT: Kolom version dapat dikurangi menjadi versi utama atau dibekukan. Perhatikan bahwa tidak akan ada indikasi bahwa nilai telah dibekukan.
• CLIENT_HINTS_LOW_ENTROPY: Kolom version tidak akan diisi.
• CLIENT_HINTS_HIGH_ENTROPY: Kolom version dapat disetel ke versi lengkap.

Ponsel

Menunjukkan apakah konten seperti iklan harus dioptimalkan untuk layar kecil dan/atau input sentuh. Perhatikan bahwa hal ini belum tentu merupakan indikator jenis perangkat, karena browser seluler dapat dikonfigurasi untuk meminta “situs desktop”.

Arsitektur

Mengidentifikasi arsitektur platform seperti "x86" atau "arm".

Untuk UserAgent berdasarkan Petunjuk Klien, perhatikan bahwa kolom ini hanya akan diisi jika source ditetapkan ke CLIENT_HINTS_HIGH_ENTROPY.

Bit

Mengidentifikasi bit platform, seperti apakah platform memiliki CPU 32-bit atau 64-bit. Kolom ini adalah string bilangan bulat yang memberikan informasi tambahan tentang arsitekturnya; misalnya, arsitektur "x86" dapat memiliki bitness yang ditetapkan ke "32" atau "64".

Untuk UserAgent berdasarkan Petunjuk Klien, perhatikan bahwa kolom ini hanya akan diisi jika source ditetapkan ke CLIENT_HINTS_HIGH_ENTROPY.

Model

Mengidentifikasi model perangkat. Untuk perangkat seluler–artinya bukan laptop atau desktop–ini akan diisi dengan nama model seperti “Pixel 6 Pro”.

Berikut ini penjelasan perbedaan yang akan Anda lihat berdasarkan nilai source:

• USER_AGENT
  • Perangkat non-seluler: Kolom model sering kali berisi gabungan arsitektur dan nilai bit seperti "x64" untuk Windows. Nilai ini tidak lintas platform; misalnya, Linux mungkin menggunakan “x86_64” untuk hardware yang sama.
  • Perangkat seluler: Kolom ini tidak akan menyertakan arsitektur dan bitness. Jika Anda tertarik dengan nilai ini, lihat UserAgent.architecture dan UserAgent.bitness.
• CLIENT_HINTS_LOW_ENTROPY: Kolom model tidak akan diisi.
• CLIENT_HINTS_HIGH_ENTROPY: Kolom model hanya akan diisi untuk model perangkat pada perangkat seluler. Tidak ada nilai yang ditetapkan untuk platform desktop.

Sumber

Mengidentifikasi header mana yang digunakan untuk membuat UserAgent. Untuk Petunjuk Klien, cara ini juga membedakan dua kasus berikut:

• CLIENT_HINTS_LOW_ENTROPY: Hanya Petunjuk Klien dasar yang tersedia.
• CLIENT_HINTS_HIGH_ENTROPY: Petunjuk Klien tersedia, termasuk setidaknya satu kolom yang diklasifikasikan sebagai entropi tinggi.