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

Les annonceurs peuvent utiliser des fournisseurs de vérification tierce, tels qu’IAS, 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 :

Le tag du fournisseur doit voyager avec le créatif, de la configuration de campagne jusqu’à la réponse d’enchère.
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 version initiale 0.1.0 prend en charge les moteurs de rendu personnalisés de bannières web avec des tags de monitoring IAS. Elle n’inclut pas encore d’intégration automatique avec Banners.js, d’autres fournisseurs de vérification, la mesure dans les applications mobiles natives ni l’installation directe par <script>.

Avant de commencer

Vos bannières doivent utiliser des modèles JSON, 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.

Installez le package dans une application basée sur npm :

npm install @topsort/verification

Le package est un module ES destiné aux applications et aux bundlers. Il ne fournit pas de build IIFE pour une installation directe via un <script> du navigateur.

É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 :

<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é. Votre moteur de rendu doit enregistrer chaque bannière après la connexion de son élément et supprimer l’enregistrement lorsque la bannière est retirée. Une clé de rendu différente sur le même élément remplace automatiquement l’enregistrement précédent. 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, puis enregistrez chaque bannière une fois son élément conteneur disponible :

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é. Un tag vide ne charge rien et supprime en toute sécurité tout enregistrement précédent du même élément. Les éléments non valides, les clés de rendu vides et les tags non vides mal formés ne chargent rien et produisent des diagnostics limités. Ces conditions ne lèvent 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.

// 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 :

// 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 :

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

Un consentement refusé est définitif pour cet enregistrement. S’il est accordé plus tard, enregistrez à nouveau la bannière ou rechargez la page. Le retrait du consentement et l’échec du fournisseur sont également définitifs ; créez un nouvel enregistrement après avoir corrigé la cause. 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
consent_withdrawn
consent_source_failed
element_not_ready
runtime_disposed

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.

Banners.js

L’intégration automatique avec Banners.js ne fait pas partie de 0.1.0. Une intégration personnalisée ne peut utiliser le runtime que si elle fournit l’élément rendu exact, verificationTag et resolvedBidId, et supprime l’enregistrement selon le cycle de vie de la bannière. La prise en charge directe de Banners.js sera documentée séparément lorsqu’elle sera disponible.

Aperçu

Plateforme Publicitaire

Serveur Publicitaire

Toppie

Intégrations Avancées

API

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

Avant de commencer

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

Étape 2 : Fournir le tag de vérification

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

Étape 4 : Enregistrer la bannière rendue

Utilisation de React

Connectez votre CMP

Vérifier l’intégration

Content Security Policy

Banners.js

​Avant de commencer

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

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

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

​Étape 4 : Enregistrer la bannière rendue

​Utilisation de React

​Connectez votre CMP

​Vérifier l’intégration

​Content Security Policy

​Banners.js

Avant de commencer

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

Étape 2 : Fournir le tag de vérification

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

Étape 4 : Enregistrer la bannière rendue

Utilisation de React

Connectez votre CMP

Vérifier l’intégration

Content Security Policy

Banners.js