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 todos los sitios.

Es posible que un anunciante o un productor de contenido desee 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 forma 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é creatividades ven los usuarios en 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 las APIs de Select URL y Shared Storage estén habilitadas:

• 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 almacenamiento compartido para obtener 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 siguiente contenido que se seleccionará y mostrará, como los pesos en este ejemplo. La página del publicador ejecuta esta secuencia de comandos. Esta secuencia de comandos llama a la worklet de almacenamiento compartido para determinar qué contenido mostrar en función de los datos disponibles en el almacenamiento y la lista de URLs de las que se puede seleccionar.

• creative-rotation-worklet.js es la tarea del almacenamiento compartido de terceros que busca la estrategia de rotación, calcula qué contenido publicar a continuación y muestra 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 la tarea de trabajo de almacenamiento compartido. La secuencia de comandos proporciona a la llamada a la worklet una lista de URLs para elegir.
2. En la worklet, si aún no se inicializó el almacenamiento compartido, este 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 secuencial.
3. La worklet lee el modo de rotación del almacenamiento compartido y muestra el índice del siguiente anuncio. En el caso del modo de rotación secuencial, también actualiza el índice de creatividades en el almacenamiento compartido con el valor nuevo que se usará para la próxima llamada.La worklet muestra un objeto FencedFrameConfig o una URN opaca según el valor 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 marco delimitado o un iframe. Consulta el documento Cómo renderizar un documento de anuncio para obtener detalles sobre los tipos de resultados.
5. Cuando un usuario cambia el modo de rotación, la tarea de trabajo de almacenamiento compartido actualiza el valor del modo de rotación de la creatividad almacenado en el almacenamiento compartido.
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 mostrará en función de la estrategia de rotación seleccionada.

Muestras de código

Las siguientes son las muestras de código de 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 "Rotación de creatividades".

2. Elige explorar la demostración como "Editor 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, a los 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. La 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 DevTools 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á 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 almacenamiento compartido para el origen https://shared-storage-demo-content-producer.web.app. Este 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 mediante el almacenamiento de 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 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 mientras estás en el modo secuencial, se mostrará la siguiente creatividad en 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 mientras estés en el modo secuencial.

   
   

6. Si cambias el modo de rotación de las creatividades con los botones de control, se actualizará el valor de la clave creative-rotation-mode en la estrategia correspondiente. El código de la worklet lo usará para elegir la siguiente 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 "Publicador A" y "Publicador B" comparten el mismo almacenamiento y usan la configuración allí para seleccionar la siguiente creatividad que se mostrará y la estrategia de rotación que se usará.

   
   

8. El almacenamiento compartido de "Editor B" está vacío, al igual que el de "Editor 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 discusión y desarrollo activo, 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 tus estadísticas.

Mantente al tanto

• Lista de distribución: Suscríbete a nuestra lista de distribución para recibir las actualizaciones y los anuncios más recientes relacionados con las APIs de Select URL y Shared Storage.

¿Necesitas ayuda?

• Asistencia para desarrolladores: Conéctate con otros desarrolladores y obtén respuestas a tus preguntas en el repositorio de asistencia para desarrolladores de Privacy Sandbox.