Zu User-Agent-Client-Hints migrieren

Strategien für die Migration Ihrer Website von der Nutzung des User-Agent-Strings zum neue User-Agent-Client-Hints.

Rowan Merewood

Der User-Agent String ist ein signifikantes passives Fingerprinting in Browsern angezeigt wird, und die Verarbeitung ist schwierig. Es gibt jedoch alle Arten von gültigen Gründe für die Erfassung und Verarbeitung von User-Agent-Daten. zu einer besseren Lösung. User-Agent-Client-Hints bieten beiden eine explizite Möglichkeit, um die Notwendigkeit von User-Agent-Daten und Methoden zur Rückgabe der Daten in einem nutzerfreundlichen Format.

In diesem Artikel erfahren Sie, wie Sie Ihren Zugriff auf User-Agent-Daten prüfen und Migration von User-Agent-Strings zu User-Agent-Client-Hints

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

Wie bei jeder Art der Datenerhebung sollten Sie immer verstehen, warum Sie sie sammeln. Der erste Schritt, unabhängig davon, ob Sie zu verstehen, wo und warum Sie User-Agent-Daten verwenden.

Wenn du nicht weißt, ob oder wo User-Agent-Daten verwendet werden, Ihren Frontend-Code zur Verwendung von navigator.userAgent und Ihren Backend-Code für der User-Agent-HTTP-Header verwendet wird. Überprüfen Sie auch Ihren Frontend-Code für die Verwendung bereits eingestellter Funktionen wie navigator.platform und navigator.appVersion.

Aus funktionaler Sicht sollten Sie sich an einer beliebigen Stelle im Code vorstellen, an der Sie Aufzeichnung oder Verarbeitung:

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

Es ist auch wahrscheinlich, dass Sie die Bibliothek oder den Dienst eines Drittanbieters für die den User-Agent zu verarbeiten. Überprüfen Sie in diesem Fall, ob eine Aktualisierung auf unterstützen User-Agent-Client-Hints.

Verwenden Sie nur grundlegende User-Agent-Daten?

Standardmäßig sind folgende User-Agent-Client-Hints verfügbar:

  • Sec-CH-UA: Browsername und Hauptversion/wichtige Version
  • Sec-CH-UA-Mobile: boolescher Wert, der ein Mobilgerät angibt
  • Sec-CH-UA-Platform: Name des Betriebssystems <ph type="x-smartling-placeholder">
      </ph>
    • Beachten Sie, dass dies in der Spezifikation aktualisiert wurde und in der Google Chrome und anderen Chromium-basierten Browsern.

Auch die reduzierte Version der vorgeschlagenen User-Agent-Zeichenfolge wird beibehalten. um diese grundlegenden Informationen abwärtskompatibel zu machen. Anstatt beispielsweise Chrome/90.0.4430.85 würde der String Chrome/90.0.0.0 enthalten.

Wenn ihr nur den User-Agent-String nach Browsername, Hauptversion, oder Betriebssystem ist, funktioniert Ihr Code weiterhin, obwohl Sie wahrscheinlich um Einstellungswarnungen zu sehen.

Es ist zwar möglich und empfehlenswert, zu User-Agent-Client-Hints zu migrieren, doch möglicherweise haben Sie Code- oder Ressourceneinschränkungen, die dies verhindern. Die Reduzierung von Informationen in dass der User-Agent-String so abwärtskompatibel ist, vorhandener Code erhält zwar weniger detaillierte Informationen, sollte aber trotzdem die grundlegende Funktionalität beibehalten.

Strategie: Clientseitige JavaScript API auf Abruf

Wenn Sie derzeit navigator.userAgent verwenden, wechseln Sie zu Bevorzugung von navigator.userAgentData, bevor auf das Parsen des User-Agent-String.

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 brand und version. Eigenschaften, bei denen der Browser seine Kompatibilität mit diesen Marken. Sie können direkt als Array darauf zugreifen oder ein some()-Aufruf, 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 ihr einen der detaillierteren User-Agent-Werte mit hoher Entropie benötigt, müssen Sie dies angeben und im zurückgegebenen Promise nach dem Ergebnis suchen:

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

Sie können diese Strategie auch verwenden, wenn Sie von serverseitiger zur clientseitigen Verarbeitung. Die JavaScript API kann keine erfordern Zugriff auf HTTP-Anfrageheader, sodass User-Agent-Werte unter jederzeit.

Strategie: Statischer serverseitiger Header

Wenn Sie den Anfrageheader User-Agent auf dem Server verwenden und für diese Daten auf der gesamten Website relativ konsistent sind, können Sie geben Sie die gewünschten Clienthinweise als statischen Satz in Ihren Antworten an. Dies ist ein relativ einfachen Ansatz, da Sie sie in der Regel nur in einem Standort. Es könnte sich beispielsweise in Ihrer Webserverkonfiguration befinden, wenn Sie bereits fügen Sie dort Header, Ihre Hosting-Konfiguration oder die Konfiguration der Framework oder Plattform, die Sie für Ihre Website verwenden.

Ziehen Sie diese Strategie in Betracht, wenn Sie die Antworten anpassen oder anpassen möchten. basierend auf den User-Agent-Daten bereitgestellt.

Browser oder andere Clients stellen möglicherweise andere Standardhinweise bereit. alles Notwendige anzugeben, selbst wenn es im Allgemeinen Standardeinstellung.

Die aktuellen Standardeinstellungen für Chrome werden beispielsweise so dargestellt:

⬇️ Antwort-Header

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

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

⬇️ Antwort-Header

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, Der Sec-CH-UA-Header wurde gesendet, woraufhin der Fallback auf den User-Agent-Header erfolgt wenn er nicht verfügbar ist.

Strategie: Hinweise an ursprungsübergreifende Anfragen delegieren

Wenn Sie ursprungsübergreifende oder websiteübergreifende Unterressourcen anfordern, für die ein User-Agent-Client-Hints werden bei Anfragen gesendet. die gewünschten Hinweise mithilfe einer Berechtigungsrichtlinie explizit angeben.

Beispiel: https://blog.site hostet Ressourcen auf https://cdn.site, die für ein bestimmtes Gerät optimierte Ressourcen zurückgeben kann. https://blog.site kann nach dem Sec-CH-UA-Model-Hinweis fragen, muss sich aber explizit über Permissions-Policy an https://cdn.site delegiert. Header. Die Liste der richtliniengesteuerten Hinweise ist unter Client-Hints Infrastruktur Entwurf

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

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

⬆️ Anfrage an untergeordnete Ressourcen von cdn.site enthält den delegierten Hinweis

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

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

😃️ Antwort von blog.site, bei der mehrere Hinweise an mehrere Ursprünge delegiert werden

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

Strategie: Hinweise an iFrames delegieren

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

⬇️ 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 sendet sich möglicherweise selbst. Stellen Sie daher sicher, dass Sie alles für die iFrames benötigen.

Strategie: Dynamische serverseitige Hinweise

Wenn Sie bestimmte Teile der User Journey haben und eine größere Auswahl benötigen als für den Rest der Website, können Sie diese Hinweise statt statisch für die gesamte Website. Dies ist komplexer, wenn verwalten. Wenn Sie jedoch bereits unterschiedliche Header für einzelne Routen festgelegt haben, machbar ist.

Wichtig dabei ist, dass jede Instanz des Accept-CH-Objekts überschreibt den vorhandenen Satz. Wenn Sie also dynamisch müssen die erforderlichen Hinweise auf jeder Seite angefordert werden.

Vielleicht haben Sie einen Bereich auf Ihrer Website, in dem Sie Symbole und Steuerelemente, die zum Betriebssystem des Nutzers passen. Dazu können Sie zusätzlich Sec-CH-UA-Platform-Version abrufen möchten, um entsprechende untergeordneten Ressourcen.

⬇️ Antwort-Header für /blog

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

⬇️ Antwort-Header für /app

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

Strategie: Serverseitige Hinweise bei der ersten Anfrage erforderlich

Es kann vorkommen, dass Sie mehr als die standardmäßigen Hinweise im Dies kommt jedoch nur selten vor. Stellen Sie daher sicher, die Begründung noch einmal durchgegangen.

Die erste Anfrage bezieht sich auf die erste Anfrage auf oberster Ebene für diesen Ursprung. die in dieser Browsersitzung gesendet wurden. Der Standardsatz von Hinweisen umfasst den Browser mit der Hauptversion, der Plattform und der mobilen Anzeige. Die Frage lautet also: ist die Frage, ob Sie beim ersten Seitenaufbau erweiterte Daten benötigen.

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

⬆️ Erste Anfrage

[With default headers]

⬇️ Antwort-Header

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 verursacht den Aufwand für Wiederholungsversuche bei der allerersten Anfrage, aber der Implementierungskosten relativ niedrig sind. Zusätzlichen Header und Browser senden den Rest.

In Situationen, in denen Sie wirklich zusätzliche Hinweise benötigen, beim ersten Seitenaufbau: Client Hints Reliability Angebot erstellt eine Route, um Hinweise in den Einstellungen auf Verbindungsebene anzugeben. Dieses nutzt das Application-Layer Protocol Erweiterung „Settings“ (ALPS) zu TLS 1.3 an, um diese frühe Übergabe von Hinweisen bei HTTP/2- und HTTP/3-Verbindungen zu ermöglichen. Dieses sich noch in einem sehr frühen Stadium befindet, aber wenn Sie Ihre eigenen TLS- und ist dies ein guter Zeitpunkt, um einen Beitrag zu leisten.

Strategie: Legacy-Unterstützung

Möglicherweise enthält Ihre Website alten oder Drittanbietercode, der navigator.userAgent, einschließlich der Teile des User-Agent-Strings, der reduziert. Langfristig sollten Sie also planen, navigator.userAgentData Anrufe, aber es gibt eine Zwischenlösung.

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

Dieser Code generiert z. B. einen User-Agent-String, der zusätzlich enthält das Modell „model“ Tipp:

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

Der resultierende String würde das Modell Pixel 5 anzeigen, aber weiterhin die reduzierten Werte 92.0.0.0 als Hinweis uaFullVersion wurde nicht angefordert:

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, beginnen Sie eine Diskussion in privacy-sandbox-dev-support Repository , damit wir Ihr Problem gemeinsam untersuchen können.

Foto von Ricardo Rocha bei Unsplash