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żna powierzchnia biernego odcisku palca w przeglądarkach, która jest trudna do przetworzenia. Istnieją jednak różne prawidłowe powody gromadzenia i przetwarzania danych użytkownika, więc potrzebna jest droga do lepszego rozwiązania. Wskazówki dotyczące klienta użytkownika zapewniają zarówno jawną deklarację, że potrzebujesz danych klienta użytkownika, jak i metody ich zwracania w łatwym w użyciu formacie.

Uwaga: aby dowiedzieć się więcej o wskazówkach dotyczących klienta użytkownika i ich rozszerzaniu za pomocą danych User-Agent, przeczytaj artykuł wprowadzający o wskazówkach dotyczących klienta użytkownika.

Z tego artykułu dowiesz się, jak sprawdzić dostęp do danych dotyczących klienta użytkownika i jak przenieść użycie ciągu klienta użytkownika do wskazówek dotyczących klienta użytkownika.

Sprawdzanie zbierania i wykorzystywania danych użytkownika w użytkowniku po stronie serwera

Podobnie jak w przypadku każdej formy gromadzenia 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, poszukaj w kodzie front-endu użycia navigator.userAgent, a w kodzie back-endu użycia nagłówka HTTP User-Agent. Sprawdź też kod front-endu pod kątem używania funkcji, które zostały wycofane, takich jak navigator.platform i navigator.appVersion.

Z funkcjonalnego punktu widzenia zastanów się, gdzie w kodzie odbywa się nagrywanie lub przetwarzanie:

• Nazwa lub wersja przeglądarki
• Nazwa lub wersja systemu operacyjnego
• Marka lub model urządzenia
• typ procesora, architektura lub liczba bitów (np. 64-bitowa)

Możliwe też, że do przetwarzania klienta użytkownika używasz biblioteki lub usługi innej firmy. W takim przypadku sprawdź, czy aktualizują się, aby obsługiwać wskazówki dotyczące klienta użytkownika.

Czy używasz tylko podstawowych danych użytkownika?

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

• Sec-CH-UA: nazwa przeglądarki i główna wersja
• Sec-CH-UA-Mobile: wartość logiczna wskazująca urządzenie mobilne
• Sec-CH-UA-Platform: nazwa systemu operacyjnego
  • Ta zmiana została zaktualizowana w specyfikacji i wkrótce zostanie to odzwierciedlone w Chrome i innych przeglądarkach opartych na Chromium.

Proponowana wersja uproszczona ciągu znaków user-agent zachowa te podstawowe informacje w sposób zgodny ze starszymi wersjami. Na przykład zamiast Chrome/90.0.4430.85 ciąg znaków 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 powinieneś przejść na wskazówki dotyczące klienta użytkownika, możesz mieć starszy kod lub ograniczenia zasobów, które uniemożliwiają Ci to. 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 po stronie klienta na żądanie

Jeśli obecnie używasz parametru navigator.userAgent, przed powrotem do analizowania ciągu user-agent powinieneś przejść na preferowanie parametru navigator.userAgentData.

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

Jeśli sprawdzasz wersję mobilną lub na 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 jako tablicy lub użyć wywołania some(), aby sprawdzić, czy występuje w niej 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
}

Pole userAgentData.brands zawiera wartości w różnej kolejności, więc nie polegaj na tym, co jest w określonym indeksie.

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.

Uwaga: wypróbuj demonstrację interfejsu User-Agent Client Hints JavaScript API.

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 być na przykład konfiguracja serwera WWW, jeśli nagłówki są już dodane, konfiguracja hostingu lub konfiguracja najwyższego poziomu platformy lub frameworku używanego w witrynie.

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

Uwaga: zamiast wysyłać dodatkowe nagłówki, możesz też rozważyć migrację do strategii interfejsu JavaScript API po stronie klienta na żądanie.

Przeglądarki lub inne klienty mogą podawać różne domyślne wskazówki, dlatego warto określić wszystko, czego potrzebujesz, nawet jeśli jest to 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 model urządzenia, wyślij:

⬇️ Nagłówki odpowiedzi

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

Kolejność nie ma znaczenia, przykłady są podane w kolejności alfabetycznej.

Podczas przetwarzania po stronie serwera należy najpierw sprawdzić, czy został wysłany odpowiedni nagłówek Sec-CH-UA, a jeśli nie jest dostępny, przełączyć się na analizowanie nagłówka User-Agent.

Uwaga: wypróbuj demo nagłówka HTTP User-Agent Client Hints.

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ń.

Uwaga: Zasady dotyczące uprawnień to nowa forma zasad dotyczących funkcji

Załóżmy na przykład, że https://blog.site hostuje zasoby na serwerze https://cdn.site, który może zwracać zasoby zoptymalizowane pod kątem konkretnego urządzenia. https://blog.site może poprosić o Sec-CH-UA-Model podpowiedź, ale musi wyraźnie przekazać ją https://cdn.site za pomocą nagłówka Permissions-Policy. Lista wskazówek kontrolowanych przez zasady jest dostępna w przeglądzie projektu Wskazówki dotyczące klienta Infrastruktura.

⬇️ Odpowiedź od blog.site, która deleguje podpowiedź

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

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

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ź z blog.site delegująca wiele wskazówek do wielu ź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")

Nie musisz dodawać każdej wskazówki delegowanej w usłudze Accept-CH, ale musisz dodać dla niej wartość self, nawet jeśli nie używasz jej bezpośrednio na najwyższym poziomie.

Strategia: delegowanie podpowiedzi do elementów iframe

Elementy iframe w innych domenach działają podobnie jak zasoby w innych domenach, ale w atrybucie allow musisz podać wskazówki, które chcesz delegować.

⬇️ Odpowiedź użytkownika 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 ramce iframe zastąpi dowolny nagłówek Accept-CH, który może wysłać widget.site, dlatego upewnij się, że uwzględniono wszystko, czego potrzebuje strona iframe.

Strategia: dynamiczne wskazówki po stronie serwera

Jeśli w określonych częściach ścieżki użytkownika potrzebujesz większej liczby podpowiedzi niż w pozostałych częściach witryny, możesz poprosić o te podpowiedzi na żądanie, a nie statycznie w całej witrynie. Jest to bardziej skomplikowane, ale jeśli masz już ustawione różne nagłówki dla poszczególnych tras, może to być możliwe.

Pamiętaj, że każda instancja nagłówka Accept-CHzastąpi istniejący zestaw. Jeśli więc nagłówek jest ustawiany dynamicznie, każda strona musi poprosić o pełny zestaw wymaganych wskazówek.

Możesz na przykład mieć w swojej witrynie sekcję, w której chcesz umieścić ikony i elementy sterujące dostosowane do systemu operacyjnego użytkownika. W tym celu możesz dodatkowo zaimportować 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: wymagane podpowiedzi po stronie serwera przy pierwszym żądaniu

Być może w pierwszym żądaniu będziesz potrzebować więcej niż domyślnego zestawu wskazówek, ale jest to mało prawdopodobne, więc sprawdź, czy rozumiesz uzasadnienie.

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 mobilności. Pytanie brzmi: czy przy wstępnym wczytaniu strony potrzebujesz rozszerzonych danych?

Uwaga: rozważ też użycie strategii interfejsu API JavaScript po stronie klienta na żądanie, aby zmieniać zawartość na stronie zamiast po stronie serwera.

Aby uzyskać dodatkowe wskazówki dotyczące pierwszej prośby, masz 2 opcje. Po pierwsze, możesz skorzystać z 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 ponownie wysyła początkowe żą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ą.

Każda wartość Critical-CH musi być podzbiorem wartości w kryterium Accept-CH. Accept-CH to wszystkie wartości, które chcesz mieć na stronie, a Critical-CH to podzbiór tych wartości, które muszą się znaleźć, aby strona mogła się wczytać prawidłowo.

W sytuacjach, gdy naprawdę potrzebujesz dodatkowych wskazówek podczas pierwszego wczytywania strony, propozycja dotycząca niezawodności wskazówek klienta przedstawia sposób określania wskazówek w ustawieniach na poziomie połączenia. Użyto w tym celu rozszerzenia Application-Layer Protocol Settings(ALPS) do TLS 1.3, aby umożliwić wcześniejsze przekazywanie wskazówek w przypadku połączeń HTTP/2 i HTTP/3. Jest to wciąż bardzo wczesny etap, ale jeśli aktywnie zarządzasz własnymi ustawieniami TLS i połączeń, to jest idealny moment, aby się zaangażować.

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ługim okresie warto przejść na równoważne navigator.userAgentDatawybieranie, ale istnieje też tymczasowe rozwiązanie.

Ostrzeżenie: to rozwiązanie nie jest zalecane i w żaden sposób nie obsługiwane. To rozwiązanie zostało uwzględnione ze względu na kompletność, ale jeśli poświęcisz czas na próbę naprawienia błędów, lepiej będzie go wykorzystać na przeprowadzenie migracji.

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

Ten kod wygeneruje ciąg znaków klienta użytkownika, który dodatkowo zawiera podpowiedź „model”:

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

Wygenerowany ciąg znaków zawiera model Pixel 5, ale nadal zawiera skrócony model 92.0.0.0, ponieważ nie przesłano podpowiedzi uaFullVersion:

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

Dodatkowa pomoc

Jeśli te strategie nie pasują do Twojego przypadku użycia, rozpocznij dyskusję w repozytorium privacy-sandbox-dev-support, a my pomożemy Ci rozwiązać problem.

Fot. Ricardo Rocha na stronie Unsplash