Ruotare le creatività degli annunci con l'API Select URL

Utilizza l'API Select URL per sfruttare Shared Storage e determinare quale creatività viene visualizzata da un utente sui vari siti.

Un inserzionista o un produttore di contenuti potrebbe voler applicare diverse strategie di rotazione dei contenuti a una campagna e ruotare i contenuti o le creatività per aumentare l'efficacia. L'API Select URL può essere utilizzata per eseguire diverse strategie di rotazione, come la rotazione sequenziale e la rotazione distribuita in modo uniforme, su diversi siti.

Con la rotazione delle creatività dell'API Select URL, puoi memorizzare dati come l'ID creatività, i conteggi delle visualizzazioni e l'interazione utente per determinare quale creatività vedono gli utenti su diversi siti.

Per saperne di più sull'API sottostante e sul funzionamento della selezione, consulta la documentazione dell'API Select URL.

Prova la rotazione creatività

Per sperimentare la rotazione delle creatività, assicurati che l'API Select URL e Shared Storage siano abilitati:

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

Prova la nostra demo dal vivo di Shared Storage per una versione live degli esempi di codice in questo documento.

Demo con esempi di codice

In questo esempio:

• creative-rotation.js è lo script di terze parti che definisce i contenuti da ruotare, insieme a tutti i dati che determinano i contenuti successivi da selezionare e visualizzare, come i pesi in questo esempio. La pagina del publisher esegue questo script. Questo script chiama il worklet Shared Storage per determinare quali contenuti visualizzare in base ai dati disponibili nello spazio di archiviazione e all'elenco di URL da cui scegliere.

• creative-rotation-worklet.js è il worklet di archiviazione condivisa di terze parti che cerca la strategia di rotazione, calcola quali contenuti pubblicare successivamente e restituisce il contenuto.

Come funziona la demo

1. Quando un utente visita la pagina dell'editore, la pagina carica lo script creative-rotation.js di terze parti. Lo script di rotazione delle creatività è responsabile del caricamento e dell'esecuzione del worklet di archiviazione condivisa. Lo script fornisce la chiamata del worklet con un elenco di URL tra cui scegliere.
2. Nel worklet, se Shared Storage non è ancora stato inizializzato, viene inizializzato con la strategia di rotazione delle creatività e l'indice delle creatività iniziali. La strategia di rotazione iniziale utilizzata in questa demo è la strategia sequenziale.
3. Il worklet legge la modalità di rotazione dallo spazio di archiviazione condiviso e restituisce l'indice dell'annuncio successivo. Nel caso della modalità di rotazione sequenziale, aggiorna anche l'indice delle creatività nello spazio di archiviazione condiviso con il nuovo valore da utilizzare per la chiamata successiva.Il worklet restituisce un oggetto URN FencedFrameConfig o opaco in base al valore resolveToConfig utilizzato durante la chiamata di selectURL.
4. Lo script di rotazione delle creatività mostra l'annuncio selezionato in un frame recintato o in un iframe. Per informazioni dettagliate sui tipi di ritorno, consulta il documento sul rendering di un annuncio.
5. Quando un utente modifica la modalità di rotazione, il worklet Shared Storage aggiorna il valore della modalità di rotazione delle creatività memorizzato in Shared Storage.
6. Quando viene ricaricata la pagina del publisher, i passaggi da 1 a 4 vengono ripetuti, consentendo la selezione dell'annuncio successivo da visualizzare in base alla strategia di rotazione selezionata.

Esempi di codice

Di seguito sono riportati gli esempi di codice per creative-rotation.js e 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);

Procedura dettagliata con screenshot

1. Per accedere alla rotazione delle creatività utilizzando l'API Select URL e Shared Storage, vai a https://shared-storage-demo.web.app/. Scegli la demo "Rotazione creatività".

2. Scegli di esplorare la demo come "Publisher A". Verrà visualizzata la pagina https://shared-storage-demo-publisher-a.web.app/creative-rotation. La pagina carica i contenuti numerati in base ai dati di rotazione delle creatività salvati in Shared Storage, a cui si accede tramite l'API Select URL. Le modalità demo per la rotazione creatività sono sequenziale, distribuzione uniforme e distribuzione ponderata. Il worklet esegue la logica per selezionare i contenuti visualizzati nell'iframe. L'immagine seguente mostra la pagina del publisher.

   
   

3. Per visualizzare i contenuti archiviati nello spazio di archiviazione condiviso, vai a Applicazione -> Spazio di archiviazione condiviso in Chrome DevTools. Vengono create due voci per lo spazio di archiviazione condiviso. È disponibile uno spazio di archiviazione vuoto per l'origine https://shared-storage-demo-publisher-a.web.app. Conterrà lo spazio di archiviazione specifico per l'origine e rimarrà vuoto per la nostra demo, poiché l'editore non deve scrivere nello spazio di archiviazione condiviso. Tieni presente che verrà creato uno spazio di archiviazione simile per l'editore B quando visiterai la pagina in un secondo momento per la demo.

   
   

4. Verrà creata un'altra voce Shared Storage per l'origine https://shared-storage-demo-content-producer.web.app. Si tratta dell'archiviazione dell'iframe di terze parti incorporato nella pagina dell'editore. Questo spazio di archiviazione verrà utilizzato per condividere i dati tra i due publisher disponibili per coordinare la selezione delle creatività. Questo spazio di archiviazione condiviso verrà utilizzato per salvare le informazioni sulla strategia di rotazione e sulla creatività mostrata salvando due coppie chiave-valore. La prima chiave utilizzata nella demo è creative-rotation-index, il cui valore è l'indice della creatività corrente in modalità sequenziale. La seconda chiave è creative-rotation-mode, che determina la strategia di rotazione utilizzata.

   
   

5. L'aggiornamento della pagina in modalità sequenziale comporta la visualizzazione della creatività successiva nella sequenza 1, 2, 3, 1, ecc. Il valore della chiave creative-rotation-index cambia in base all'indice della creatività visualizzata in modalità sequenziale.

   
   

6. Se modifichi la modalità di rotazione delle creatività utilizzando i pulsanti di controllo, il valore della chiave creative-rotation-mode verrà aggiornato in base alla strategia corrispondente. Verrà utilizzato dal codice del worklet per scegliere la successiva creatività da mostrare nell'iframe. Tieni presente che il valore salvato per creative-rotation-index non cambia per le modalità di rotazione diverse da quella sequenziale.

   
   

7. Vai alla pagina di "Publisher B" all'indirizzo https://shared-storage-demo-publisher-b.web.app/creative-rotation. In modalità sequenziale, la creatività mostrata deve essere la successiva nella sequenza visualizzata quando si visita l'URL di "Publisher A". Se esamini lo spazio di archiviazione condiviso per il produttore di contenuti, puoi notare che sia "Publisher A" che "Publisher B" condividono lo stesso spazio di archiviazione e utilizzano le impostazioni per selezionare la prossima creatività da mostrare e la strategia di rotazione da utilizzare.

   
   

8. Lo spazio di archiviazione condiviso per "Publisher B" è vuoto, come quello di "Publisher A".

   
   

   Casi d'uso

   Tutti i casi d'uso disponibili per l'API Select URL sono disponibili in questa sezione. Continueremo ad aggiungere esempi man mano che riceviamo feedback e scopriamo nuovi casi di test.

   • Ruota le creatività degli annunci: memorizza i dati, ad esempio l'ID creatività e l'interazione degli utenti, per determinare la creatività che gli utenti vedono su siti diversi.
   • Seleziona le creatività degli annunci in base alla frequenza: utilizza i dati sul conteggio delle visualizzazioni per determinare quali creatività vengono visualizzate dagli utenti su siti diversi.
   • Esegui test A/B: puoi assegnare un utente a un gruppo sperimentale, quindi archiviare il gruppo in Shared Storage per accedervi su più siti.
   • Personalizza l'esperienza per i clienti noti: condividi contenuti personalizzati e inviti all'azione in base allo stato di registrazione o ad altri stati dell'utente.

Partecipare e condividere feedback

Tieni presente che la proposta dell'API Select URL è in fase di discussione e sviluppo ed è soggetta a modifiche.

Non vediamo l'ora di conoscere la tua opinione sull'API Select URL.

• Proposta: rivedi la proposta dettagliata.
• Discussione: partecipa alla discussione in corso per porre domande e condividere le tue informazioni.