Alternar criativos de anúncios com a API Select URL

Use a API Select URL para aproveitar o Shared Storage e determinar qual criativo um usuário vê em vários sites.

Um anunciante ou produtor de conteúdo pode querer aplicar diferentes estratégias de rotação de conteúdo a uma campanha e alternar os conteúdos ou criativos para aumentar a eficácia. A API Select URL pode ser usada para executar diferentes estratégias de rotação, como rotação sequencial e rotação distribuída uniformemente, em diferentes sites.

Com a rotação de criativos da API Select URL, é possível armazenar dados, como ID do criativo, contagens de visualizações e interação do usuário, para determinar qual criativo os usuários veem em diferentes sites.

Para mais informações sobre a API subjacente e como a seleção funciona, consulte a documentação da API Select URL.

Teste a rotação de criativos

Para testar a rotação de criativos, verifique se a API Select URL e o Armazenamento compartilhado estão ativados:

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

Teste nossa demonstração ao vivo do armazenamento compartilhado para ver uma versão ativa dos exemplos de código neste documento.

Demonstração com exemplos de código

Neste exemplo:

• creative-rotation.js é o script de terceiros que define o conteúdo a ser alternado, além de todos os dados que determinam o próximo conteúdo a ser selecionado e exibido, como ponderações neste exemplo. A página do editor executa esse script. Esse script chama o worklet de armazenamento compartilhado para determinar qual conteúdo mostrar com base nos dados disponíveis no armazenamento e na lista de URLs para selecionar.

• creative-rotation-worklet.js é o worklet de armazenamento compartilhado do terceiro que pesquisa a estratégia de rotação, calcula qual conteúdo publicar em seguida e retorna esse conteúdo.

Como a demonstração funciona

1. Quando um usuário visita a página do editor, ela carrega o script creative-rotation.js do terceiro. O script de rotação de criativos é responsável por carregar e executar o worklet de armazenamento compartilhado. O script fornece a chamada do worklet com uma lista de URLs para selecionar.
2. No worklet, se o armazenamento compartilhado ainda não tiver sido inicializado, ele será inicializado com a estratégia inicial de rotação de criativos e o índice de criativos. A estratégia de rotação inicial usada nesta demonstração é a sequencial.
3. O worklet lê o modo de rotação do armazenamento compartilhado e retorna o índice do próximo anúncio. No caso do modo de rotação sequencial, ele também atualiza o índice do criativo no armazenamento compartilhado com o novo valor a ser usado na próxima chamada.O worklet retorna um objeto FencedFrameConfig ou URN opaco com base no valor resolveToConfig usado ao chamar selectURL.
4. O script de rotação de criativos mostra o anúncio selecionado em um frame isolado ou um iframe. Consulte o documento sobre renderização de um anúncio para detalhes sobre tipos de retorno.
5. Quando um usuário muda o modo de rotação, o worklet de armazenamento compartilhado atualiza o valor do modo de rotação do criativo armazenado no armazenamento compartilhado.
6. Ao recarregar a página do publisher, as etapas de 1 a 4 são repetidas, permitindo a seleção do próximo anúncio a ser exibido com base na estratégia de rotação selecionada.

Amostras de código

Confira abaixo os exemplos de código para 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);

Tutorial com capturas de tela

1. Para acessar a rotação de criativos usando a API Select URL e o armazenamento compartilhado, acesse https://shared-storage-demo.web.app/. Escolha a demonstração "Rotação de criativos".

2. Escolha explorar a demonstração como "Publisher A". Você vai ser redirecionado para https://shared-storage-demo-publisher-a.web.app/creative-rotation. A página carrega conteúdo numerado com base nos dados de rotação de criativos salvos no Armazenamento compartilhado, acessados pela API Select URL. Os modos de demonstração para rotação de criativos são sequencial, distribuição uniforme e distribuição ponderada. O worklet executa a lógica para selecionar o conteúdo que aparece no iframe. A imagem a seguir mostra a página do editor.

   
   

3. Para ver o que está armazenado no Shared Storage, acesse Application -> Shared Storage no Chrome DevTools. Duas entradas são criadas para o armazenamento compartilhado. Um armazenamento vazio está disponível para a origem https://shared-storage-demo-publisher-a.web.app. Ele vai conter o armazenamento específico dessa origem e vai permanecer vazio na nossa demonstração, já que o editor não precisa gravar no armazenamento compartilhado. Uma área de armazenamento semelhante será criada para o Publisher B quando você acessar essa página mais tarde para a demonstração.

   
   

4. Outra entrada do armazenamento compartilhado será criada para a origem https://shared-storage-demo-content-producer.web.app. É o armazenamento do iframe de terceiros incorporado na página do editor. Esse armazenamento será usado para compartilhar dados entre os dois publishers disponíveis e coordenar a seleção de criativos. Esse armazenamento compartilhado será usado para salvar informações sobre o criativo mostrado e a estratégia de rotação, salvando dois pares de chave-valor. A primeira chave usada na demonstração é creative-rotation-index, cujo valor é o índice do criativo atual no modo sequencial. A segunda chave é creative-rotation-mode, que determina a estratégia de rotação usada.

   
   

5. Atualizar a página no modo sequencial vai mostrar o próximo criativo na sequência 1, 2, 3, 1, etc. O valor da chave "creative-rotation-index" muda de acordo com o índice do criativo mostrado no modo sequencial.

   
   

6. Mudar o modo de rotação de criativos usando os botões de controle atualiza o valor da chave creative-rotation-mode na estratégia correspondente. Isso será usado pelo código do worklet para escolher o próximo criativo a ser mostrado no iframe. O valor salvo para "creative-rotation-index" não muda para modos de rotação diferentes do sequencial.

   
   

7. Acesse a página do "Editor B" em https://shared-storage-demo-publisher-b.web.app/creative-rotation. No modo sequencial, o criativo mostrado deve ser o próximo na sequência exibida ao visitar o URL do "Publisher A". Ao inspecionar o armazenamento compartilhado do produtor de conteúdo, você descobre que o "Publisher A" e o "Publisher B" compartilham o mesmo armazenamento e usam as configurações dele para selecionar o próximo criativo a ser mostrado e a estratégia de rotação a ser usada.

   
   

8. O armazenamento compartilhado do "Publisher B" está vazio, assim como o do "Publisher A".

   
   

   Casos de uso

   Todos os casos de uso disponíveis para a API Select URL podem ser encontrados nesta seção. Vamos continuar adicionando exemplos à medida que recebermos feedback e descobrirmos novos casos de teste.

   • Rotecionar criativos de anúncios: armazene dados, como o ID do criativo e a interação do usuário, para determinar quais criativos os usuários veem em diferentes sites.
   • Selecionar criativos de anúncio por frequência: use os dados de contagem de visualizações para determinar quais criativos os usuários veem em diferentes sites.
   • Executar testes A/B: é possível atribuir um usuário a um grupo de experimentos e armazenar esse grupo na Shared Storage para acesso em vários sites.
   • Personalizar a experiência para clientes conhecidos: compartilhe conteúdo e calls-to-action personalizados com base no status de registro ou em outros estados do usuário.

Engajamento e como compartilhar feedback

A proposta da API Select URL está em discussão e desenvolvimento ativos e está sujeita a mudanças.

Queremos saber o que você acha da API Select URL.

• Proposta: revise a proposta detalhada.
• Discussão: participe da discussão em andamento para fazer perguntas e compartilhar suas ideias.