Rota las creatividades de anuncios con la API de Select URL

Usa la API de Select URL para aprovechar Shared Storage y determinar qué creatividad ve un usuario en los sitios.

Un anunciante o un productor de contenido pueden querer aplicar diferentes estrategias de rotación de contenido a una campaña y rotar el contenido o las creatividades para aumentar la eficacia. La API de Select URL se puede usar para ejecutar diferentes estrategias de rotación, como la rotación secuencial y la rotación distribuida de manera uniforme, en diferentes sitios.

Con la rotación de creatividades de la API de Select URL, puedes almacenar datos, como el ID de la creatividad, los recuentos de vistas y la interacción del usuario, para determinar qué creatividad ven los usuarios en los diferentes sitios.

Para obtener más información sobre la API subyacente y cómo funciona la selección, explora la documentación de la API de Select URL.

Prueba la rotación de creatividades

Para experimentar con la rotación de creatividades, asegúrate de que la API de Select URL y el almacenamiento compartido estén habilitados:

• En chrome://settings/content/siteData, selecciona Allow sites to save data on your device o Delete data sites have saved to your device when you close all windows.
• En chrome://settings/adPrivacy/sites, selecciona Site-suggested ads.

Prueba nuestra demostración en vivo de Shared Storage para ver una versión en vivo de las muestras de código de este documento.

Demostración con muestras de código

En este ejemplo:

• creative-rotation.js es la secuencia de comandos de terceros que define el contenido que se rotará, junto con los datos que determinan el próximo contenido que se seleccionará y mostrará, como los pesos en este ejemplo. La página del publicador ejecuta este código. Esta secuencia de comandos llama al worklet de almacenamiento compartido para determinar qué contenido mostrar según los datos disponibles en el almacenamiento y la lista de URLs para seleccionar.

• creative-rotation-worklet.js es el worklet de almacenamiento compartido de terceros que busca la estrategia de rotación, calcula qué contenido publicar a continuación y devuelve ese contenido.

Cómo funciona la demostración

1. Cuando un usuario visita la página del publicador, esta carga la secuencia de comandos creative-rotation.js de terceros. La secuencia de comandos de rotación de creatividades es responsable de cargar y ejecutar el worklet de almacenamiento compartido. La secuencia de comandos proporciona la llamada al worklet con una lista de URLs para seleccionar.
2. En el worklet, si aún no se inicializó el almacenamiento compartido, se inicializa con la estrategia de rotación de creatividades y el índice de creatividades iniciales. La estrategia de rotación inicial que se usa en esta demostración es la estrategia secuencial.
3. El worklet lee el modo de rotación del almacenamiento compartido y devuelve el índice del próximo anuncio. En el caso del modo de rotación secuencial, también actualiza el índice de creatividad en el almacenamiento compartido con el nuevo valor que se usará para la próxima llamada.El worklet devuelve un objeto FencedFrameConfig o un URN opaco según el valor de resolveToConfig que se usó cuando se llamó a selectURL.
4. La secuencia de comandos de rotación de creatividades muestra el anuncio seleccionado en un Fenced Frame o un iframe. Consulta el documento sobre cómo renderizar un anuncio para obtener detalles sobre los tipos de devolución.
5. Cuando un usuario cambia el modo de rotación, el worklet de Shared Storage actualiza el valor del modo de rotación de la creatividad almacenado en Shared Storage.
6. Cuando se vuelve a cargar la página del publicador, se repiten los pasos del 1 al 4, lo que permite seleccionar el siguiente anuncio que se verá según la estrategia de rotación seleccionada.

Muestras de código

A continuación, se incluyen las muestras de código para creative-rotation.js y creative-rotation-worklet.js.

creative-rotation.js

const contentProducerUrl = 'https://your-server.example';

// Ad config with the URL of the ad, a probability weight for rotation, and the clickthrough rate.
const DEMO_AD_CONFIG = [
  {
    url: `${contentProducerUrl}/ads/ad-1.html`,
    weight: 0.7,
  },
  {
    url: `${contentProducerUrl}/ads/ad-2.html`,
    weight: 0.2,
  },
  {
    url: `${contentProducerUrl}/ads/ad-3.html`,
    weight: 0.1,
  },
];

async function setRotationMode(rotationMode) {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  await creativeRotationWorklet.run('set-rotation-mode', {
    data: { rotationMode }
  });
  console.log(`creative rotation mode set to ${rotationMode}`);
}

async function injectAd() {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  const urls = DEMO_AD_CONFIG.map(({ url }) => ({ url }));

  // Resolve the selectURL call to a fenced frame config only when it exists on the page
  const resolveToConfig = typeof window.FencedFrameConfig !== 'undefined';

  // Run the URL selection operation to determine the next ad that should be rendered
  const selectedUrl = await creativeRotationWorklet.selectURL('creative-rotation', urls, {
    data: DEMO_AD_CONFIG,
    resolveToConfig
  });

  const adSlot = document.getElementById('ad-slot');

  if (resolveToConfig && selectedUrl instanceof FencedFrameConfig) {
    adSlot.config = selectedUrl;
  } else {
    adSlot.src = selectedUrl;
  }
}

injectAd();

creative-rotation-worklet.js

class SelectURLOperation {
  async run(urls, data) {
    // Initially set the storage to sequential mode for the demo
    await SelectURLOperation.seedStorage();

    // Read the rotation mode from Shared Storage
    const rotationMode = await sharedStorage.get('creative-rotation-mode');

    // Generate a random number to be used for rotation
    const randomNumber = Math.random();

    let index;

    switch (rotationMode) {
      /**
       * Sequential rotation
       * - Rotates the creatives in order
       * - Example: A -> B -> C -> A ...
       */
      case 'sequential':
        const currentIndex = await sharedStorage.get('creative-rotation-index');
        index = parseInt(currentIndex, 10);
        const nextIndex = (index + 1) % urls.length;

        console.log(`index = ${index} / next index = ${nextIndex}`);

        await sharedStorage.set('creative-rotation-index', nextIndex.toString());
        break;

      /**
       * Evenly-distributed rotation
       * - Rotates the creatives with equal probability
       * - Example: A=33% / B=33% / C=33%
       */
      case 'even-distribution':
        index = Math.floor(randomNumber * urls.length);
        break;

      /**
       * Weighted rotation
       * - Rotates the creatives with weighted probability
       * - Example: A=70% / B=20% / C=10%
       */
      case 'weighted-distribution':
        console.log('data = ', JSON.stringify(data));
        // Find the first URL where the cumnulative sum of the weights
        // exceed the random number. The array is sorted by the weight
        // in descending order.
        let weightSum = 0;
        const { url } = data
          .sort((a, b) => b.weight - a.weight)
          .find(({ weight }) => {
            weightSum += weight;
            return weightSum > randomNumber;
          });

        index = urls.indexOf(url);
        break;

      default:
        index = 0;
    }

    console.log(JSON.stringify({ index, randomNumber, rotationMode }));
    return index;
  }

  // Set the mode to sequential and set the starting index to 0.
  static async seedStorage() {
    await sharedStorage.set('creative-rotation-mode', 'sequential', {
      ignoreIfPresent: true,
    });

    await sharedStorage.set('creative-rotation-index', 0, {
      ignoreIfPresent: true,
    });
  }
}

class SetRotationModeOperation {
  async run({ rotationMode }) {
    await sharedStorage.set('creative-rotation-mode', rotationMode);
  }
}

// Register the operation as 'creative-rotation'
register('creative-rotation', SelectURLOperation);
register('set-rotation-mode', SetRotationModeOperation);

Explicación con capturas de pantalla

1. Para acceder a la rotación de creatividades con la API de Select URL y el almacenamiento compartido, ve a https://shared-storage-demo.web.app/. Elige la demostración de "Rotación de creatividades".

2. Elige explorar la demostración como "Publicador A". Se te redireccionará a https://shared-storage-demo-publisher-a.web.app/creative-rotation. La página carga contenido numerado según los datos de rotación de creatividades guardados en el almacenamiento compartido, al que se accede a través de la API de Select URL. Los modos de demostración para la rotación de creatividades son secuencial, distribución uniforme y distribución ponderada. El worklet ejecuta la lógica para seleccionar el contenido que aparece en el iframe. En la siguiente imagen, se muestra la página del publicador.

   
   

3. Para ver lo que se almacena en Shared Storage, navega a Application -> Shared Storage en las Herramientas para desarrolladores de Chrome. Se crean dos entradas para el almacenamiento compartido. Hay un almacenamiento vacío disponible para el origen https://shared-storage-demo-publisher-a.web.app. Contendrá el almacenamiento específico de ese origen y permanecerá vacío para nuestra demostración, ya que el publicador no necesita escribir en el almacenamiento compartido. Ten en cuenta que se creará un almacenamiento similar para el Publicador B cuando visites esa página más adelante para la demostración.

   
   

4. Se creará otra entrada de Shared Storage para el origen https://shared-storage-demo-content-producer.web.app. Es el almacenamiento del iframe de terceros incorporado en la página del publicador. Este almacenamiento se usará para compartir datos entre los dos publicadores disponibles y coordinar la selección de creatividades. Este almacenamiento compartido se usará para guardar información sobre la creatividad que se muestra y la estrategia de rotación guardando dos pares clave-valor. La primera clave que se usa en la demostración es creative-rotation-index, cuyo valor es el índice de creatividad actual en el modo secuencial. La segunda clave es creative-rotation-mode, que determina la estrategia de rotación que se usa.

   
   

5. Si actualizas la página en el modo secuencial, se mostrará la siguiente creatividad de la secuencia 1, 2, 3, 1… El valor de la clave creative-rotation-index cambiará según el índice de la creatividad que se muestre en el modo secuencial.

   
   

6. Si cambias el modo de rotación de creatividades con los botones de control, se actualizará el valor de creative-rotation-mode clave en la estrategia correspondiente. El código del worklet usará este valor para elegir la próxima creatividad que se mostrará en el iframe. Ten en cuenta que el valor guardado para creative-rotation-index no cambia para los modos de rotación que no sean secuenciales.

   
   

7. Navega a la página del "Publicador B" en https://shared-storage-demo-publisher-b.web.app/creative-rotation. En el modo secuencial, la creatividad que se muestra debe ser la siguiente en la secuencia que se muestra cuando se visita la URL del "Publicador A". Si inspeccionas el almacenamiento compartido del productor de contenido, puedes ver que tanto el "Publicador A" como el "Publicador B" comparten el mismo almacenamiento y usan la configuración allí establecida para seleccionar la próxima creatividad que se mostrará y la estrategia de rotación que se usará.

   
   

8. El almacenamiento compartido de "Publicador B" está vacío, de forma similar al almacenamiento compartido de "Publicador A".

   
   

   Casos prácticos

   En esta sección, encontrarás todos los casos de uso disponibles para la API de Select URL. Seguiremos agregando ejemplos a medida que recibamos comentarios y descubramos nuevos casos de prueba.

   • Rota las creatividades de anuncios: Almacena datos, como el ID de la creatividad y la interacción del usuario, para determinar qué creatividades ven los usuarios en diferentes sitios.
   • Seleccionar creatividades de anuncios por frecuencia: Usa los datos del recuento de vistas para determinar qué creatividades ven los usuarios en diferentes sitios.
   • Ejecuta pruebas A/B: Puedes asignar un usuario a un grupo de experimentos y, luego, almacenar ese grupo en Shared Storage para acceder a él en varios sitios.
   • Personaliza la experiencia para clientes conocidos: Comparte contenido personalizado y llamados a la acción en función del estado de registro de un usuario o de otros estados.

Interactúa y comparte comentarios

Ten en cuenta que la propuesta de la API de Select URL está en debate y desarrollo activos, y está sujeta a cambios.

Nos encantaría conocer tu opinión sobre la API de Select URL.

• Propuesta: Revisa la propuesta detallada.
• Debate: Únete al debate en curso para hacer preguntas y compartir tu opinión.