Przeprowadź migrację do wskazówek dotyczących klienta użytkownika

Strategie migracji witryny z używania ciągu znaków klienta użytkownika do nowych wskazówek dotyczących klienta użytkownika.

Rowan Merewood

Ciąg znaków User-Agent to ważny element pasywny do obsługi odcisków cyfrowych w przeglądarkach, a przy tym trudny do przetwarzania. Istnieje jednak wiele uzasadnionych powodów gromadzenia i przetwarzania danych klienta użytkownika, więc to, czego potrzeba, to ścieżka do lepszego rozwiązania. Wskazówki dotyczące klienta użytkownika zapewniają zarówno wyraźne zadeklarowanie, że potrzebujesz danych klienta użytkownika, jak i metody ich zwracania w łatwym w użyciu formacie.

Z tego artykułu dowiesz się, jak kontrolować dostęp do danych klienta użytkownika i przenieść wykorzystanie ciągu znaków klienta użytkownika do narzędzia User-Agent Client Hints.

Kontrola zbierania i wykorzystywania danych klienta użytkownika

Tak jak w przypadku każdej formy zbierania danych, musisz zawsze wiedzieć, dlaczego to robisz. Pierwszym krokiem, niezależnie od tego, czy będziesz podejmować jakiekolwiek działania, jest zrozumienie, gdzie i dlaczego korzystasz z danych klienta użytkownika.

Jeśli nie wiesz, czy i gdzie są używane dane klienta użytkownika, spróbuj wyszukać w kodzie interfejsu użytkownika navigator.userAgent i kod backendu do użycia nagłówka HTTP User-Agent. Sprawdź też kod interfejsu pod kątem użycia wycofanych funkcji, takich jak navigator.platform czy navigator.appVersion.

Jeśli chodzi o funkcjonalne miejsce, spójrz na dowolne miejsce w kodzie, w którym rejestrujesz lub przetwarzasz:

  • Nazwa lub wersja przeglądarki
  • Nazwa lub wersja systemu operacyjnego
  • Marka lub model urządzenia
  • Typ procesora, architektura lub szybkość transmisji bitów (np. 64-bitowy)

Możliwe też, że do przetwarzania klienta użytkownika używasz biblioteki lub usługi innej firmy. W takim przypadku sprawdź, czy aktualizują się pod kątem wskazówek dotyczących klienta użytkownika.

Czy używasz tylko podstawowych danych klienta użytkownika?

Domyślny zestaw wskazówek dotyczących klienta użytkownika obejmuje:

  • Sec-CH-UA: nazwa przeglądarki i wersja główna/istotna.
  • Sec-CH-UA-Mobile: wartość logiczna wskazująca urządzenie mobilne.
  • Sec-CH-UA-Platform: nazwa systemu operacyjnego

Zaproponowana skrócona wersja ciągu znaków klienta użytkownika zachowa te podstawowe informacje w sposób zgodny wstecznie. Na przykład zamiast Chrome/90.0.4430.85 ciąg będzie zawierać Chrome/90.0.0.0.

Jeśli sprawdzasz ciąg znaków klienta użytkownika tylko pod kątem nazwy przeglądarki, wersji głównej lub systemu operacyjnego, kod będzie nadal działać, mimo że prawdopodobnie będą pojawiać się ostrzeżenia o wycofaniu.

Chociaż możesz i powinien przejść na korzystanie z instrukcji klienta użytkownika, to może to uniemożliwiać starszy kod lub ograniczenia zasobów. Zmniejszenie ilości informacji w ciągu znaków klienta użytkownika w ten sposób wstecznej zgodności ma na celu zapewnienie, że chociaż istniejący kod będzie otrzymywać mniej szczegółowe informacje, powinien zachować podstawowe funkcje.

Strategia: interfejs JavaScript API na żądanie po stronie klienta

Jeśli obecnie używasz dyrektywy navigator.userAgent, przed przystąpieniem do analizowania ciągu klienta użytkownika zacznij korzystać z metody navigator.userAgentData.

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

Jeśli sprawdzasz urządzenie mobilne lub komputer, użyj wartości logicznej mobile:

const isMobile = navigator.userAgentData.mobile;

userAgentData.brands to tablica obiektów z właściwościami brand i version, w której przeglądarka może wyświetlać informacje o zgodności z tymi markami. Możesz uzyskać do niego dostęp bezpośrednio w postaci tablicy lub użyć wywołania some(), aby sprawdzić, czy istnieje określony wpis:

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
}

Jeśli potrzebujesz jednej z bardziej szczegółowych wartości klienta użytkownika o wysokiej entropii, musisz ją określić i sprawdzić w zwróconej wartości Promise:

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

Z tej strategii możesz też korzystać, jeśli chcesz przejść z przetwarzania po stronie serwera na przetwarzanie po stronie klienta. JavaScript API nie wymaga dostępu do nagłówków żądań HTTP, więc wartości klienta użytkownika można żądać w każdej chwili.

Strategia: statyczny nagłówek po stronie serwera

Jeśli na serwerze używasz nagłówka żądania User-Agent i Twoje potrzeby w zakresie tych danych są względnie spójne w całej witrynie, możesz wskazać żądane wskazówki dotyczące klienta jako statyczny zestaw w odpowiedziach. To dość proste podejście, ponieważ zwykle wystarczy skonfigurować je w jednej lokalizacji. Może to na przykład znajdować się w konfiguracji serwera WWW, jeśli masz już tam dodane nagłówki, w konfiguracji hostingu albo w konfiguracji najwyższego poziomu platformy lub platformy, których używasz w swojej witrynie.

Rozważ tę strategię, jeśli przekształcasz lub dostosowujesz odpowiedzi wyświetlane na podstawie danych klienta użytkownika.

Przeglądarki i inne klienty mogą udostępniać różne domyślne wskazówki, dlatego dobrze jest określić wszystko, czego potrzebujesz, nawet jeśli jest to ustawienie domyślne.

Na przykład bieżące ustawienia domyślne Chrome będą wyglądać tak:

⩍️ nagłówki odpowiedzi

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

Jeśli chcesz też otrzymywać w odpowiedziach informacje o modelu urządzenia, wyślij:

⩍️ nagłówki odpowiedzi

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

Podczas przetwarzania tego typu po stronie serwera należy najpierw sprawdzić, czy został wysłany odpowiedni nagłówek Sec-CH-UA, a następnie użyć analizy nagłówka User-Agent, jeśli nie jest on dostępny.

Strategia: przekazywanie wskazówek do żądań z innych domen

Jeśli żądasz zasobów podrzędnych z innych domen lub witryn, które wymagają wysyłania wskazówek klienta użytkownika w odpowiedzi na ich żądania, musisz wyraźnie wskazać odpowiednie wskazówki w zasadach dotyczących uprawnień.

Załóżmy na przykład, że https://blog.site hostuje zasoby https://cdn.site, które mogą zwracać zasoby zoptymalizowane pod kątem konkretnego urządzenia. https://blog.site może poprosić o podpowiedź Sec-CH-UA-Model, ale musi wyraźnie przekazać ją usłudze https://cdn.site za pomocą nagłówka Permissions-Policy. Lista wskazówek kontrolowane przez zasady jest dostępna w wersji roboczej infrastruktury pomocy klienta

🏏️ Odpowiedź od użytkownika blog.site przekazująca wskazówkę

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

⬆️ Żądanie do zasobów podrzędnych zasobu cdn.site zawiera podpowiedź delegowaną

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

Możesz określić wiele wskazówek dla wielu źródeł, a nie tylko do zakresu ch-ua:

☔️ Odpowiedź od użytkownika blog.site z przekazywaniem wielu wskazówek do różnych źródeł

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")

Strategia: przekazywanie wskazówek do elementów iframe

Elementy iframe z innych domen działają podobnie do zasobów z innych domen, ale wskazówki, które chcesz przekazać, określasz w atrybucie allow.

🏏️ Odpowiedź od: blog.site

Accept-CH: Sec-CH-UA-Model

↪️ HTML dla: blog.site

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

⬆️ Prośba do: widget.site

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

Atrybut allow w elemencie iframe zastępuje wszystkie nagłówki Accept-CH, które widget.site może wysyłać, więc upewnij się, że są określone wszystkie wymagania elementu iframe.

Strategia: dynamiczne wskazówki po stronie serwera

Jeśli w określonych częściach ścieżki użytkownika potrzebujesz szerszego wyboru wskazówek niż w pozostałych częściach witryny, możesz prosić o nie na żądanie zamiast statycznie w całej witrynie. Zarządzanie jest wtedy bardziej skomplikowane, ale jeśli masz już ustawione różne nagłówki dla poszczególnych tras, jest to możliwe.

Pamiętaj, że każde wystąpienie nagłówka Accept-CH zastąpi istniejący zestaw. Jeśli więc ustawiasz nagłówek dynamicznie, każda strona musi zażądać pełnego zestawu wymaganych wskazówek.

Na przykład w witrynie może znajdować się sekcja, w której możesz umieścić ikony i ustawienia pasujące do systemu operacyjnego użytkownika. Do tego możesz dodatkowo pobrać zasób Sec-CH-UA-Platform-Version, aby udostępnić odpowiednie zasoby podrzędne.

🏏️ Nagłówki odpowiedzi dla: /blog

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

🏏️ Nagłówki odpowiedzi dla: /app

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

Strategia: przy pierwszym żądaniu wymagane są wskazówki po stronie serwera

Czasem może się zdarzyć, że przy pierwszym żądaniu potrzebne będzie więcej wskazówek niż domyślny zestaw wskazówek, jednak będzie to rzadkością, dlatego dokładnie zapoznaj się z uzasadnieniem.

Pierwsze żądanie tak naprawdę oznacza pierwsze żądanie najwyższego poziomu dotyczące tego źródła wysłane w tej sesji przeglądania. Domyślny zestaw wskazówek zawiera nazwę przeglądarki z wersją główną, platformę i wskaźnik urządzenia mobilnego. Pytanie brzmi: czy przy wstępnym wczytaniu strony potrzebujesz rozszerzonych danych?

Dodatkowe wskazówki dotyczące pierwszego żądania można uzyskać na 2 sposoby. Po pierwsze, możesz użyć nagłówka Critical-CH. Ma taki sam format jak Accept-CH, ale informuje przeglądarkę, że powinna natychmiast ponowić próbę, jeśli pierwsza wiadomość została wysłana bez podpowiedzi krytycznej.

⬆️ Wstępna prośba

[With default headers]

⩍️ nagłówki odpowiedzi

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

🔃 Przeglądarka ponawia pierwsze żądanie z dodatkowym nagłówkiem

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

Wiąże się to z narzutem na ponawianie próby przy pierwszym żądaniu, ale koszt implementacji jest stosunkowo niski. Wyślij dodatkowy nagłówek, a przeglądarka zajmie się resztą.

Jeśli potrzebujesz dodatkowych wskazówek już przy pierwszym wczytaniu strony, w propozycji dotyczącej niezawodności wskazówek dotyczących klienta wskazujemy w ustawieniach na poziomie połączenia trasę określającą wskazówki. Wykorzystuje ono rozszerzenie Application-Layer Protocol Settings(ALPS) do protokołu TLS 1.3, aby umożliwić wczesne przekazywanie wskazówek w połączeniach HTTP/2 i HTTP/3. Jest to na wczesnym etapie, ale jeśli aktywnie zarządzasz swoimi ustawieniami TLS i połączenia, to jest idealny moment na podjęcie działań.

Strategia: obsługa starszych wersji usług

W witrynie może znajdować się starszy kod lub kod innej firmy, który jest zależny od parametru navigator.userAgent. Dotyczy to fragmentów ciągu znaków klienta użytkownika, które zostaną zmniejszone. W dłuższej perspektywie warto planować przejście na odpowiadające im wywołania navigator.userAgentData, ale istnieje rozwiązanie tymczasowe.

Zastąpienie UA-CH to mała biblioteka, która umożliwia zastąpienie parametru navigator.userAgent nowym ciągiem znaków utworzonym na podstawie żądanych wartości navigator.userAgentData.

Na przykład ten kod wygeneruje ciąg klienta użytkownika zawierający dodatkowo wskazówkę dotyczącą modelu:

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

Powstały ciąg znaków wyświetli model Pixel 5, ale nadal będzie pokazywać zmniejszoną wartość 92.0.0.0, ponieważ instrukcja uaFullVersion nie została wysłana:

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

Dalsza pomoc

Jeśli te strategie nie mają zastosowania w Twoim przypadku, rozpocznij dyskusję w repozytorium privacy-sandbox-dev-support, a my wspólnie przyjrzymy się problemowi.

Fot. Ricardo Rocha i film Unsplash