Registra las fuentes de atribución

Obtén información para registrar fuentes y atribuir clics y vistas a los eventos adecuados.

Una fuente de atribución es un evento relacionado con el anuncio (un clic o una vista), al que una tecnología publicitaria puede adjuntar los siguientes tipos de información:

• Datos de informes contextuales, como el ID de la creatividad del anuncio, información sobre la campaña o la ubicación geográfica
• Un destino de conversión, como el sitio en el que esperas que el usuario genere una conversión.

Si sigues los pasos que se indican en este documento, podrás registrar las fuentes (impresiones de anuncios o clics) a las que el navegador luego atribuirá las conversiones.

Métodos de registro

Para registrar fuentes de atribución, usa elementos HTML o llamadas a JavaScript:

• Etiqueta <a>
• Etiqueta <img>
• Etiqueta <script>
• fetch llamada
• XMLHttpRequest
• window.open llamada

Esto genera solicitudes de red a las que respondes con un encabezado de respuesta HTTP de registro de fuente.

Registra fuentes de clics o vistas

Para registrar una fuente de atribución para los clics o las vistas, sigue los pasos que se describen aquí. A continuación, se indican los pasos completos. Aquí tienes un resumen:

1. Inicia el registro de la fuente. Usa un elemento HTML o una llamada a JavaScript para realizar una solicitud. Este paso es diferente para los clics y las vistas, como verás en las siguientes secciones.

2. Para completar el registro de la fuente, responde con el encabezado de registro de la fuente. Cuando recibas esa solicitud, responde con el encabezado Attribution-Reporting-Register-Source. En ese encabezado, especifica la configuración de los informes de atribución que elegiste. Este paso es el mismo para los clics y las vistas.

   Ejemplo de informes de resumen:

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

   Ejemplo de informes a nivel del evento:

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

Atributos obligatorios y opcionales

A medida que uses elementos HTML o realices llamadas a JavaScript para registrar fuentes, es posible que necesites usar attributionsrc o attributionReporting. Consulta la siguiente tabla para conocer los detalles sobre cuándo se requieren.

Cuando attributionsrc es opcional, su uso indica que la solicitud es apta para Attribution Reporting. Si usas attributionsrc, el navegador envía el encabezado Attribution-Reporting-Eligible. También es útil para la medición de app a Web: si attributionsrc está presente, el navegador envía el encabezado Attribution-Reporting-Support.

Paso 1: Inicia el registro de la fuente

El paso 1 es diferente para los clics y las vistas.

Para registrar una fuente de atribución para un clic, puedes usar una etiqueta <a> o window.open() de JavaScript.

Usa un ancla

Agrega attributionsrc a las etiquetas <a> existentes para las que deseas medir las impresiones o los clics:

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

Revisa el código de ejemplo para obtener más información.

Usa una secuencia de comandos

Llama a window.open() con attributionsrc:

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

Para que se tenga en cuenta, se debe llamar a este método en un plazo de 5 segundos después de la interacción del usuario.

En lugar de agregar attributionsrc por sí solo, para una imagen o una secuencia de comandos, puedes especificar un solo valor de URL:

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

En el caso de JavaScript, si le asignas un valor a attributionsrc, asegúrate de codificar esa URL en caso de que contenga caracteres especiales, como =, que provocarían que el parámetro se analice de forma incorrecta.

Codifica de la siguiente manera:

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

attributionsrc también puede aceptar una lista de URLs separadas por espacios, como se ilustra aquí con una etiqueta <a>:

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

o como se muestra aquí con window.open().

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

En esos casos, ambas URLs reciben solicitudes attributionsrc aptas para la fuente de navegación (solicitudes que incluyen el encabezado Attribution-Reporting-Eligible).

attributionsrc con o sin un valor

Como viste anteriormente, puedes especificar attributionsrc sin una URL. También puedes especificar una sola URL. Además, puedes usar una lista de URLs separadas por espacios.

El uso de URLs hace que el navegador inicie una solicitud de recuperación de keepalive separada, una para cada URL, que incluye el encabezado de solicitud Attribution-Reporting-Eligible.

Esto es útil si deseas realizar el registro de la fuente respondiendo a una solicitud que es independiente de la solicitud principal del elemento.

Por ejemplo, si necesitas registrar fuentes para los clics en un elemento de anclaje, es posible que no tengas el control del destino. En este caso, te recomendamos que configures el encabezado de registro de la fuente como una respuesta a una solicitud independiente de la navegación y que puedas controlar por completo. Cuando especificas un valor explícito para attributionsrc, le indicas al navegador que realice esa solicitud adicional y configures su destino.

Para registrar una fuente de atribución para una vista, puedes usar una etiqueta de imagen o de secuencia de comandos a la que agregarás el atributo attributionsrc.

Como alternativa, puedes usar fetch() o XMLHttpRequest() de JavaScript.

Con una imagen

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

Con una secuencia de comandos

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

De forma opcional, puedes especificar un valor de URL para attributionsrc de la misma manera que para los clics; es decir, para una imagen o una secuencia de comandos , puedes establecer la URL o las URLs de attributionsrc de la siguiente manera:

Con una sola URL:

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

Con una lista de URLs:

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

Usa fetch() o XMLHttpRequest()

Este código simula de manera eficaz lo que haría una solicitud HTML con attributionsrc:

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();

Paso 2: Responde con un encabezado (clics y vistas)

El siguiente paso para los clics y las vistas es responder con el encabezado Attribution-Reporting-Register-Source.

Revisa el código de ejemplo para obtener más información.

Cuando recibas la solicitud del navegador en el servidor, responde y, luego, incluye en tu respuesta el encabezado Attribution-Reporting-Register-Source.

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"
  })
);

Una vez convertido en cadena, el encabezado se verá de la siguiente manera:

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

Próximos pasos

Obtén información para registrar activadores de atribución.