Rotacja kreacji reklamy za pomocą interfejsu Select URL API

Użyj interfejsu Select URL API, aby korzystać z pamięci współdzielonej i określać, jaką kreację użytkownik zobaczy w różnych witrynach.

Reklamodawca lub producent treści może chcieć zastosować w kampanii różne strategie rotacji treści i wyświetlać treści lub kreacje naprzemiennie, aby zwiększyć skuteczność. Interfejs Select URL API umożliwia stosowanie różnych strategii rotacji, np. rotacji sekwencyjnej i rotacji z równomiernym rozkładem, w różnych witrynach.

Dzięki rotacji kreacji w interfejsie Select URL API możesz przechowywać dane, takie jak identyfikator kreacji, liczba wyświetleń i interakcje użytkowników, aby określać, które kreacje będą wyświetlane użytkownikom w różnych witrynach.

Więcej informacji o interfejsie API i sposobie działania funkcji wyboru znajdziesz w dokumentacji interfejsu Select URL API.

Wypróbuj rotację kreacji

Aby eksperymentować z rotacją kreacji, upewnij się, że interfejs Select URL API i Shared Storage są włączone:

• W sekcji chrome://settings/content/siteData wybierz Allow sites to save data on your device lub Delete data sites have saved to your device when you close all windows.
• W sekcji chrome://settings/adPrivacy/sites wybierz Site-suggested ads.

Wypróbuj naszą wersję demonstracyjną Shared Storage, aby zobaczyć na żywo przykłady kodu z tego dokumentu.

Prezentacja z przykładowymi fragmentami kodu

W tym przykładzie:

• creative-rotation.js to skrypt innej firmy, który określa treści do rotacji oraz dane, które decydują o tym, jakie treści mają być wybierane i wyświetlane w następnej kolejności, np. wagi w tym przykładzie. Ten skrypt jest wykonywany na stronie wydawcy. Ten skrypt wywołuje worklet pamięci współdzielonej, aby na podstawie dostępnych w niej danych i listy adresów URL do wyboru określić, które treści mają być wyświetlane.

• creative-rotation-worklet.js to element roboczy pamięci współdzielonej podmiotu zewnętrznego, który wyszukuje strategię rotacji, oblicza, które treści opublikować w następnej kolejności, i zwraca te treści.

Jak działa wersja demonstracyjna

1. Gdy użytkownik odwiedza stronę wydawcy, wczytuje ona skrypt creative-rotation.js podmiotu zewnętrznego. Skrypt rotacji kreacji odpowiada za wczytywanie i uruchamianie workletu pamięci współdzielonej. Skrypt przekazuje do wywołania workletu listę adresów URL do wyboru.
2. Jeśli w worklecie pamięć współdzielona nie została jeszcze zainicjowana, jest ona inicjowana za pomocą początkowej strategii rotacji kreacji i indeksu kreacji. Początkową strategią rotacji używaną w tej wersji demonstracyjnej jest strategia sekwencyjna.
3. Worklet odczytuje tryb rotacji z pamięci współdzielonej i zwraca indeks następnej reklamy. W przypadku trybu rotacji sekwencyjnej aktualizuje też indeks kreacji w pamięci współdzielonej o nową wartość, która będzie używana w następnym wywołaniu.Worklet zwraca obiekt FencedFrameConfig lub nieprzezroczysty obiekt URN na podstawie wartości resolveToConfig użytej podczas wywoływania funkcji selectURL.
4. Skrypt rotacji kreacji wyświetla wybraną reklamę w ramce ograniczonej lub w elemencie iframe. Szczegółowe informacje o typach zwracanych danych znajdziesz w dokumencie dotyczącym renderowania reklamy.
5. Gdy użytkownik zmieni tryb rotacji, element roboczy Shared Storage zaktualizuje wartość trybu rotacji kreacji przechowywaną w pamięci współdzielonej.
6. Podczas ponownego wczytywania strony wydawcy powtarzane są kroki 1–4, co umożliwia wybór kolejnej reklamy do wyświetlenia na podstawie wybranej strategii rotacji.

Przykładowe fragmenty kodu

Poniżej znajdziesz przykłady kodu dla plików creative-rotation.js i 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);

Instrukcja ze zrzutami ekranu

1. Aby uzyskać dostęp do rotacji kreacji za pomocą interfejsu Select URL API i pamięci współdzielonej, otwórz stronę https://shared-storage-demo.web.app/. Wybierz wersję demonstracyjną „Rotacja kreacji”.

2. Wybierz opcję eksplorowania wersji demonstracyjnej jako „Wydawca A”. Przekierujemy Cię na stronę https://shared-storage-demo-publisher-a.web.app/creative-rotation. Strona wczytuje ponumerowane treści na podstawie danych o rotacji kreacji zapisanych w Shared Storage, do których dostęp uzyskuje się za pomocą interfejsu Select URL API. Tryby demonstracyjne rotacji kreacji to sekwencyjna, równomierna i ważona. Worklet wykonuje logikę, aby wybrać treści, które mają się pojawić w ramce iframe. Na poniższym obrazie widać stronę wydawcy.

   
   

3. Aby sprawdzić, co jest przechowywane w Shared Storage, w narzędziach deweloperskich w Chrome wybierz kolejno Application –> Shared Storage (Aplikacja –> Shared Storage). W przypadku pamięci współdzielonej tworzone są 2 wpisy. Pusty obszar pamięci jest dostępny dla pochodzenia https://shared-storage-demo-publisher-a.web.app. Będzie on zawierać miejsce na dane specyficzne dla danego pochodzenia i w naszym przypadku pozostanie pusty, ponieważ wydawca nie musi zapisywać danych w pamięci współdzielonej. Pamiętaj, że podobny obszar pamięci zostanie utworzony dla Wydawcy B, gdy w późniejszym czasie odwiedzisz tę stronę w celu przeprowadzenia demonstracji.

   
   

4. Zostanie utworzony kolejny wpis Shared Storage dla pochodzenia https://shared-storage-demo-content-producer.web.app. Jest to pamięć elementu iframe firmy zewnętrznej umieszczonego na stronie wydawcy. Będzie on służyć do udostępniania danych między 2 wydawcami, aby koordynować wybór kreacji. Ten wspólny obszar pamięci będzie służyć do zapisywania informacji o wyświetlonym kreacji i strategii rotacji przez zapisywanie 2 par klucz-wartość. Pierwszy klucz użyty w wersji demonstracyjnej to creative-rotation-index, którego wartością jest bieżący indeks kreacji w trybie sekwencyjnym. Drugi klucz to creative-rotation-mode, który określa używaną strategię rotacji.

   
   

5. Odświeżenie strony w trybie sekwencyjnym spowoduje wyświetlenie następnej kreacji w sekwencji 1, 2, 3, 1 itd. Wartość klucza creative-rotation-index będzie się zmieniać w zależności od indeksu wyświetlanej kreacji w trybie sekwencyjnym.

   
   

6. Zmiana trybu rotacji reklam za pomocą przycisków sterujących spowoduje zaktualizowanie wartości klucza creative-rotation-mode na odpowiednią strategię. Będzie on używany przez kod workletu do wybierania następnej kreacji, która ma się wyświetlić w elemencie iframe. Pamiętaj, że wartość zapisana w przypadku indeksu rotacji kreacji nie zmienia się w przypadku trybów rotacji innych niż sekwencyjny.

   
   

7. Otwórz stronę „Wydawca B” pod adresem https://shared-storage-demo-publisher-b.web.app/creative-rotation. W trybie sekwencyjnym wyświetlana kreacja powinna być następną kreacją w sekwencji, która jest wyświetlana po odwiedzeniu adresu URL „Wydawcy A”. Sprawdzając pamięć współdzieloną producenta treści, możesz zauważyć, że wydawcy A i B korzystają z tej samej pamięci i używają ustawień w niej zawartych do wybierania następnej kreacji do wyświetlenia oraz strategii rotacji.

   
   

8. Pamięć współdzielona „Wydawcy B” jest pusta, podobnie jak pamięć współdzielona „Wydawcy A”.

   
   

   Przypadki użycia

   W tej sekcji znajdziesz wszystkie dostępne przypadki użycia interfejsu Select URL API. Będziemy dodawać kolejne przykłady, gdy będziemy otrzymywać opinie i odkrywać nowe przypadki testowe.

   • Rotacja kreacji reklamowych: przechowuj dane, takie jak identyfikator kreacji i interakcje użytkowników, aby określić, które kreacje wyświetlają się użytkownikom w różnych witrynach.
   • Wybieranie kreacji reklamowych według częstotliwości wyświetleń: na podstawie danych o liczbie wyświetleń możesz określić, które kreacje wyświetlają się użytkownikom w różnych witrynach.
   • Przeprowadzanie testów A/B: możesz przypisać użytkownika do grupy eksperymentalnej, a potem zapisać tę grupę w Shared Storage, aby umożliwić dostęp do niej w różnych witrynach.
   • Dostosowywanie interfejsu dla znanych klientów: udostępniaj treści i wezwania do działania na podstawie stanu rejestracji lub innych stanów użytkownika.

Angażowanie się i przesyłanie opinii

Pamiętaj, że propozycja interfejsu Select URL API jest obecnie przedmiotem dyskusji i prac rozwojowych, a jej treść może ulec zmianie.

Chętnie poznamy Twoją opinię o interfejsie Select URL API.

• Oferta: sprawdź szczegółową ofertę.
• Dyskusja: dołącz do bieżącej dyskusji, aby zadawać pytania i dzielić się spostrzeżeniami.