> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hilfsbibliothek für Drittanbieter-Verifizierung

> Verwenden Sie @topsort/verification, um IAS-Verifizierungstags nach der Einwilligung des Käufers in Banneranzeigen einzufügen.

Advertiser können Drittanbieter-Verifizierungsanbieter wie IAS und DoubleVerify nutzen, um unabhängig zu messen, ob ihre Anzeigen gerendert und sichtbar waren. Diese Anbieter führen ein kleines Script auf der Seite neben der Anzeige aus.

Dafür sind zwei Dinge erforderlich:

1. Der Tag des Anbieters muss mit dem Creative mitreisen, von der Kampagneneinrichtung bis zur Auktionsantwort.
2. Der Storefront muss das Script in das gerenderte Banner einfügen, nachdem der Käufer die Einwilligung erteilt hat.

Topsort unterstützt bereits das Mitführen von Verifizierungstags über JSON-Banner-Vorlagen. Marketplaces können Einwilligungsverarbeitung und Script-Einfügung selbst implementieren oder die Bibliothek `@topsort/verification` verwenden, um diese Schritte zu übernehmen.

Die Hilfsbibliothek unterstützt derzeit **nur IAS**. Sie reduziert den Custom-Code, der für Tag-Einfügung, Banner-Re-Renders, Anzeigenrotation und Einwilligungsänderungen nötig ist.

Die Bibliothek steht allen Topsort-Kunden zur Verfügung und funktioniert mit oder ohne Banners.js. Folgen Sie den Schritten unten für einen eigenen Banner-Renderer. Wenn Sie Banners.js verwenden, siehe auch [Banners.js verwenden](#bannersjs-verwenden).

## Bevor Sie beginnen

* Ihre Banner müssen [JSON-Vorlagen](/de/knowledge-base/ad-platform/banners/native-ads-banners-templating) verwenden, die benannte Creative-Felder definieren.
* Sie brauchen eine **Consent Management Platform (CMP)**, um die Einwilligung des Käufers zu erfassen und zu speichern. Topsort und diese Bibliothek stellen keine CMP bereit. Sie verbinden die Bibliothek über einen Consent-Adapter mit Ihrer vorhandenen CMP.

## Schritt 1: Banner-Vorlage konfigurieren

Fügen Sie beim Erstellen der Banner-Vorlage ein Textfeld namens `verificationTag` hinzu. Dieses Feld enthält den Verifizierungstag des Advertisers.

Sie können einen anderen Feldnamen verwenden, sofern Ihr Storefront denselben Namen aus der Auktionsantwort liest. Dieser Guide verwendet `verificationTag`.

## Schritt 2: Verifizierungstag bereitstellen

Bei der Kampagnenerstellung fügt der Advertiser den vom Verifizierungsanbieter gelieferten Tag in das Vorlagenfeld ein.

Für die aktuelle IAS-Unterstützung der Bibliothek ist der akzeptierte Wert genau ein externes Script-Tag:

```html theme={null}
<script
  type="application/javascript"
  src="https://staticjs.adsafeprotected.com/fw.js?advEntityId=3072912&pubEntityId=96261444"
></script>
```

Die Bibliothek prüft den Tag anhand der folgenden Anforderungen:

* Die URL muss HTTPS verwenden.
* Der Hostname muss `staticjs.adsafeprotected.com` sein.
* Der Pfad muss `/fw.js` sein.
* Die URL muss genau eine numerische `advEntityId` und eine numerische `pubEntityId` enthalten.
* Inline-JavaScript, zusätzliche Attribute, zusätzliche Elemente, andere Hosts, explizite Ports und URL-Fragmente werden abgelehnt.

Wird der Tag abgelehnt, fügt die Bibliothek kein Script ein. Das Banner selbst wird weiterhin normal gerendert.

## Schritt 3: Tag aus der Auktionsantwort lesen

Die Vorlagenfelder werden im `content`-Objekt des gewinnenden Assets zurückgegeben. Lesen Sie `verificationTag` zusammen mit der Bild-URL, der Headline und den anderen Creative-Feldern.

In der rohen Auktionsantwort ist das `winner.asset[index].content.verificationTag`, wobei `index` das Asset identifiziert, das Sie rendern.

Die Beispiele unten gehen davon aus, dass Ihre Anwendung das `content`-Objekt dieses Assets auf `banner.content` und die `resolvedBidId` des Gewinners auf `banner.resolvedBidId` mappt. Das sind Mappings auf Anwendungsebene, kein anderes Auktionsantwortformat.

## Schritt 4: Gerenderten Banner registrieren

Die Bibliothek fügt das validierte Script nach erteilter Einwilligung in den Container des Banners ein. Sie verwaltet außerdem Registrierungsänderungen, wenn Banner neu gerendert, rotiert oder entfernt werden.

In den Beispielen kommen drei Begriffe vor:

* **Runtime:** Das Objekt, das `createVerificationRuntime(...)` zurückgibt. Es verbindet sich mit Ihrem Consent-Adapter und verfolgt registrierte Banner-Elemente. Erstellen Sie eine Runtime für die Seite und verwenden Sie sie für alle Banner wieder.
* **Register:** Der Aufruf von `register(...)` übergibt das Banner-Element, den Verifizierungstag und den Render-Key. Die Bibliothek prüft die Einwilligung, bevor sie das Script einfügt.
* **Handle:** Das Objekt, das `register(...)` zurückgibt. Die Methode `dispose()` beendet die Registrierung und entfernt den Script-Knoten, den die Bibliothek eingefügt hat.

Erstellen Sie den in [CMP verbinden](#cmp-verbinden) beschriebenen `consentSource`-Adapter und registrieren Sie dann jeden Banner, sobald sein Container-Element verfügbar ist:

```javascript theme={null}
import { createVerificationRuntime } from "@topsort/verification";
import { consentSource } from "./consent";

const verification = createVerificationRuntime({ consentSource });

const handle = verification.register({
  element: bannerRoot, // The DOM element containing the rendered banner.
  verificationTag: banner.content.verificationTag,
  renderKey: banner.resolvedBidId,
});

// When the banner is removed or rotated out:
handle.dispose();
```

`renderKey` unterscheidet einen Re-Render derselben Anzeige von einer neuen Anzeige, die in dasselbe Element gerendert wird. Das Registrieren eines neuen `renderKey` am selben Element baut die vorherige Registrierung automatisch ab und ersetzt sie.

Halten Sie den Key für Re-Renders derselben Anzeige stabil und ändern Sie ihn für das Rendern einer neuen Anzeige.

Wenn `element` kein gültiges Element ist, der Tag leer ist oder `renderKey` leer ist, tut `register` nichts und lädt nichts. Es wirft keinen Fehler in Ihren Banner-Rendering-Code.

### React verwenden

Für React erstellen Sie die Runtime einmal in einem gemeinsamen Modul und importieren Sie sie überall, wo Sie Banner rendern. Erstellen Sie sie nicht innerhalb einer Komponente, wo wiederholte Mounts getrennte Runtimes und Consent-Subscriptions erzeugen würden.

```typescript theme={null}
// verification.ts
import { createVerificationRuntime } from "@topsort/verification";
import { consentSource } from "./consent";

export const verification = createVerificationRuntime({ consentSource });
```

Verwenden Sie den React-Helper, um die Runtime mit dem Banner-Element zu verbinden:

```jsx theme={null}
// Banner.tsx
import { useVerificationRef } from "@topsort/verification/react";
import { verification } from "./verification";

function Banner({ banner }) {
  const ref = useVerificationRef(verification, {
    verificationTag: banner.content.verificationTag,
    renderKey: banner.resolvedBidId,
  });

  return <div ref={ref}>{/* Your existing banner markup. */}</div>;
}
```

`useVerificationRef` gibt einen Callback-Ref zurück. React ruft ihn mit dem DOM-Knoten auf, wenn der Banner gemountet wird, und mit `null`, wenn er unmountet. Der Helper registriert den Banner und übernimmt das Cleanup, sodass Sie `dispose()` nicht selbst aufrufen.

## CMP verbinden

Die Bibliothek zeigt keine Consent-UI und kommuniziert nicht direkt mit Ihrer CMP. Sie stellen einen Adapter mit zwei Funktionen bereit:

* `current()` gibt den aktuellen Einwilligungsstatus zurück.
* `subscribe(listener)` meldet Einwilligungsänderungen und gibt eine Funktion zurück, die das Lauschen beendet.

Wählen Sie den CMP-Purpose, der für Vendor-Messung gilt, und mappen Sie dessen Status auf `"unknown"`, `"granted"` oder `"denied"`.

Das folgende Beispiel zeigt die Adapterstruktur. Ersetzen Sie `readMyCmp()` und `myCmp.on/off` durch die tatsächlichen APIs Ihrer CMP:

```javascript theme={null}
// consent.js
export const consentSource = {
  current() {
    return readMyCmp(); // "unknown" | "granted" | "denied"
  },

  subscribe(listener) {
    const onChange = () => listener(readMyCmp());
    myCmp.on("change", onChange);

    return () => myCmp.off("change", onChange);
  },
};
```

Die Bibliothek reagiert auf jeden Status wie folgt:

* **`unknown`:** Wartet, ohne den Tag zu parsen, das Anbieter-Script zu laden oder das DOM zu ändern.
* **`granted`:** Validiert den Tag, erzeugt ein neues `<script>`-Element aus dem validierten `src` und hängt es in das Banner-Element ein. Gespeichertes Markup wird nicht über `innerHTML` eingefügt.
* **`denied`:** Beendet die Registrierung, ohne das Script zu laden.

Geben Sie den tatsächlichen Einwilligungsstatus Ihrer CMP zurück. Das Hardcoden von `"granted"` umgeht die Consent-Prüfung und erlaubt IAS, zu laden, sobald der Banner registriert ist.

Wird die Einwilligung später entzogen, beendet die Bibliothek die Registrierung und entfernt den eigenen Script-Knoten. Sie kann bereits ausgeführten Vendor-Code, bereits gesendete Requests, bereits gesetzte Globals oder bereits geschriebenen Storage nicht rückgängig machen. Cleanup ist Best-Effort und umfasst nur den von der Bibliothek erzeugten Script-Knoten.

## Integration prüfen

Übergeben Sie beim Erstellen der Runtime einen `onDiagnostic`-Callback, um Statuscodes wie die folgenden zu erhalten:

* `registered`
* `active`
* `consent_denied`
* `invalid_tag`
* `provider_load_failed`
* `provider_load_timeout`

Diagnosen enthalten den Anbieternamen und die verstrichenen Millisekunden. Sie enthalten nicht den Roh-Tag, die URL-Query oder den Seiteninhalt.

**`active` bedeutet nur, dass das Script des Anbieters fertig geladen wurde.** Es bestätigt nicht, dass IAS eine Impression erfasst, die Anzeige als sichtbar betrachtet oder die Daten akzeptiert hat. Bestätigen Sie die Messung in den IAS-Reports.

## Content Security Policy

Wenn Ihr Storefront eine Content Security Policy (CSP) verwendet, erlauben Sie `staticjs.adsafeprotected.com` in `script-src`, damit der Browser das IAS-Script laden kann.

Das ist keine vollständige Production-Allowlist. Die vollständige Menge der für `script-src`, `connect-src`, `img-src` und `frame-src` erforderlichen IAS-Origins bleibt von der Validierung durch IAS abhängig.

## Banners.js verwenden

Dieselbe Vorlagenkonfiguration und derselbe Consent-Adapter gelten beim Einsatz von [Banners.js](/de/ad-platform/banners/bannersjs).

Nachdem Banners.js ein Banner gerendert und das `ready`-Event ausgelöst hat:

1. Identifizieren Sie das Container-Element des gerenderten Banners.
2. Lesen Sie `verificationTag` aus dem Vorlagen-Content des gewinnenden Creatives.
3. Registrieren Sie Element, Tag und Render-Key beim Verification-Runtime, wie in Schritt 4 gezeigt.

Beenden Sie die Registrierung, wenn der Banner entfernt oder herausrotiert wird. Beim Registrieren eines neuen Render-Keys am selben Element ersetzt die Bibliothek automatisch die vorherige Registrierung.