User-Agent-Targeting

Der User-Agent-Header wurde bisher in Gebotsanfragen eingefügt, um nützliche Targeting-Daten wie den Browser und die Plattform des initiierenden Geräts bereitzustellen. Browser kürzen den User-Agent-String jedoch oft stark, da er schwer zu verwenden ist und um den Datenschutz der Nutzer besser zu schützen. Als Reaktion darauf unterstützt Google User-Agent-Client-Hints, die, sofern verfügbar, in Gebotsanfragen enthalten sind, um den User-Agent-Header zu ergänzen. Diese Client-Hints (kurz) können aus Sec-Ch-UA*-Headern oder aus der Javascript Client Hints API stammen.

Der User-Agent-Header wird als String im Feld BidRequest.device.ua verfügbar gemacht.

Eine UserAgent-Nachricht wird mit Client-Hints gefüllt, wenn diese verfügbar sind. Andernfalls wird sie basierend auf Werten gefüllt, die aus dem User-Agent-Header geparst werden. Dies wird im Feld BidRequest.device.sua angezeigt.

Wir empfehlen Bietern dringend, die UserAgent-Nachricht anstelle des User-Agent-Strings zu verwenden.

So wird UserAgent ausgefüllt

Im Gegensatz zum User-Agent-Header stellt die UserAgent-Nachricht die User-Agent-Informationen aufgeschlüsselt in mehrere Felder für bestimmte Informationen dar.

Je nachdem, ob Client-Hints in der Anzeigenanfrage verfügbar sind, kann die UserAgent-Nachricht auf folgende Weise ausgefüllt werden:

• Wenn die Anfrage mindestens Client-Hints mit niedriger Entropie enthält, wird UserAgent anhand ihres Inhalts ausgefüllt.
• Wenn die Anfrage nur den User-Agent-Header enthält, wird UserAgent basierend auf den Informationen, die aus dem Header geparst werden können, ausgefüllt.

Hinweis: Mit dem Feld source lässt sich unterscheiden, was zum Ausfüllen von UserAgent verwendet wird. Wenn der Wert beispielsweise auf USER_AGENT_STRING festgelegt ist, bedeutet das, dass UserAgent auf Grundlage des Inhalts der User-Agent-Header ausgefüllt wurde.

Beispiel: UserAgent anhand des User-Agent-Headers ausfüllen

Angenommen, es gibt eine Anzeigenanfrage, bei der der Browser die folgenden Header sendet:

User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
            AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36

Ein UserAgent, das nur auf dem User-Agent-Header basiert, könnte so aussehen:

browsers: [{ brand: "Mozilla", version: ["5", "0"] },
           { brand: "AppleWebKit", version: ["537", "36"] },
           { brand: "Chrome", version: ["103", "0", "0", "0"] },
           { brand: "Safari", version: ["537", "36"] }],
platform: { brand: "Windows NT", version: ["10", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
model: "x64",
source: USER_AGENT_STRING

Beispiel: UserAgent basierend auf Client Hints ausfüllen

Angenommen, es gibt eine Anzeigenanfrage, bei der der Browser die folgenden Header sendet:

User-Agent:                 Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                            AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36
Sec-Ch-Ua:                  ".Not/A)Brand";v="99", "Google Chrome";v="103", "Chromium";v="103"
Sec-Ch-Ua-Arch:             x86
Sec-Ch-Ua-Full-Version:     103.0.5060.134
Sec-Ch-Ua-Mobile:           ?0
Sec-Ch-Ua-Platform:         Windows
Sec-Ch-Ua-Platform-Version: 15.0.0

Wenn mindestens Client-Hints mit geringer Entropie enthalten sind, wird UserAgent anhand der Inhalte dieser Header ausgefüllt, auch wenn User-Agent-Header vorhanden sind. Das würde so aussehen:

browsers: [{ brand: ".Not/A)Brand", version: ["99", "0", "0", "0"] },
           { brand: "Google Chrome", version: ["103", "0", "5060", "134"] },
           { brand: "Chromium", version: ["103", "0", "5060", "134"] }],
platform: { brand: "Windows", version: ["15", "0", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
source: CLIENT_HINTS_HIGH_ENTROPY

Befüllung basierend auf dem User-Agent-Header im Vergleich zu Client-Hints

Einige Felder werden unterschiedlich ausgefüllt, je nachdem, ob sie auf dem User-Agent-Header oder Client-Hinweisen basieren. Im Folgenden finden Sie eine Zusammenfassung dieser Unterschiede:

• Bei identischen Browsern und Plattformen unterscheiden sich UserAgent.browsers.brand und UserAgent.platform.brand häufig zwischen einem UserAgent basierend auf dem User-Agent-Header oder Client-Hinweisen. Beispiel: UserAgent.platform.brand könnte als „Windows NT“ angezeigt werden, wenn es auf dem User-Agent-Header basiert, oder als „Windows“, wenn es auf Client-Hints basiert.
• Einige UserAgent.browsers-Einträge sind nur für den User-Agent-Header oder für Client-Hints verfügbar. Wenn UserAgent beispielsweise auf dem User-Agent-Header basieren würde, würde „AppleWebKit“ angezeigt. „Chromium“ würde nur angezeigt, wenn es auf Client-Hinweisen basieren würde.
• Nur ein UserAgent, das auf dem User-Agent-Header basiert, kann eingefrorene Werte enthalten. Wenn die Plattform beispielsweise Windows 11 22H2 ist, wird UserAgent.platform.brand auf „Windows NT“ und UserAgent.platform.version auf [“10”, “0”] festgelegt, da dies der eingefrorene Wert für alle Windows-Versionen ab Version 10 ist.

Daten in UserAgent, die auf Client-Hinweisen basieren, sind in der Regel kein ungenauer Ersatz für eingefrorene oder unkenntlich gemachte Informationen. Wenn der User-Agent-Header nicht mit einem UserAgent übereinstimmt, der auf Client-Hints basiert, sollten die Informationen aus dem UserAgent bevorzugt werden.

Felder des UserAgent-Objekts

In diesem Abschnitt werden die einzelnen Felder zusammengefasst. Dabei liegt der Fokus auf dem Google RTB-spezifischen Verhalten und den Best Practices für die Verwendung.

Browser

Enthält eine Liste von BrandVersion-Einträgen, die in der Regel nach Spezifität sortiert sind. Wenn Sie beispielsweise den Inhalt von browsers auflisten, könnte die brand für jeden Eintrag in der folgenden Reihenfolge angezeigt werden:

Marke	Bedeutung
Mozilla	Mozilla-kompatibel
AppleWebKit	AppleWebKit-basiert, eine Teilmenge von Mozilla.
Chrome	Chrome-Browser, eine Teilmenge von AppleWebKit-kompatiblen Browsern
Safari	Desktopvariante im Gegensatz zur mobilen Variante.

In UserAgent werden Browser nicht immer in einer bestimmten Reihenfolge aufgeführt, insbesondere wenn die Informationen auf Client-Hinweisen basieren. Im Folgenden werden weitere Unterschiede beschrieben, die je nach Wert von source zu erwarten sind:

• USER_AGENT: Das Feld version kann auf eine Hauptversion reduziert oder eingefroren werden (abhängig von der agentspezifischen Richtlinie). Es gibt keine Hinweise darauf, dass der Wert eingefroren ist.
• CLIENT_HINTS_LOW_ENTROPY und CLIENT_HINTS_HIGH_ENTROPY: Einträge werden nicht nach bestimmten Kriterien sortiert. So kann derselbe Browser diese Einträge beispielsweise in jeder Anfrage in einer anderen Reihenfolge senden. Sie können auch einen GREASE-Eintrag enthalten, der ignoriert werden sollte.
• CLIENT_HINTS_HIGH_ENTROPY: Alle in Browsern gefundenen version-Felder können auf vollständige Versionen festgelegt werden.

Plattform

Ein BrandVersion-Eintrag, der die Plattform beschreibt. Das ist möglicherweise nicht mit dem User-Agent-Header und Client-Hinweisen kompatibel. Für das Targeting auf einigen Plattformen müssen daher möglicherweise zwei Namen getestet werden. Das Betriebssystem Macintosh von Apple wird beispielsweise im User-Agent-Header als „Macintosh“ und in Client-Hinweisen als „macOS“ bezeichnet. Im Folgenden werden weitere Unterschiede beschrieben, die je nach Wert von source zu erwarten sind:

• USER_AGENT: Das Feld version kann auf eine Hauptversion reduziert oder eingefroren werden. Es gibt keinen Hinweis darauf, dass der Wert eingefroren ist.
• CLIENT_HINTS_LOW_ENTROPY: Das Feld version wird nicht ausgefüllt.
• CLIENT_HINTS_HIGH_ENTROPY: Das Feld version kann auf die Vollversion festgelegt werden.

Mobilgeräte

Gibt an, ob Inhalte wie Anzeigen für kleine Bildschirme und/oder Touch-Eingabe optimiert werden sollen. Das ist nicht unbedingt ein Indikator für den Gerätetyp, da mobile Browser so konfiguriert werden können, dass sie eine „Desktop-Website“ anfordern.

Architektur

Gibt die Architektur der Plattform an, z. B. „x86“ oder „arm“.

Bei einem UserAgent, das auf Client Hints basiert, wird dieses Feld nur ausgefüllt, wenn source auf CLIENT_HINTS_HIGH_ENTROPY festgelegt ist.

Bitness

Gibt an, ob die Plattform eine 32‑Bit- oder 64‑Bit-CPU hat. Das Feld ist ein Integer-String, der zusätzliche Informationen zur Architektur enthält. Bei einer „x86“-Architektur kann die Bitness beispielsweise auf „32“ oder „64“ festgelegt sein.

Bei einem UserAgent, das auf Client Hints basiert, wird dieses Feld nur ausgefüllt, wenn source auf CLIENT_HINTS_HIGH_ENTROPY festgelegt ist.

Modell

Gibt das Gerätemodell an. Bei Mobilgeräten (nicht Laptops oder Desktopcomputer) wird hier ein Modellname wie „Pixel 6 Pro“ eingetragen.

Im Folgenden werden die Unterschiede beschrieben, die je nach Wert von source zu erwarten sind:

• USER_AGENT
  • Nicht mobile Geräte: Das Feld model enthält oft einen kombinierten Architektur- und Bitness-Wert wie „x64“ für Windows. Dieser Wert ist nicht plattformübergreifend. Unter Linux wird für dieselbe Hardware beispielsweise „x86_64“ verwendet.
  • Mobilgeräte: Dieses Feld enthält keine Informationen zur Architektur und Bitanzahl. Wenn Sie sich für diese Werte interessieren, finden Sie weitere Informationen unter UserAgent.architecture und UserAgent.bitness.
• CLIENT_HINTS_LOW_ENTROPY: Das Feld model wird nicht ausgefüllt.
• CLIENT_HINTS_HIGH_ENTROPY: Das Feld model wird nur für das Gerätemodell von Mobilgeräten ausgefüllt. Für Desktop-Plattformen ist kein Wert festgelegt.

Quelle

Gibt an, welche Überschriften zum Erstellen von UserAgent verwendet wurden. Bei Client-Hinweisen wird auch zwischen den folgenden beiden Fällen unterschieden:

• CLIENT_HINTS_LOW_ENTROPY: Nur grundlegende Client-Hints sind verfügbar.
• CLIENT_HINTS_HIGH_ENTROPY: Client-Hinweise sind verfügbar, einschließlich mindestens eines Felds, das als „hohe Entropie“ klassifiziert ist.