Zu User-Agent-Client-Hints migrieren

Strategien für die Migration Ihrer Website vom User-Agent-String zu den neuen User-Agent-Client-Hints.

Veröffentlicht: 19. Mai 2021

Der User-Agent-String ist eine wichtige passive Fingerprinting-Oberfläche in Browsern und außerdem schwer zu verarbeiten. Es gibt jedoch viele gute Gründe, User-Agent-Daten zu erheben und zu verarbeiten. Daher ist eine bessere Lösung erforderlich. User-Agent-Client-Hints bieten sowohl eine explizite Möglichkeit, Ihren Bedarf an User-Agent-Daten zu deklarieren, als auch Methoden, um die Daten in einem einfach zu verwendenden Format zurückzugeben.

Hier erfährst du, wie du deinen Zugriff auf User-Agent-Daten prüfst und die Verwendung von User-Agent-Strings zu User-Agent-Client-Hints migrierst.

Browser Support

  • Chrome: 90.
  • Edge: 90.
  • Firefox: not supported.
  • Safari: not supported.

Source

Erhebung und Verwendung von User-Agent-Daten prüfen

Wie bei jeder Form der Datenerhebung sollten Sie immer wissen, warum Sie die Daten erheben. Der erste Schritt besteht darin, zu verstehen, wo und warum Sie User-Agent-Daten verwenden, unabhängig davon, ob Sie Maßnahmen ergreifen werden oder nicht.

Wenn Sie nicht wissen, ob oder wo User-Agent-Daten verwendet werden, können Sie Ihren Frontend-Code nach der Verwendung von navigator.userAgent und Ihren Backend-Code nach der Verwendung des HTTP-Headers User-Agent durchsuchen. Sie sollten auch Ihren Frontend-Code auf die Verwendung bereits verworfener Funktionen wie navigator.platform und navigator.appVersion prüfen.

Überlegen Sie sich aus funktionaler Sicht, wo in Ihrem Code Sie Folgendes aufzeichnen oder verarbeiten:

  • Browsername oder -version
  • Name oder Version des Betriebssystems
  • Gerätemarke oder -modell
  • CPU-Typ, -Architektur oder -Bitness (z. B. 64-Bit)

Es ist auch wahrscheinlich, dass du eine Drittanbieterbibliothek oder einen Drittanbieterdienst verwendest, um den User-Agent zu verarbeiten. Prüfen Sie in diesem Fall, ob sie aktualisiert werden, um User-Agent-Client-Hints zu unterstützen.

Verwenden Sie nur grundlegende User-Agent-Daten?

Die Standard-User-Agent-Client-Hints umfassen:

  • Sec-CH-UA: Browsername und Haupt-/signifikante Version
  • Sec-CH-UA-Mobile: boolescher Wert, der ein Mobilgerät angibt
  • Sec-CH-UA-Platform: Name des Betriebssystems

Die vorgeschlagene reduzierte Version des User-Agent-Strings enthält diese grundlegenden Informationen ebenfalls in abwärtskompatibler Form. Anstelle von Chrome/90.0.4430.85 würde der String beispielsweise Chrome/90.0.0.0 enthalten.

Wenn Sie den User-Agent-String nur auf Browsernamen, Hauptversion oder Betriebssystem prüfen, funktioniert Ihr Code weiterhin, aber Sie sehen wahrscheinlich Warnungen zur Einstellung.

Sie können und sollten zu User-Agent-Client-Hints migrieren. Es kann jedoch sein, dass Sie Legacy-Code oder Ressourcenbeschränkungen haben, die dies verhindern. Die Reduzierung der Informationen im User-Agent-String auf diese abwärtskompatible Weise soll dafür sorgen, dass vorhandener Code zwar weniger detaillierte Informationen erhält, aber dennoch die grundlegende Funktionalität beibehält.

Strategien

Es gibt verschiedene Strategien, um die Verwendung von User-Agent-Strings zu User-Agent-Client-Hints zu migrieren.

On-Demand-clientseitige JavaScript API

Wenn du navigator.userAgent verwendest, solltest du auf navigator.userAgentData umstellen, bevor du auf das Parsen des User-Agent-Strings zurückgreifst.

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

Wenn Sie nach Mobilgeräten oder Computern suchen, verwenden Sie den booleschen Wert mobile:

const isMobile = navigator.userAgentData.mobile;

userAgentData.brands ist ein Array von Objekten mit den Attributen brand und version, mit denen der Browser seine Kompatibilität mit diesen Marken auflisten kann. Sie können direkt als Array darauf zugreifen oder einen some()-Aufruf verwenden, um zu prüfen, ob ein bestimmter Eintrag vorhanden ist:

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
}

Wenn Sie einen der detaillierteren User-Agent-Werte mit hoher Entropie benötigen, müssen Sie ihn angeben und das Ergebnis im zurückgegebenen Promise prüfen:

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

Diese Strategie kann auch verwendet werden, wenn Sie von der serverseitigen zur clientseitigen Verarbeitung wechseln möchten. Die JavaScript API benötigt keinen Zugriff auf HTTP-Anfrageheader, sodass User-Agent-Werte jederzeit angefordert werden können.

Statischer serverseitiger Header

Wenn Sie den Anfrageheader User-Agent auf dem Server verwenden und Ihre Anforderungen an diese Daten auf Ihrer gesamten Website relativ einheitlich sind, können Sie Client Hints als statischen Satz in Ihren Antworten angeben. Dies ist ein relativ einfacher Ansatz, da Sie ihn in der Regel nur an einem Ort konfigurieren müssen. Sie kann sich beispielsweise in der Webserverkonfiguration befinden, wenn Sie dort bereits Header hinzufügen, in der Hostingkonfiguration oder in der Konfiguration auf oberster Ebene des Frameworks oder der Plattform, die Sie für Ihre Website verwenden.

Diese Strategie ist sinnvoll, wenn du die Antworten, die basierend auf den User-Agent-Daten bereitgestellt werden, transformierst oder anpasst.

Browser oder andere Clients können unterschiedliche Standardhinweise bereitstellen. Daher empfiehlt es sich, alle erforderlichen Hinweise anzugeben, auch wenn sie im Allgemeinen standardmäßig bereitgestellt werden.

Die aktuellen Standardeinstellungen für Chrome würden beispielsweise so dargestellt:

⬇️ Antwortheader

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

Wenn Sie auch das Gerätemodell in Antworten erhalten möchten, senden Sie Folgendes:

⬇️ Antwortheader

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

Bei der serverseitigen Verarbeitung sollten Sie zuerst prüfen, ob der gewünschte Sec-CH-UA-Header gesendet wurde. Wenn er nicht verfügbar ist, sollten Sie auf das Parsen des User-Agent-Headers zurückgreifen.

Hinweise an ursprungsübergreifende Anfragen delegieren

Wenn Sie ursprungs- oder websiteübergreifende Unterressourcen anfordern, für die User-Agent-Client-Hints in den Anfragen gesendet werden müssen, müssen Sie die gewünschten Hinweise explizit über eine Berechtigungsrichtlinie angeben.

Angenommen, https://blog.site hostet Ressourcen auf https://cdn.site, die für ein bestimmtes Gerät optimierte Ressourcen zurückgeben können. https://blog.site kann den Hinweis Sec-CH-UA-Model anfordern, muss ihn aber explizit mit dem Header Permissions-Policy an https://cdn.site delegieren. Die Liste der richtliniengesteuerten Hinweise ist im Entwurf zur Client-Hints-Infrastruktur verfügbar.

⬇️ Antwort von blog.site, die den Hinweis delegiert

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

⬆️ Anfragen an Unterressourcen auf cdn.site enthalten den delegierten Hinweis

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

Sie können mehrere Hinweise für mehrere Ursprünge angeben, nicht nur aus dem ch-ua-Bereich:

⬇️ Antwort von blog.site, die mehrere Hinweise an mehrere Ursprünge delegiert

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

Hinweise an iFrames delegieren

Ursprungsübergreifende iFrames funktionieren ähnlich wie ursprungsübergreifende Ressourcen. Sie geben jedoch die Hinweise, die Sie delegieren möchten, im Attribut allow an.

⬇️ Antwort von blog.site

Accept-CH: Sec-CH-UA-Model

↪️ HTML für blog.site

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

⬆️ Anfrage an widget.site

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

Das Attribut allow im iFrame überschreibt alle Accept-CH-Header, die widget.site möglicherweise selbst sendet. Achten Sie also darauf, dass Sie alles angegeben haben, was die Website im iFrame benötigt.

Dynamische serverseitige Hinweise

Wenn Sie für bestimmte Teile der User Journey eine größere Auswahl an Hinweisen benötigen als für den Rest der Website, können Sie diese Hinweise bei Bedarf anfordern, anstatt sie statisch für die gesamte Website zu verwenden. Dies ist komplexer zu verwalten, aber wenn Sie bereits unterschiedliche Header pro Route festlegen, ist es möglicherweise machbar.

Wichtig ist hierbei, dass jede Instanz des Accept-CH-Headers die vorhandene Gruppe überschreibt. Wenn Sie den Header also dynamisch festlegen, muss jede Seite die vollständigen erforderlichen Hinweise anfordern.

Angenommen, Sie möchten in einem Bereich Ihrer Website Symbole und Steuerelemente bereitstellen, die dem Betriebssystem des Nutzers entsprechen. Dazu können Sie zusätzlich Sec-CH-UA-Platform-Version abrufen, um die entsprechenden Unterressourcen bereitzustellen.

⬇️ Antwortheader für /blog

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

⬇️ Antwortheader für /app

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

Serverseitige Hinweise, die bei der ersten Anfrage erforderlich sind, berücksichtigen

Es kann vorkommen, dass Sie bei der allerersten Anfrage mehr als die Standardhinweise benötigen. Dies ist jedoch wahrscheinlich selten der Fall. Prüfen Sie daher die Begründung.

Die erste Anfrage ist die allererste Anfrage auf oberster Ebene für diesen Ursprung, die in dieser Browsersitzung gesendet wird. Der Standardsatz von Hinweisen umfasst den Browsernamen mit der Hauptversion, die Plattform und die Angabe, ob es sich um ein Mobilgerät handelt. Die Frage ist also, ob Sie beim ersten Seitenaufbau erweiterte Daten benötigen.

Für zusätzliche Hinweise zur ersten Anfrage gibt es zwei Optionen. Erstens können Sie den Header Critical-CH verwenden. Dieses hat dasselbe Format wie Accept-CH, teilt dem Browser aber mit, dass er die Anfrage sofort wiederholen soll, wenn die erste Anfrage ohne den kritischen Hinweis gesendet wurde.

⬆️ Erste Anfrage

[With default headers]

⬇️ Antwortheader

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

🔃 Der Browser wiederholt die ursprüngliche Anfrage mit dem zusätzlichen Header.

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

Dies führt zu einem Mehraufwand für die Wiederholung der allerersten Anfrage, die Implementierungskosten sind jedoch relativ gering. Senden Sie den zusätzlichen Header und der Browser erledigt den Rest.

Für Situationen, in denen Sie beim allerersten Seitenaufbau zusätzliche Hinweise benötigen, wird im Vorschlag zur Zuverlässigkeit von Client Hints ein Weg beschrieben, wie Sie Hinweise in den Einstellungen auf Verbindungsebene angeben können. Dabei wird die TLS 1.3-Erweiterung Application-Layer Protocol Settings (ALPS) verwendet, um diese frühzeitige Weitergabe von Hinweisen für HTTP/2- und HTTP/3-Verbindungen zu ermöglichen. Das ist noch in einem sehr frühen Stadium, aber wenn ihr eure eigenen TLS- und Verbindungseinstellungen aktiv verwaltet, ist jetzt der ideale Zeitpunkt, um einen Beitrag zu leisten.

Legacy-Unterstützung

Möglicherweise enthält Ihre Website alten Code oder Code von Drittanbietern, der von navigator.userAgent abhängt, einschließlich Teilen des User-Agent-Strings, die reduziert werden. Sie sollten auf die entsprechenden navigator.userAgentData-Aufrufe umstellen, es gibt jedoch eine Zwischenlösung.

UA-CH Retrofill ist eine kleine Bibliothek, mit der Sie navigator.userAgent mit einem neuen String überschreiben können, der aus den angeforderten navigator.userAgentData-Werten erstellt wurde.

Mit diesem Code wird beispielsweise ein User-Agent-String generiert, der zusätzlich den Hinweis „model“ enthält:

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

Der resultierende String würde das Pixel 5-Modell anzeigen, aber immer noch die reduzierte 92.0.0.0, da der uaFullVersion-Hinweis nicht angefordert wurde:

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

Weitere Unterstützung

Wenn diese Strategien für Ihren Anwendungsfall nicht geeignet sind, können Sie eine Diskussion im Repository privacy-sandbox-dev-support starten, damit wir Ihr Problem gemeinsam untersuchen können.