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 menyamarkan User-Agent karena sulit digunakan dan untuk melindungi privasi pengguna dengan lebih baik. Sebagai respons atas hal ini, Google mendukung Client Hints 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.

Header User-Agent ditampilkan sebagai string di kolom BidRequest.device.ua.

Pesan UserAgent akan diisi dengan Client Hints jika tersedia, tetapi akan diisi berdasarkan nilai yang diuraikan dari header User-Agent. Hal ini ditampilkan di kolom BidRequest.device.sua.

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

Cara pengisian UserAgent

Tidak seperti header User-Agent, pesan UserAgent mewakili informasi agen pengguna yang dikelompokkan menjadi beberapa kolom untuk informasi tertentu.

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

• Jika permintaan berisi setidaknya Client Hints entropi rendah, UserAgent akan diisi berdasarkan kontennya.
• Jika permintaan hanya berisi header Agen Pengguna, UserAgent akan diisi berdasarkan apa yang dapat diuraikan dari header.

Catatan: Kolom source dapat digunakan untuk membedakan apa yang digunakan untuk mengisi UserAgent. Misalnya, jika ditetapkan ke USER_AGENT_STRING, hal ini akan menunjukkan bahwa UserAgent diisi berdasarkan konten header User-Agent.

Contoh: Mengisi UserAgent berdasarkan header User-Agent

Misalkan ada permintaan iklan yang dikirimkan browser dengan 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 User-Agent 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 Client Hints

Misalkan ada permintaan iklan yang dikirimkan browser dengan 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 Client Hints entropi rendah disertakan, UserAgent akan diisi berdasarkan konten header tersebut meskipun header Agen Pengguna ada. Tampilannya 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 User-Agent versus Petunjuk Klien

Beberapa kolom diisi secara berbeda, bergantung pada apakah kolom tersebut didasarkan pada header User-Agent atau Client Hints. Berikut adalah ringkasan perbedaan tersebut:

• Untuk browser dan platform yang identik, UserAgent.browsers.brand dan UserAgent.platform.brand akan sering kali berbeda antara UserAgent berdasarkan header User-Agent atau Client Hints. Misalnya, UserAgent.platform.brand mungkin muncul sebagai “Windows NT” jika didasarkan pada header Agen Pengguna, atau “Windows” jika didasarkan pada Client Hints.
• Beberapa entri UserAgent.browsers bersifat unik untuk header User-Agent atau untuk Client Hints. Misalnya, “AppleWebKit” akan muncul jika UserAgent didasarkan pada header User-Agent, sedangkan “Chromium” hanya akan muncul jika didasarkan pada Client Hints.
• Hanya UserAgent berdasarkan header User-Agent 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 itulah nilai yang dibekukan untuk versi Windows apa pun yang sama dengan atau lebih tinggi dari 10.

Data di UserAgent yang didasarkan pada Client Hints biasanya tidak akan menjadi pengganti yang tidak akurat untuk informasi yang dibekukan atau disamarkan. Jika ada ketidaksesuaian antara header User-Agent dan UserAgent berdasarkan Client Hints, informasi dari UserAgent harus lebih diutamakan.

Kolom objek UserAgent

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

Browser

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

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

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

• USER_AGENT: Kolom version dapat dikurangi menjadi versi utama atau dibekukan (bergantung pada kebijakan khusus agen). Perhatikan 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 mengirim entri ini dalam urutan yang berbeda di setiap permintaan. File 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 menjelaskan platform. Hal ini mungkin tidak kompatibel di seluruh header User-Agent dan Client Hints, sehingga penargetan beberapa platform mungkin memerlukan pengujian dua nama. Misalnya, sistem operasi Macintosh Apple diberi merek sebagai "Macintosh" di header User-Agent, tetapi "macOS" di Client Hints. Berikut ini menjelaskan perbedaan lain yang dapat Anda lihat berdasarkan nilai source:

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

Seluler

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

Arsitektur

Mengidentifikasi arsitektur platform seperti “x86” atau “arm”.

Untuk UserAgent berdasarkan Client Hints, perhatikan bahwa ini hanya akan diisi saat source ditetapkan ke CLIENT_HINTS_HIGH_ENTROPY.

Bitness

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 Client Hints, perhatikan bahwa ini hanya akan diisi saat source ditetapkan ke CLIENT_HINTS_HIGH_ENTROPY.

Model

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

Berikut ini menjelaskan perbedaan yang dapat Anda lihat berdasarkan nilai source:

• USER_AGENT
  • Perangkat non-seluler: Kolom model sering kali berisi nilai arsitektur dan bit gabungan 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 perangkat seluler. Tidak ada nilai yang ditetapkan untuk platform desktop.

Sumber

Mengidentifikasi header yang digunakan untuk membuat UserAgent. Untuk Client Hints, hal ini juga membedakan antara 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.