Memutar materi iklan dengan Select URL API

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Gunakan Select URL API untuk memanfaatkan Shared Storage guna menentukan materi iklan yang dilihat pengguna di seluruh situs.

Pengiklan atau produsen konten mungkin ingin menerapkan strategi rotasi konten yang berbeda ke kampanye, dan memutar konten atau materi iklan untuk meningkatkan efektivitas. Select URL API dapat digunakan untuk menjalankan berbagai strategi rotasi, seperti rotasi berurutan dan rotasi yang didistribusikan secara merata, di berbagai situs.

Dengan rotasi materi iklan Select URL API, Anda dapat menyimpan data, seperti ID materi iklan, jumlah penayangan, dan interaksi pengguna untuk menentukan materi iklan yang dilihat pengguna di berbagai situs.

Untuk informasi selengkapnya tentang API yang mendasarinya dan cara kerja pemilihan, pelajari dokumentasi Select URL API.

Mencoba rotasi materi iklan

Untuk bereksperimen dengan rotasi materi iklan, pastikan Select URL API dan Shared Storage diaktifkan:

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

Coba demo langsung Penyimpanan Bersama kami untuk melihat versi langsung contoh kode dalam dokumen ini.

Demo dengan contoh kode

Dalam contoh ini:

• creative-rotation.js adalah skrip pihak ketiga yang menentukan konten yang akan dirotasi, beserta data apa pun yang menentukan konten berikutnya yang akan dipilih dan ditampilkan, seperti bobot dalam contoh ini. Halaman penayang menjalankan skrip ini. Skrip ini memanggil worklet penyimpanan bersama untuk menentukan konten yang akan ditampilkan berdasarkan data yang tersedia di penyimpanan dan daftar URL yang akan dipilih.

• creative-rotation-worklet.js adalah worklet penyimpanan bersama pihak ketiga yang mencari strategi rotasi, menghitung konten yang akan dipublikasikan berikutnya, dan menampilkan bagian konten tersebut.

Cara kerja demo

1. Saat pengguna mengunjungi halaman penayang, halaman akan memuat skrip creative-rotation.js pihak ketiga. Skrip rotasi materi iklan bertanggung jawab untuk memuat dan menjalankan worklet penyimpanan bersama. Skrip menyediakan panggilan worklet dengan daftar URL yang dapat dipilih.
2. Dalam worklet, jika penyimpanan bersama belum diinisialisasi, penyimpanan akan diinisialisasi dengan strategi rotasi materi iklan awal dan indeks materi iklan. Strategi rotasi awal yang digunakan dalam demo ini adalah strategi berurutan.
3. Worklet membaca mode rotasi dari penyimpanan bersama dan menampilkan indeks iklan berikutnya. Dalam kasus mode rotasi berurutan, mode ini juga memperbarui indeks materi iklan di penyimpanan bersama dengan nilai baru yang akan digunakan untuk panggilan berikutnya.Worklet menampilkan objek FencedFrameConfig atau URN buram berdasarkan nilai resolveToConfig yang digunakan saat memanggil selectURL.
4. Skrip rotasi materi iklan menampilkan iklan yang dipilih dalam Bingkai Pagar atau iframe. Lihat merender dokumen iklan untuk mengetahui detail tentang jenis nilai yang ditampilkan.
5. Saat pengguna mengubah mode rotasi, worklet penyimpanan bersama akan memperbarui nilai mode rotasi materi iklan yang disimpan di penyimpanan bersama.
6. Saat memuat ulang halaman penayang, langkah 1-4 diulang sehingga memungkinkan pemilihan iklan berikutnya untuk dilihat berdasarkan strategi rotasi yang dipilih

Contoh kode

Berikut adalah contoh kode untuk creative-rotation.js dan 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);

Panduan dengan screenshot

1. Untuk mengakses Rotasi Materi Iklan menggunakan Select URL API dan Shared Storage, buka https://shared-storage-demo.web.app/. Pilih demo 'Rotasi Materi Iklan'.

2. Pilih untuk menjelajahi demo sebagai 'Penayang A'. Anda akan dialihkan ke https://shared-storage-demo-publisher-a.web.app/creative-rotation. Halaman memuat konten bernomor berdasarkan data rotasi materi iklan yang disimpan di Shared Storage, yang diakses melalui Select URL API. Mode demo untuk rotasi materi iklan adalah berurutan, distribusi merata, dan distribusi berbobot. Worklet menjalankan logika untuk memilih konten yang muncul di iframe. Gambar berikut menampilkan halaman penayang.

   
   

3. Untuk melihat apa yang disimpan di Shared Storage, buka Aplikasi -> Shared Storage di Chrome DevTools. Dua entri dibuat untuk penyimpanan bersama. Penyimpanan kosong tersedia untuk origin https://shared-storage-demo-publisher-a.web.app. Ini akan berisi penyimpanan khusus untuk origin tersebut dan akan tetap kosong untuk demo kita karena penayang tidak perlu menulis ke penyimpanan bersama. Perhatikan bahwa penyimpanan serupa akan dibuat untuk Penayang B saat Anda mengunjungi halaman tersebut di lain waktu untuk demo.

   
   

4. Entri Shared Storage lain akan dibuat untuk origin https://shared-storage-demo-content-producer.web.app. Ini adalah penyimpanan iframe pihak ketiga yang disematkan di halaman penayang. Penyimpanan ini akan digunakan untuk berbagi data antara dua penayang yang tersedia untuk mengoordinasikan pemilihan materi iklan. Penyimpanan bersama ini akan digunakan untuk menyimpan informasi tentang materi iklan yang ditampilkan dan strategi rotasi dengan menyimpan dua pasangan nilai kunci. Kunci pertama yang digunakan dalam demo adalah creative-rotation-index yang nilainya adalah indeks materi iklan saat ini dalam mode berurutan. Kunci kedua adalah creative-rotation-mode yang menentukan strategi rotasi yang digunakan.

   
   

5. Memuat ulang halaman saat dalam mode berurutan akan menampilkan materi iklan berikutnya dalam urutan 1, 2, 3, 1, …, Nilai untuk kunci creative-rotation-index akan berubah sesuai dengan indeks materi iklan yang ditampilkan saat dalam mode berurutan.

   
   

6. Mengubah mode rotasi materi iklan menggunakan tombol kontrol akan memperbarui nilai untuk kunci creative-rotation-mode ke strategi yang sesuai. Kode ini akan digunakan oleh kode worklet untuk memilih materi iklan berikutnya yang akan ditampilkan di iframe. Perhatikan bahwa nilai yang disimpan untuk creative-rotation-index tidak berubah untuk mode rotasi selain berurutan.

   
   

7. Buka halaman untuk "Penayang B" di https://shared-storage-demo-publisher-b.web.app/creative-rotation. Dalam mode berurutan, materi iklan yang ditampilkan harus berupa materi iklan berikutnya dalam urutan yang ditampilkan saat membuka URL untuk "Penayang A". Dengan memeriksa Penyimpanan Bersama untuk produsen konten, Anda dapat menemukan bahwa "Penayang A" dan "Penayang B" menggunakan penyimpanan yang sama dan menggunakan setelan di sana untuk memilih materi iklan berikutnya yang akan ditampilkan dan strategi rotasi yang akan digunakan.

   
   

8. Penyimpanan Bersama untuk "Penerbit B" kosong, mirip dengan Penyimpanan Bersama "Penerbit A".

   
   

   Kasus penggunaan

   Semua kasus penggunaan yang tersedia untuk Select URL API dapat ditemukan di bagian ini. Kami akan terus menambahkan contoh saat menerima masukan dan menemukan kasus pengujian baru.

   • Memutar materi iklan: Menyimpan data, seperti ID materi iklan dan interaksi pengguna, untuk menentukan materi iklan yang dilihat pengguna di berbagai situs.
   • Memilih materi iklan berdasarkan frekuensi: Gunakan data jumlah penayangan untuk menentukan materi iklan yang dilihat pengguna di berbagai situs.
   • Menjalankan pengujian A/B: Anda dapat menetapkan pengguna ke grup eksperimen, lalu menyimpan grup tersebut di Shared Storage untuk diakses lintas situs.
   • Menyesuaikan pengalaman untuk pelanggan yang diketahui: Membagikan konten kustom dan pesan ajakan (CTA) berdasarkan status pendaftaran pengguna atau status pengguna lainnya.

Berinteraksi dan memberikan masukan

Perhatikan bahwa proposal Select URL API sedang dalam diskusi dan pengembangan aktif serta dapat berubah sewaktu-waktu.

Kami ingin mengetahui pendapat Anda tentang Select URL API.

• Proposal: Tinjau proposal mendetail.
• Diskusi: Bergabunglah dengan diskusi yang sedang berlangsung untuk mengajukan pertanyaan dan membagikan insight Anda.

Mendapatkan Info Terbaru

• Daftar Email: Berlangganan ke daftar email kami untuk mendapatkan info terbaru dan pengumuman terkait API URL Pilih dan Shared Storage.

Perlu Bantuan?

• Dukungan Developer: Terhubung dengan developer lain dan dapatkan jawaban atas pertanyaan Anda di repositori Dukungan Developer Privacy Sandbox.