Bermigrasi ke Petunjuk Klien Agen Pengguna

Strategi untuk memigrasikan situs Anda dari mengandalkan string agen pengguna ke Petunjuk Klien Agen Pengguna baru.

Rowan Merewood

Agen Pengguna string adalah pelacakan sidik jari pasif yang signifikan muncul di browser, serta serta sulit untuk diproses. Namun, ada semua jenis alasan pengumpulan dan pemrosesan data agen pengguna, jadi yang diperlukan adalah ke solusi yang lebih baik. Petunjuk Klien Agen Pengguna memberikan cara yang eksplisit mendeklarasikan kebutuhan Anda akan data agen pengguna dan metode untuk mengembalikan data dalam format yang mudah digunakan.

Catatan: Untuk mengetahui informasi selengkapnya tentang Petunjuk Klien dan memperluasnya dengan data agen pengguna, baca artikel pengantar tentang Petunjuk Klien Agen Pengguna.

Artikel ini akan memandu Anda untuk mengaudit akses Anda ke data agen pengguna dan memigrasikan penggunaan string agen pengguna ke Petunjuk Klien Agen Pengguna.

Mengaudit pengumpulan dan penggunaan data agen pengguna

Seperti semua bentuk pengumpulan data, Anda harus selalu memahami mengapa Anda mengumpulkannya. Langkah pertama, terlepas dari apakah Anda akan mengambil tindakan apa pun, adalah memahami di mana dan mengapa Anda menggunakan data agen pengguna.

Jika Anda tidak tahu apakah atau di mana data agen pengguna digunakan, coba telusuri kode front-end untuk penggunaan navigator.userAgent dan kode back-end untuk penggunaan header HTTP User-Agent. Anda juga harus memeriksa kode {i>front-end<i} untuk penggunaan fitur yang sudah tidak digunakan lagi, seperti navigator.platform dan navigator.appVersion.

Dari sudut pandang fungsional, pikirkan di mana pun dalam kode di mana Anda berada perekaman atau pemrosesan:

• Nama atau versi browser
• Nama atau versi sistem operasi
• Merek atau model perangkat
• Jenis, arsitektur, atau bit CPU (misalnya, 64-bit)

Anda mungkin juga menggunakan pustaka atau layanan pihak ketiga untuk memproses agen pengguna. Dalam hal ini, periksa untuk melihat apakah mereka memperbarui ke mendukung Petunjuk Klien Agen Pengguna.

Apakah Anda hanya menggunakan data agen pengguna dasar?

Kumpulan default Petunjuk Klien Agen Pengguna mencakup:

• Sec-CH-UA: nama browser dan versi utama/signifikan
• Sec-CH-UA-Mobile: nilai boolean yang menunjukkan perangkat seluler
• Sec-CH-UA-Platform: nama sistem operasi
  • Perhatikan bahwa hal ini telah diperbarui dalam spesifikasi dan akan ditampilkan dalam Chrome dan browser berbasis Chromium lainnya sebentar lagi.

Pengurangan versi string agen pengguna yang diusulkan juga akan mempertahankan informasi dasar ini dengan cara yang kompatibel dengan sistem lama. Misalnya, daripada Chrome/90.0.4430.85, string akan menyertakan Chrome/90.0.0.0.

Jika Anda hanya memeriksa string agen pengguna untuk nama browser, versi utama, atau sistem operasi, maka kode Anda akan tetap berfungsi walaupun kemungkinan besar untuk melihat peringatan penghentian penggunaan.

Meskipun Anda dapat dan harus bermigrasi ke Petunjuk Klien Agen Pengguna, Anda mungkin memiliki atau batasan sumber daya yang mencegah hal ini. Pengurangan informasi dalam string agen pengguna dengan cara yang kompatibel dengan versi lama ini dimaksudkan untuk memastikan bahwa meskipun kode yang sudah ada akan menerima informasi yang kurang detail, kode tersebut seharusnya tetap mempertahankan fungsionalitas dasar.

Strategi: JavaScript API sisi klien on-demand

Jika Anda saat ini menggunakan navigator.userAgent, Anda harus melakukan transisi ke lebih memilih navigator.userAgentData sebelum kembali ke penguraian string agen pengguna.

if (navigator.userAgentData) {
  // use new hints
} else {
  // fall back to user-agent string parsing
}

Jika Anda memeriksa perangkat seluler atau desktop, gunakan nilai mobile boolean:

const isMobile = navigator.userAgentData.mobile;

userAgentData.brands adalah array objek dengan brand dan version properti yang browser dapat mencantumkan kompatibilitasnya dengan perusahaan. Anda dapat mengaksesnya langsung sebagai array atau Anda mungkin ingin menggunakan Panggilan some() untuk memeriksa apakah ada entri tertentu:

function isCompatible(item) {
  // In real life you most likely have more complex rules here
  return ['Chromium', 'Google Chrome', 'NewBrowser'].includes(item.brand);
}
if (navigator.userAgentData.brands.some(isCompatible)) {
  // browser reports as compatible
}

userAgentData.brands akan berisi berbagai nilai dalam urutan yang berbeda-beda, jadi jangan bergantung pada sesuatu yang muncul pada indeks tertentu.

Jika Anda membutuhkan salah satu nilai agen pengguna yang lebih rinci dan entropi tinggi, Anda akan perlu menentukannya dan memeriksa hasilnya dalam Promise yang ditampilkan:

navigator.userAgentData.getHighEntropyValues(['model'])
  .then(ua => {
    // requested hints available as attributes
    const model = ua.model
  });

Anda juga dapat menggunakan strategi ini jika Anda ingin beralih dari pemrosesan sisi server ke pemrosesan sisi klien. JavaScript API tidak memerlukan akses ke header permintaan HTTP, sehingga nilai agen pengguna dapat diminta di di titik mana pun.

Catatan: Coba demo JavaScript API Petunjuk Klien Agen Pengguna.

Strategi: Header sisi server statis

Jika Anda menggunakan header permintaan User-Agent di server dan kebutuhan Anda bahwa data relatif konsisten di seluruh situs Anda, maka Anda dapat menentukan client hints yang diinginkan sebagai set statis dalam respons Anda. Ini adalah pendekatan yang relatif sederhana karena umumnya Anda hanya perlu mengkonfigurasi dalam satu lokasi HTTP/HTTPS. Misalnya, mungkin ada di konfigurasi server web Anda jika Anda sudah tambahkan {i>header<i} di sana, konfigurasi {i> hosting Anda<i}, atau konfigurasi tingkat atas dari kerangka kerja atau platform yang digunakan untuk situs Anda.

Pertimbangkan strategi ini jika Anda mengubah atau menyesuaikan respons dilayani berdasarkan data agen pengguna.

Catatan: Anda juga dapat mempertimbangkan untuk bermigrasi ke strategi JavaScript API sisi klien on demand, bukan mengirim header tambahan.

Browser atau klien lain dapat memilih untuk menyediakan petunjuk default yang berbeda, jadi praktik yang baik untuk menentukan semua yang Anda butuhkan, bahkan jika itu disediakan oleh secara default.

Misalnya, default saat ini untuk Chrome akan ditampilkan sebagai:

⬇️ Header respons

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

Jika Anda juga ingin menerima model perangkat dalam respons, maka Anda perlu kirim:

⬇️ Header respons

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA

Pengurutan tidak penting, contoh dicantumkan menurut abjad.

Saat memproses ini di sisi server, Anda harus memeriksa terlebih dahulu apakah server Header Sec-CH-UA telah dikirim lalu kembali ke header User-Agent mengurai jika tidak tersedia.

Catatan: Coba demo header HTTP Petunjuk Klien Agen Pengguna.

Strategi: Mendelegasikan petunjuk ke permintaan lintas origin

Jika Anda meminta subresource lintas origin atau lintas situs yang memerlukan Petunjuk Klien Agen Pengguna akan dikirim pada permintaan mereka, maka Anda harus secara eksplisit menentukan petunjuk yang diinginkan menggunakan Kebijakan Izin.

Catatan: Kebijakan Izin adalah bentuk baru dari Kebijakan Fitur

Sebagai contoh, anggaplah https://blog.site menghosting resource di https://cdn.site yang dapat menampilkan resource yang dioptimalkan untuk perangkat tertentu. https://blog.site dapat meminta petunjuk Sec-CH-UA-Model, tetapi harus secara eksplisit mendelegasikannya ke https://cdn.site menggunakan Permissions-Policy {i>header<i}. Daftar petunjuk yang dikontrol kebijakan tersedia di Petunjuk Klien Infrastruktur draf

⬇️ Respons dari blog.site yang mendelegasikan petunjuk

Accept-CH: Sec-CH-UA-Model
Permissions-Policy: ch-ua-model=(self "https://cdn.site")

⬆️ Permintaan ke subresource di cdn.site menyertakan petunjuk yang didelegasikan

Sec-CH-UA-Model: "Pixel 5"

Anda dapat menentukan beberapa petunjuk untuk beberapa origin, dan bukan hanya dari rentang ch-ua:

⬇️ Respons dari blog.site yang mendelegasikan beberapa petunjuk ke beberapa asal

Accept-CH: Sec-CH-UA-Model, DPR
Permissions-Policy: ch-ua-model=(self "https://cdn.site"),
                    ch-dpr=(self "https://cdn.site" "https://img.site")

Anda tidak perlu menyertakan setiap petunjuk yang didelegasikan dalam Accept-CH, tetapi Anda perlu menyertakan self untuk setiap petunjuk, meskipun Anda tidak menggunakannya secara langsung di tingkat teratas.

Strategi: Mendelegasikan petunjuk ke iframe

iframe lintas origin berfungsi dengan cara yang mirip dengan resource lintas origin, tetapi Anda tentukan petunjuk yang ingin Anda delegasikan dalam atribut allow.

⬇️ Jawaban dari blog.site

Accept-CH: Sec-CH-UA-Model

↪️ HTML untuk blog.site

<iframe src="https://widget.site" allow="ch-ua-model"></iframe>

⬆️ Permintaan ke widget.site

Sec-CH-UA-Model: "Pixel 5"

Atribut allow di iframe akan menggantikan header Accept-CH yang widget.site dapat mengirim sendiri, jadi pastikan Anda telah menentukan semua diperlukan situs iframe.

Strategi: Petunjuk sisi server dinamis

Jika Anda memiliki bagian tertentu dari perjalanan pengguna yang membutuhkan pilihan yang lebih banyak petunjuk dibandingkan di bagian lain situs, Anda dapat memilih untuk meminta petunjuk tersebut sesuai permintaan daripada secara statis di seluruh situs. Ini lebih kompleks untuk mengelola, tetapi jika Anda sudah menetapkan {i> header<i} yang berbeda untuk setiap rute, layak.

Hal penting yang perlu diingat di sini adalah setiap instance Accept-CH akan menimpa kumpulan yang ada secara efektif. Jadi, jika Anda secara dinamis menetapkan {i>header<i} maka setiap halaman harus meminta kumpulan petunjuk lengkap yang diperlukan.

Misalnya, Anda mungkin memiliki satu bagian di situs tempat Anda ingin menyediakan ikon dan kontrol yang sesuai dengan sistem operasi pengguna. Untuk itu, Anda dapat ingin menarik Sec-CH-UA-Platform-Version juga untuk menayangkan subresource.

⬇️ Header respons untuk /blog

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

⬇️ Header respons untuk /app

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA

Strategi: Petunjuk sisi server diperlukan pada permintaan pertama

Mungkin ada kasus di mana Anda memerlukan lebih daripada kumpulan petunjuk default pada permintaan pertama, namun kemungkinan besar ini jarang terjadi, jadi pastikan Anda meninjau alasannya.

Permintaan pertama benar-benar berarti permintaan tingkat atas pertama untuk origin tersebut yang dikirimkan di sesi penjelajahan. Kumpulan petunjuk default mencakup browser dengan versi utama, platform, dan indikator seluler. Jadi pertanyaannya pertanyaannya adalah, apakah Anda memerlukan data yang diperpanjang pada pemuatan halaman awal?

Catatan: Pertimbangkan juga untuk menggunakan strategi JavaScript API sisi klien on-demand untuk mengubah konten dalam halaman, bukan sisi server.

Ada dua opsi untuk petunjuk tambahan pada permintaan pertama. Pertama, Anda dapat memanfaatkan header Critical-CH. Format ini sama dengan Accept-CH tetapi memberi tahu browser bahwa ia harus segera mencoba ulang permintaan tersebut jika satu pesan dikirim tanpa petunjuk penting.

⬆️ Permintaan awal

[With default headers]

⬇️ Header respons

Accept-CH: Sec-CH-UA-Model
Critical-CH: Sec-CH-UA-Model

🔃 Browser mencoba kembali permintaan awal dengan header ekstra

[With default headers + …]
Sec-CH-UA-Model: Pixel 5

Hal ini akan menimbulkan overhead percobaan ulang pada permintaan pertama, tetapi biaya implementasinya relatif rendah. Kirim header tambahan dan browser akan mengerjakan sisanya.

Setiap nilai Critical-CH harus menjadi subhimpunan dari nilai dalam Accept-CH. Accept-CH adalah semua nilai yang Anda inginkan untuk halaman, Critical-CH adalah subkumpulan nilai yang harus Anda miliki atau Anda tidak dapat memuat halaman dengan benar.

Untuk situasi di mana Anda memerlukan benar-benar memerlukan petunjuk tambahan pada pemuatan halaman pertama, artikel Keandalan Petunjuk Klien proposal memberikan rute untuk memberikan petunjuk dalam setelan tingkat koneksi. Ini menggunakan protokol Protokol Lapisan Aplikasi Ekstensi Settings(ALPS) ke TLS 1.3 untuk memungkinkan penerusan awal petunjuk ini pada koneksi HTTP/2 dan HTTP/3. Ini masih pada tahap awal, tetapi jika Anda aktif mengelola TLS dan pengaturan koneksi, maka ini adalah waktu yang ideal untuk berkontribusi.

Strategi: Dukungan lama

Anda mungkin memiliki kode lama atau kode pihak ketiga di situs Anda yang bergantung pada navigator.userAgent, termasuk bagian dari string agen pengguna yang akan berkurang. Dalam jangka panjang, Anda harus merencanakan untuk pindah ke lingkungan yang setara Panggilan navigator.userAgentData, tetapi ada solusi sementara.

Peringatan: Tindakan ini tidak direkomendasikan dan tidak didukung dengan cara apa pun. Solusi ini disertakan untuk kelengkapan, tetapi jika Anda meluangkan waktu untuk mencoba memperbaiki bug di dalamnya, akan lebih baik jika waktu tersebut dihabiskan untuk melakukan migrasi yang sebenarnya.

Retrofill UA-CH adalah metode library yang memungkinkan Anda menimpa navigator.userAgent dengan string baru dibuat dari nilai navigator.userAgentData yang diminta.

Misalnya, kode ini akan menghasilkan string agen pengguna yang juga mencakup "model" petunjuk:

import { overrideUserAgentUsingClientHints } from './uach-retrofill.js';
overrideUserAgentUsingClientHints(['model'])
  .then(() => { console.log(navigator.userAgent); });

String yang dihasilkan akan menampilkan model Pixel 5, tetapi masih menampilkan penurunan 92.0.0.0 sebagai petunjuk uaFullVersion tidak diminta:

Mozilla/5.0 (Linux; Android 10.0; Pixel 5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.0.0 Mobile Safari/537.36

Dukungan lebih lanjut

Jika strategi ini tidak mencakup kasus penggunaan Anda, mulai Diskusi di privacy-sandbox-dev-support repositori dan kita dapat mempelajari masalah Anda bersama.

Foto oleh Ricardo Rocha di Unsplash