Поворот рекламных объявлений с помощью API Select URL

Используйте API выбора URL-адреса, чтобы воспользоваться преимуществами общего хранилища и определить, какие рекламные материалы будут отображаться пользователю на разных сайтах.

Рекламодатель или производитель контента может захотеть применить различные стратегии ротации контента в рамках кампании и менять контент или креативы для повышения эффективности. API Select URL можно использовать для запуска различных стратегий ротации, таких как последовательная ротация и равномерно распределенная ротация, на разных сайтах.

С помощью Select URL API для ротации креативов вы можете хранить такие данные, как идентификатор креатива, количество просмотров и взаимодействие с пользователями, чтобы определять, какие креативы пользователи видят на разных сайтах.

Для получения более подробной информации об используемом API и принципах работы выбора, ознакомьтесь с документацией по API выбора URL-адреса .

Попробуйте креативную ротацию.

Для экспериментов с креативной ротацией убедитесь, что включены функции Select URL API и Shared Storage:

• В chrome://settings/content/siteData выберите Allow sites to save data on your device или Delete data sites have saved to your device when you close all windows .
• В chrome://settings/adPrivacy/sites выберите Site-suggested ads .

Попробуйте нашу демонстрационную версию Shared Storage , чтобы ознакомиться с работающими примерами кода из этого документа.

Демонстрация с примерами кода.

В этом примере:

• creative-rotation.js — это сторонний скрипт, определяющий контент для ротации, а также любые данные, определяющие следующий контент для выбора и отображения, например, веса в этом примере. Страница издателя выполняет этот скрипт. Этот скрипт вызывает рабочий процесс общего хранилища, чтобы определить, какой контент отображать на основе доступных данных в хранилище и списка URL-адресов для выбора.

• creative-rotation-worklet.js — это сторонний модуль для общего хранилища, который определяет стратегию ротации, вычисляет, какой контент следует опубликовать следующим, и возвращает именно этот контент.

Как работает демоверсия

1. Когда пользователь заходит на страницу издателя, страница загружает сторонний скрипт creative-rotation.js . Скрипт creative-rotation отвечает за загрузку и запуск рабочего модуля общего хранилища. Скрипт передает вызову рабочего модуля список URL-адресов для выбора.
2. В рабочем модуле, если общее хранилище еще не инициализировано, оно инициализируется с использованием начальной стратегии ротации креативов и индекса креативов. В этом примере используется последовательная стратегия ротации.
3. Этот рабочий модуль считывает режим ротации из общего хранилища и возвращает индекс следующего объявления. В случае последовательной ротации он также обновляет индекс креатива в общем хранилище новым значением, которое будет использоваться для следующего вызова. Рабочий модуль возвращает объект FencedFrameConfig или непрозрачный URN в зависимости от значения resolveToConfig использованного при вызове selectURL .
4. Скрипт creative-rotation отображает выбранное объявление в рамке Fenced Frame или iframe. Подробную информацию о типах возврата см. в документе render an ad .
5. Когда пользователь изменяет режим поворота экрана, рабочий модуль общего хранилища обновляет значение режима поворота творческого режима, хранящееся в общем хранилище.
6. При перезагрузке страницы издателя шаги 1-4 повторяются, что позволяет выбрать следующее объявление для просмотра в соответствии с выбранной стратегией ротации.

Примеры кода

Ниже приведены примеры кода для файлов creative-rotation.js и 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);

Пошаговое руководство со скриншотами.

1. Чтобы получить доступ к функции ротации креативов с помощью API выбора URL и общего хранилища, перейдите по ссылке https://shared-storage-demo.web.app/ . Выберите демо-версию «Ротация креативов».

2. Выберите демонстрацию в качестве «Издателя A». Вы будете перенаправлены на страницу https://shared-storage-demo-publisher-a.web.app/creative-rotation . На странице загрузится пронумерованный контент на основе данных ротации креативов, сохраненных в общем хранилище (Shared Storage) и доступных через API выбора URL. Демонстрационные режимы ротации креативов: последовательная, равномерное распределение и взвешенное распределение. Рабочий модуль выполняет логику выбора контента, который отображается в iframe. На следующем изображении показана страница издателя.

   
   

3. Чтобы просмотреть содержимое общего хранилища, перейдите в меню «Приложения» -> «Общее хранилище» в инструментах разработчика Chrome. Для общего хранилища создаются две записи. Для источника https://shared-storage-demo-publisher-a.web.app доступно пустое хранилище. Оно будет содержать данные, специфичные для этого источника, и останется пустым для нашей демонстрации, поскольку издателю не нужно записывать данные в общее хранилище. Обратите внимание, что аналогичное хранилище будет создано для издателя B, когда вы позже посетите эту страницу для демонстрации.

   
   

4. Для источника https://shared-storage-demo-content-producer.web.app будет создана еще одна запись в общем хранилище. Это хранилище для стороннего iframe, встроенного на страницу издателя. Это хранилище будет использоваться для обмена данными между двумя доступными издателями для координации выбора креативов. В этом общем хранилище будет сохраняться информация о отображаемых креативах и стратегии ротации путем сохранения двух пар ключ-значение. Первый ключ, используемый в демонстрации, — creative-rotation-index значение которого — текущий индекс креатива в последовательном режиме. Второй ключ — creative-rotation-mode , который определяет используемую стратегию ротации.

   
   

5. Обновление страницы в последовательном режиме приведет к отображению следующего креатива в последовательности 1, 2, 3, 1, …. Значение ключа creative-rotation-index будет изменяться в соответствии с индексом отображаемого креатива в последовательном режиме.

   
   

6. Изменение режима ротации креативов с помощью кнопок управления обновит значение параметра creative-rotation-mode в соответствующую стратегию. Это значение будет использоваться кодом рабочего блока для выбора следующего креатива, который будет показан в iframe. Обратите внимание, что значение, сохраненное для creative-rotation-index, не изменяется для режимов ротации, отличных от последовательной.

   
   

7. Перейдите на страницу "Издателя B" по адресу https://shared-storage-demo-publisher-b.web.app/creative-rotation . В последовательном режиме отображаемый креатив должен быть следующим креативом в последовательности, показанной при переходе по URL-адресу "Издателя A". Проверив общее хранилище для производителя контента, вы обнаружите, что "Издатель A" и "Издатель B" используют одно и то же хранилище и применяют его настройки для выбора следующего креатива для показа и стратегии ротации.

   
   

8. Общее хранилище для "Издателя B" пусто, как и общее хранилище для "Издателя A".

   
   

   Варианты использования

   Все доступные варианты использования Select URL API можно найти в этом разделе. Мы продолжим добавлять примеры по мере получения отзывов и обнаружения новых тестовых случаев.

   • Чередуйте рекламные объявления : сохраняйте данные, такие как идентификатор креатива и взаимодействие с пользователем, чтобы определить, какие креативы пользователи видят на разных сайтах.
   • Выберите рекламные объявления по частоте : используйте данные о количестве просмотров, чтобы определить, какие креативы видят пользователи на разных сайтах.
   • Запустите A/B-тестирование : вы можете назначить пользователя в экспериментальную группу, а затем сохранить эту группу в общем хранилище для обеспечения кросс-сайтового доступа.
   • Персонализируйте опыт для известных клиентов : делитесь индивидуальным контентом и призывами к действию на основе статуса регистрации пользователя или других состояний пользователя.

Engage and share feedback

Note that the Select URL API proposal is under active discussion and development and subject to change.

We're eager to hear your thoughts on the Select URL API.

• Proposal: Review the detailed proposal.
• Discussion: Join the ongoing discussion to ask questions and share your insights.