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

# Bibliothèque d'aide à la vérification tierce

> Utilisez @topsort/verification pour insérer des tags de vérification IAS dans les publicités bannière après le consentement de l'acheteur.

Les annonceurs peuvent utiliser des fournisseurs de vérification tierce, tels qu'IAS et DoubleVerify, pour mesurer de manière indépendante si leurs publicités se sont affichées et étaient visibles. Ces fournisseurs exécutent un petit script sur la page, aux côtés de la publicité.

Cela nécessite deux éléments :

1. Le tag du fournisseur doit voyager avec le créatif, de la configuration de campagne jusqu'à la réponse d'enchère.
2. Le storefront doit insérer le script dans la bannière rendue après que l'acheteur a donné son consentement.

Topsort prend déjà en charge le transport des tags de vérification via des modèles JSON de bannière. Les marketplaces peuvent implémenter elles-mêmes la gestion du consentement et l'insertion du script, ou utiliser la bibliothèque `@topsort/verification` pour gérer ces étapes.

La bibliothèque d'aide prend actuellement en charge **IAS uniquement**. Elle réduit le code personnalisé nécessaire pour gérer l'insertion des tags, les re-renders de bannières, la rotation des publicités et les changements de consentement.

La bibliothèque est disponible pour tous les clients Topsort et fonctionne avec ou sans Banners.js. Suivez les étapes ci-dessous pour un moteur de rendu de bannières personnalisé. Si vous utilisez Banners.js, consultez aussi [Utilisation de Banners.js](#utilisation-de-bannersjs).

## Avant de commencer

* Vos bannières doivent utiliser des [modèles JSON](/fr/knowledge-base/ad-platform/banners/native-ads-banners-templating), qui définissent des champs créatifs nommés.
* Vous avez besoin d'une **Consent Management Platform (CMP)** pour collecter et enregistrer le consentement de l'acheteur. Topsort et cette bibliothèque ne fournissent pas de CMP. Vous connectez la bibliothèque à votre CMP existante via un adaptateur de consentement.

## Étape 1 : Configurer le modèle de bannière

Lors de la création du modèle de bannière, incluez un champ texte nommé `verificationTag`. Ce champ contient le tag de vérification de l'annonceur.

Vous pouvez utiliser un autre nom de champ, à condition que votre storefront lise le même nom dans la réponse d'enchère. Ce guide utilise `verificationTag`.

## Étape 2 : Fournir le tag de vérification

Lors de la création de campagne, l'annonceur colle dans le champ du modèle le tag fourni par son fournisseur de vérification.

Pour la prise en charge IAS actuelle de la bibliothèque, la valeur acceptée est exactement un tag script externe :

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

La bibliothèque valide le tag selon les exigences suivantes :

* L'URL doit utiliser HTTPS.
* Le hostname doit être `staticjs.adsafeprotected.com`.
* Le chemin doit être `/fw.js`.
* L'URL doit contenir exactement un `advEntityId` numérique et un `pubEntityId` numérique.
* Le JavaScript inline, les attributs supplémentaires, les éléments supplémentaires, les autres hôtes, les ports explicites et les fragments d'URL sont rejetés.

Si le tag est rejeté, la bibliothèque n'insère pas de script. La bannière continue de s'afficher normalement.

## Étape 3 : Lire le tag dans la réponse d'enchère

Les champs du modèle sont renvoyés dans l'objet `content` de l'asset gagnant. Lisez `verificationTag` en même temps que l'URL de l'image, le titre et les autres champs créatifs.

Dans la réponse d'enchère brute, il s'agit de `winner.asset[index].content.verificationTag`, où `index` identifie l'asset que vous affichez.

Les exemples ci-dessous supposent que votre application mappe l'objet `content` de cet asset vers `banner.content` et le `resolvedBidId` du gagnant vers `banner.resolvedBidId`. Il s'agit de mappings au niveau de l'application, pas d'un format de réponse d'enchère différent.

## Étape 4 : Enregistrer la bannière rendue

La bibliothèque insère le script validé dans le conteneur de la bannière une fois le consentement accordé. Elle gère aussi les changements d'enregistrement lorsque les bannières sont re-rendues, rotées ou retirées.

Trois termes apparaissent dans les exemples :

* **Runtime :** L'objet renvoyé par `createVerificationRuntime(...)`. Il se connecte à votre adaptateur de consentement et suit les éléments de bannière enregistrés. Créez un runtime pour la page et réutilisez-le pour toutes les bannières.
* **Register :** L'appel à `register(...)` fournit l'élément de bannière, le tag de vérification et la clé de rendu. La bibliothèque vérifie le consentement avant d'insérer le script.
* **Handle :** L'objet renvoyé par `register(...)`. Sa méthode `dispose()` termine l'enregistrement et supprime le nœud script inséré par la bibliothèque.

Créez l'adaptateur `consentSource` décrit dans [Connectez votre CMP](#connectez-votre-cmp), puis enregistrez chaque bannière une fois son élément conteneur disponible :

```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` distingue un re-render de la même publicité d'une nouvelle publicité rendue dans le même élément. L'enregistrement d'un nouveau `renderKey` sur le même élément démonte et remplace automatiquement l'enregistrement précédent.

Gardez la clé stable pour les re-renders de la même publicité, et changez-la pour le rendu d'une nouvelle publicité.

Si `element` n'est pas un élément valide, si le tag est vide ou si `renderKey` est vide, `register` ne fait rien et ne charge rien. Il ne lève pas d'erreur dans votre code de rendu de bannières.

### Utilisation de React

Pour React, créez le runtime une fois dans un module partagé et importez-le partout où vous rendez des bannières. Ne le créez pas à l'intérieur d'un composant, où des montages répétés créeraient des runtimes et des abonnements de consentement distincts.

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

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

Utilisez le helper React pour connecter le runtime à l'élément de bannière :

```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` renvoie un callback ref. React l'appelle avec le nœud DOM au montage de la bannière et avec `null` au démontage. Le helper enregistre la bannière et gère le nettoyage, vous n'appelez donc pas `dispose()` vous-même.

## Connectez votre CMP

La bibliothèque n'affiche aucune UI de consentement et ne communique pas directement avec votre CMP. Vous fournissez un adaptateur avec deux fonctions :

* `current()` renvoie l'état de consentement actuel.
* `subscribe(listener)` signale les changements de consentement et renvoie une fonction qui arrête l'écoute.

Choisissez le purpose CMP applicable à la mesure du fournisseur, puis mappez son état vers `"unknown"`, `"granted"` ou `"denied"`.

L'exemple suivant illustre la structure de l'adaptateur. Remplacez `readMyCmp()` et `myCmp.on/off` par les APIs réelles de votre 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);
  },
};
```

La bibliothèque répond à chaque état comme suit :

* **`unknown` :** Attend sans parser le tag, récupérer le script du fournisseur ni modifier le DOM.
* **`granted` :** Valide le tag, crée un nouvel élément `<script>` à partir du `src` validé et l'ajoute dans l'élément de bannière. Elle n'insère pas de markup stocké via `innerHTML`.
* **`denied` :** Termine l'enregistrement sans charger le script.

Renvoyez l'état de consentement réel de votre CMP. Forcer `"granted"` contourne le contrôle du consentement et permet à IAS de se charger dès l'enregistrement de la bannière.

Si le consentement est retiré plus tard, la bibliothèque termine l'enregistrement et supprime son propre nœud script. Elle ne peut pas annuler le code fournisseur déjà exécuté, les requêtes déjà envoyées, les globals déjà définis ni le stockage déjà écrit. Le nettoyage est au mieux et ne couvre que le nœud script créé par la bibliothèque.

## Vérifier l'intégration

Passez un callback `onDiagnostic` à la création du runtime pour recevoir des codes d'état tels que :

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

Les diagnostics incluent le nom du fournisseur et les millisecondes écoulées. Ils n'incluent pas le tag brut, la query d'URL ni le contenu de la page.

**`active` signifie seulement que le script du fournisseur a fini de se charger.** Cela ne confirme pas qu'IAS a enregistré une impression, considéré la publicité comme visible ou accepté les données. Confirmez la mesure dans les rapports IAS.

## Content Security Policy

Si votre storefront utilise une Content Security Policy (CSP), autorisez `staticjs.adsafeprotected.com` dans `script-src` pour que le navigateur puisse charger le script IAS.

Ceci n'est pas une allowlist de production complète. L'ensemble des origines IAS requises pour `script-src`, `connect-src`, `img-src` et `frame-src` reste soumis à la validation côté IAS.

## Utilisation de Banners.js

La même configuration de modèle et le même adaptateur de consentement s'appliquent lorsque vous utilisez [Banners.js](/fr/ad-platform/banners/bannersjs).

Après que Banners.js a rendu une bannière et déclenché son événement `ready` :

1. Identifiez l'élément conteneur de la bannière rendue.
2. Lisez `verificationTag` dans le content de modèle du créatif gagnant.
3. Enregistrez l'élément, le tag et la clé de rendu auprès du runtime de vérification, comme indiqué à l'étape 4.

Disposez l'enregistrement lorsque la bannière est retirée ou rotée. Lors de l'enregistrement d'une nouvelle clé de rendu sur le même élément, la bibliothèque remplace automatiquement l'enregistrement précédent.