Enregistrer des sources d'attribution

Découvrez comment enregistrer des sources pour attribuer les clics et les vues aux événements appropriés.

Une source d'attribution est un événement lié à une annonce (clic ou vue) auquel une technologie publicitaire peut associer les types d'informations suivants :

• Données de reporting contextuelles, telles que l'ID de la création publicitaire, des informations sur la campagne ou la zone géographique.
• Une destination de conversion, c'est-à-dire le site sur lequel vous souhaitez que l'utilisateur effectue une conversion.

En suivant les étapes décrites dans ce document, vous pouvez enregistrer des sources (impressions ou clics sur des annonces) auxquelles le navigateur attribue ensuite les conversions.

Méthodes d'inscription

Pour enregistrer des sources d'attribution, utilisez des éléments HTML ou des appels JavaScript :

• Balise <a>
• Balise <img>
• Balise <script>
• fetch appel
• XMLHttpRequest
• window.open appel

Cela génère des requêtes réseau auxquelles vous répondez ensuite avec un en-tête de réponse HTTP d'enregistrement de source.

Enregistrer des sources pour les clics ou les vues

Pour enregistrer une source d'attribution pour les clics ou les vues, suivez les étapes décrites ici. Voici la procédure complète : Voici le résumé :

1. Lancez l'enregistrement de la source. Utilisez un élément HTML ou un appel JavaScript pour effectuer une requête. Cette étape est différente pour les clics et les vues, comme vous le verrez dans les sections suivantes.

2. Terminez l'enregistrement de la source en répondant avec l'en-tête d'enregistrement de la source. Lorsque vous recevez cette requête, répondez avec l'en-tête Attribution-Reporting-Register-Source. Dans cet en-tête, spécifiez la configuration choisie pour Attribution Reporting. Cette étape est identique pour les clics et les vues.

   Exemple de rapport récapitulatif :

   {
     "aggregation_keys": {
       "campaignCounts": "0x159",
       "geoValue": "0x5"
     },
     "aggregatable_report_window": "86400",
     "destination": "https://example.com"
   }
   

   Exemple pour les rapports au niveau des événements :

   {
     "source_event_id": "12340873456",
     "destination": "[eTLD+1]",
     "expiry": "[64-bit signed integer]",
     "priority": "[64-bit signed integer]",
     "event_report_window": "[64-bit signed integer]"
   }
   

Attributs obligatoires et facultatifs

Lorsque vous utilisez des éléments HTML ou effectuez des appels JavaScript pour enregistrer des sources, vous devrez peut-être utiliser attributionsrc ou attributionReporting. Pour savoir quand ces informations sont requises, consultez le tableau ci-dessous.

Lorsque attributionsrc est facultatif, son utilisation indique que la requête est éligible aux rapports sur l'attribution. Si vous utilisez attributionsrc, le navigateur envoie l'en-tête Attribution-Reporting-Eligible. Il est également utile pour la mesure des applications vers le Web : si attributionsrc est présent, le navigateur envoie l'en-tête Attribution-Reporting-Support.

Étape 1 : Lancez l'enregistrement de la source

L'étape 1 diffère selon qu'il s'agit de clics ou de vues.

Pour enregistrer une source d'attribution pour un clic, vous pouvez utiliser une balise <a> ou JavaScript window.open().

Utiliser une ancre

Ajoutez attributionsrc aux balises <a> existantes pour lesquelles vous souhaitez mesurer les impressions ou les clics :

<a href="https://shoes.example/..." attributionsrc>Click me</a>

Pour en savoir plus, consultez l'exemple de code.

Avec un script

Appeler window.open() avec attributionsrc :

window.open(
  "https://shoes.example/...",
  "_blank",
  "attributionsrc");

Pour être prise en compte, cette méthode doit être appelée dans les cinq secondes suivant l'interaction de l'utilisateur.

Au lieu d'ajouter attributionsrc seul, vous pouvez spécifier une seule valeur d'URL pour une image ou un script :

<a href=... attributionsrc="https://a.example/register-source">Click me</a>

Dans le cas de JavaScript, si vous attribuez une valeur à attributionsrc, veillez à encoder cette URL au cas où elle contiendrait des caractères spéciaux tels que =, qui pourraient entraîner une analyse incorrecte du paramètre.

Encodez comme suit :

const encodedUrl = encodeURIComponent(
  "https://adtech.example/attribution_source?ad_id=...");
window.open(
  "https://shoes.example/landing",
   "_blank",
   `attributionsrc=${encodedUrl}`);

attributionsrc peut également accepter une liste d'URL séparées par un espace, comme illustré ici avec une balise <a> :

<a href=... attributionsrc="https://a.example/register-source
  https://b.example/register-source">Click me</a>

ou comme ici en utilisant window.open().

window.open("...", "_blank", `attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2}`)

Dans ce cas, les deux URL reçoivent des requêtes attributionsrc éligibles à la source de navigation (requêtes qui incluent l'en-tête Attribution-Reporting-Eligible).

attributionsrc avec ou sans valeur

Comme vous l'avez vu précédemment, vous pouvez spécifier attributionsrc sans URL. Vous pouvez également spécifier une seule URL. Vous pouvez également utiliser une liste d'URL séparées par un espace.

L'utilisation d'URL entraîne l'initiation par le navigateur d'une requête de récupération keep-alive distincte (une pour chaque URL), qui inclut l'en-tête de requête Attribution-Reporting-Eligible.

Cette option est utile si vous souhaitez enregistrer la source en répondant à une requête distincte de la requête principale de l'élément.

Par exemple, si vous devez enregistrer des sources pour des clics sur un élément d'ancrage, vous ne contrôlez peut-être pas la destination. Dans ce cas, vous aurez besoin d'une configuration dans laquelle vous envoyez l'en-tête d'enregistrement de la source en réponse à une requête distincte de la navigation et que vous pouvez contrôler entièrement. En spécifiant une valeur explicite pour attributionsrc, vous demandez au navigateur d'effectuer cette requête supplémentaire et vous configurez sa destination.

Pour enregistrer une source d'attribution pour une vue, vous pouvez utiliser une balise d'image ou de script à laquelle vous ajouterez l'attribut attributionsrc.

Vous pouvez également utiliser les fonctions JavaScript fetch() ou XMLHttpRequest().

Avec une image

<img attributionsrc
src="https://adtech.example/attribution_source?ad_id=...">

Avec un script

<script attributionsrc
  src="https://adtech.example/attribution_source?ad_id=..."></script>

Vous pouvez éventuellement spécifier une valeur d'URL pour attributionsrc de la même manière que pour les clics. Autrement dit, pour une image ou un script, vous pouvez définir l'URL ou les URL attributionsrc comme suit :

Avec une seule URL :

<img attributionsrc="https://adtech.example/attribution_source?ad_id=123">

Avec une liste d'URL :

<img attributionsrc="https://a.example/register-source
  https://b.example/register-source">

Utiliser fetch() ou XMLHttpRequest()

Ce code simule efficacement ce qu'une requête HTML avec attributionsrc ferait :

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

// Optionally set keepalive to make sure the request outlives the page.
window.fetch("https://adtech.example/attribution_source?my_ad_id=123",
  { keepalive: true, attributionReporting });

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

const req = new XMLHttpRequest();
req.open("GET", url);
req.setAttributionReporting(attributionReporting);
req.send();

Étape 2 : Répondez avec un en-tête (clics et vues)

L'étape suivante pour les clics et les vues consiste à répondre avec l'en-tête Attribution-Reporting-Register-Source.

Pour en savoir plus, consultez l'exemple de code.

Lorsque vous recevez la requête du navigateur sur le serveur, répondez et incluez l'en-tête Attribution-Reporting-Register-Source dans votre réponse.

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    // Use source_event_id to map it to any granular information
    // you need at ad-serving time
    source_event_id: "412444888111012",
    destination: "https://advertiser.example",
    // Optional fields
    expiry: "604800",
    priority: "100",
    debug_key: "122939999"
  })
);

Une fois la chaîne convertie, votre en-tête se présente comme suit :

{"source_event_id":"412444888111012","destination":"https://advertiser.example","expiry":"604800","priority":"100","debug_key":"122939999"}

Étapes suivantes

Découvrez comment enregistrer des déclencheurs d'attribution.