Select URL API ile reklam öğelerini dönüşümlü yayınlama

Kullanıcının siteler arasında hangi reklam öğesini göreceğini belirlemek için Shared Storage'dan yararlanmak üzere Select URL API'yi kullanın.

Bir reklamveren veya içerik üretici, bir kampanyaya farklı içerik rotasyonu stratejileri uygulamak ve etkinliği artırmak için içerikleri veya reklam öğelerini döndürmek isteyebilir. Select URL API, farklı sitelerde sıralı rotasyon ve eşit dağıtılmış rotasyon gibi farklı rotasyon stratejileri çalıştırmak için kullanılabilir.

URL API reklam öğesi rotasyonu seçeneğiyle, kullanıcıların farklı sitelerde hangi reklam öğesini göreceğini belirlemek için reklam öğesi kimliği, görüntüleme sayısı ve kullanıcı etkileşimi gibi verileri depolayabilirsiniz.

Temel API ve seçim süreci hakkında daha fazla bilgi için Select URL API belgelerini inceleyin.

Reklam öğesi rotasyonunu deneme

Reklam öğesi rotasyonuyla deneme yapmak için Select URL API'sinin ve Shared Storage'ın etkinleştirildiğinden emin olun:

• chrome://settings/content/siteData bölümünde Allow sites to save data on your device veya Delete data sites have saved to your device when you close all windows'ı seçin.
• chrome://settings/adPrivacy/sites bölümünde Site-suggested ads seçeneğini belirleyin.

Bu belgedeki kod örneklerinin canlı sürümü için Shared Storage canlı demomuzu deneyin.

Kod örnekleriyle demo

Bu örnekte:

• creative-rotation.js, döndürülecek içeriği tanımlayan üçüncü taraf komut dosyasıdır. Ayrıca, bir sonraki seçilecek ve görüntülenecek içeriği belirleyen tüm verileri (ör. bu örnekteki ağırlıklar) içerir. Bu komut dosyası yayıncı sayfasında yürütülür. Bu komut dosyası, depolamada bulunan verilere ve seçilecek URL listesine göre hangi içeriğin görüntüleneceğini belirlemek için Shared Storage worklet'ini çağırır.

• creative-rotation-worklet.js, rotasyon stratejisini arayan, bir sonraki yayınlanacak içeriği hesaplayan ve bu içeriği döndüren üçüncü tarafın paylaşılan depolama alanı işlevidir.

Demonun işleyiş şekli

1. Kullanıcı yayıncı sayfasını ziyaret ettiğinde sayfaya üçüncü tarafın creative-rotation.js komut dosyası yüklenir. Reklam öğesi rotasyonu komut dosyası, paylaşılan depolama işini yüklemekten ve çalıştırmaktan sorumludur. Komut dosyası, işlev çağrısına aralarından seçim yapılabilecek bir URL listesi sağlar.
2. Çalışma biriminde, Shared Storage henüz başlatılmamışsa depolama alanı ilk reklam öğesi rotasyon stratejisi ve reklam öğesi diziniyle başlatılır. Bu demoda kullanılan ilk dönüşüm stratejisi sıralı stratejidir.
3. İş akışı, rotasyon modunu ortak depolama alanından okur ve sonraki reklamın dizinini döndürür. Sıralı rotasyon modunda, paylaşılan depolamadaki reklam öğesi dizinini de bir sonraki çağrıda kullanılacak yeni değerle günceller.İşletim birimi, selectURL çağrılırken kullanılan resolveToConfig değerine bağlı olarak FencedFrameConfig veya opak URN nesnesi döndürür.
4. Reklam öğesi rotasyonu komut dosyası, seçilen reklamı Fenced Frame veya iframe'de gösterir. Döndürülen türlerle ilgili ayrıntılar için reklam oluşturma dokümanına bakın.
5. Kullanıcı döndürme modunu değiştirdiğinde, paylaşılan depolama işleti, paylaşılan depolamada depolanan reklam öğesi döndürme modu değerini günceller.
6. Yayıncı sayfası yeniden yüklendiğinde 1-4 arasındaki adımlar tekrarlanır ve seçilen rotasyon stratejisine göre görüntülenecek bir sonraki reklamın seçilmesine olanak tanınır.

Kod örnekleri

Aşağıda creative-rotation.js ve creative-rotation-worklet.js için kod örnekleri verilmiştir.

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);

Ekran görüntüleriyle adım adım açıklama

1. Select URL API ve Shared Storage kullanarak reklam öğesi rotasyonuna erişmek için https://shared-storage-demo.web.app/ adresine gidin. "Reklam öğesi rotasyonu" demosunu seçin.

2. Demoyu "A Yayıncısı" olarak keşfetmeyi seçin. https://shared-storage-demo-publisher-a.web.app/creative-rotation adresine yönlendirilirsiniz. Sayfa, Select URL API aracılığıyla erişilen Shared Storage'da kaydedilen reklam öğesi rotasyonu verilerine göre numaralandırılmış içerik yükler. Reklam öğesi rotasyonu için sıralı, eşit dağıtım ve ağırlıklı dağıtım olmak üzere üç demo modu vardır. İşlet, iFrame'de gösterilen içeriği seçme mantığını yürütür. Aşağıdaki resimde yayıncı sayfası gösterilmektedir.

   
   

3. Shared Storage'da depolananları görüntülemek için Chrome DevTools'da Application -> Shared Storage'a gidin. Paylaşılan depolama alanı için iki giriş oluşturulur. https://shared-storage-demo-publisher-a.web.app kaynağı için boş bir depolama alanı kullanılabilir. Bu, söz konusu kaynakla ilgili depolama alanını içerir ve yayıncının paylaşılan depolama alanına yazması gerekmediğinden demomuzda boş kalır. Bu sayfayı daha sonra demo için ziyaret ettiğinizde Yayıncı B için benzer bir depolama alanı oluşturulacağını unutmayın.

   
   

4. https://shared-storage-demo-content-producer.web.app kaynağı için başka bir Shared Storage girişi oluşturulur. Bu, yayıncı sayfasına yerleştirilmiş üçüncü taraf iframe'in depolama alanıdır. Bu depolama alanı, reklam öğesi seçimini koordine etmek için iki yayıncı arasında veri paylaşımında kullanılır. Bu paylaşılan depolama alanı, iki anahtar/değer çifti kaydedilerek gösterilen reklam öğesi ve rotasyon stratejisi hakkındaki bilgileri kaydetmek için kullanılır. Demoda kullanılan ilk anahtar creative-rotation-index olup değeri, sıralı moddaki mevcut reklam öğesi dizinidir. İkinci anahtar, kullanılan rotasyon stratejisini belirleyen creative-rotation-mode'dır.

   
   

5. Sıralı moddayken sayfayı yenilemek, sıradaki bir sonraki reklam öğesinin (1, 2, 3, 1, …) gösterilmesine neden olur. Sıralı moddayken gösterilen reklam öğesinin dizinine göre key-creative-rotation-index anahtarının değeri değişir.

   
   

6. Kontrol düğmelerini kullanarak reklam öğesi rotasyon modunu değiştirdiğinizde, key-creative-rotation-mode değeri ilgili stratejiye göre güncellenir. Bu değer, iFrame'de gösterilecek bir sonraki reklam öğesini seçmek için işlev kodu tarafından kullanılır. Reklam öğesi rotasyon dizini için kaydedilen değerin, sıralı rotasyon modu dışındaki rotasyon modlarında değişmediğini unutmayın.

   
   

7. https://shared-storage-demo-publisher-b.web.app/creative-rotation adresinde "Yayıncı B"nin sayfasına gidin. Sıralı modda, "Yayıncı A"nın URL'si ziyaret edildiğinde gösterilen reklam öğesi, sıradaki bir sonraki reklam öğesi olmalıdır. İçerik üreticinin paylaşılan depolama alanını incelediğinizde hem "Yayıncı A" hem de "Yayıncı B"nin aynı depolama alanını paylaştığını ve gösterilecek bir sonraki reklam öğesini ve kullanılacak rotasyon stratejisini seçmek için buradaki ayarları kullandığını görebilirsiniz.

   
   

8. "B Yayıncısı"nın Shared Storage'ı, "A Yayıncısı"nın Shared Storage'ı gibi boştur.

   
   

   Kullanım alanları

   Seçili URL API'si için kullanılabilen tüm kullanım alanlarını bu bölümde bulabilirsiniz. Geri bildirim aldıkça ve yeni test örnekleri keşfettikçe örnekler eklemeye devam edeceğiz.

   • Reklam öğelerini döndürme: Kullanıcıların farklı sitelerde gördüğü reklam öğesini belirlemek için reklam öğesi kimliği ve kullanıcı etkileşimi gibi verileri depolayın.
   • Reklam öğelerini sıklıklarına göre seçme: Kullanıcıların farklı sitelerde gördüğü reklam öğelerini belirlemek için görüntüleme sayısı verilerini kullanın.
   • A/B testi çalıştırma: Bir kullanıcıyı deneme grubuna atayabilir ve ardından bu grubu, siteler arası erişilebilmesi için Shared Storage'da saklayabilirsiniz.
   • Tanınmış müşteriler için deneyimi özelleştirme: Kullanıcının kayıt durumuna veya diğer kullanıcı durumlarına göre özel içerikler ve harekete geçirici mesajlar paylaşın.

Etkileşim kurma ve geri bildirim paylaşma

Select URL API teklifinin aktif olarak tartışılıp geliştirildiğini ve bu nedenle değişebileceğini unutmayın.

Select URL API hakkındaki düşüncelerinizi öğrenmek istiyoruz.

• Teklif: Ayrıntılı teklifi inceleyin.
• Tartışma: Soru sormak ve görüşlerinizi paylaşmak için devam eden tartışmaya katılın.