تدوير تصميمات الإعلانات باستخدام Select URL API

استخدِم واجهة برمجة التطبيقات Select URL API للاستفادة من Shared Storage لتحديد تصميم الإعلان الذي يراه المستخدِم على مستوى المواقع الإلكترونية.

قد يريد المعلِن أو منتج المحتوى تطبيق استراتيجيات مختلفة لتبديل المحتوى على إحدى الحملات، وتبديل المحتوى أو تصميمات الإعلانات لزيادة الفعالية. يمكن استخدام Select URL API لتنفيذ استراتيجيات مختلفة للتناوب، مثل التناوب التسلسلي والتناوب الموزّع بالتساوي، على مستوى مواقع إلكترونية مختلفة.

باستخدام ميزة Select URL API لعرض الإعلانات، يمكنك تخزين البيانات، مثل رقم تعريف تصميم الإعلان وعدد المشاهدات وتفاعل المستخدِم لتحديد تصميم الإعلان الذي يراه المستخدِمون على المواقع الإلكترونية المختلفة.

لمزيد من المعلومات عن واجهة برمجة التطبيقات الأساسية وطريقة عمل الاختيار، يمكنك الاطّلاع على مستندات Select URL API.

تجربة العرض بالتناوب لتصميم الإعلان

لتجربة ميزة عرض الإعلانات بالتناوب، تأكَّد من تفعيل 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 API للحصول على إصدار مباشر من عيّنات الرموز البرمجية الواردة في هذا المستند.

عرض توضيحي يتضمّن عيّنات من الرموز البرمجية

في هذا المثال:

• creative-rotation.js هو النص البرمجي التابع لجهة خارجية الذي يحدّد المحتوى الذي سيتم عرضه بالتناوب، بالإضافة إلى أي بيانات تحدّد المحتوى التالي الذي سيتم اختياره وعرضه، مثل الأوزان في هذا المثال. تنفِّذ صفحة الناشر هذا النص البرمجي. يستدعي هذا النص البرمجي وحدة عمل مساحة التخزين المشتركة لتحديد المحتوى الذي سيتم عرضه استنادًا إلى البيانات المتاحة في مساحة التخزين وقائمة عناوين URL التي يمكن الاختيار من بينها.

• creative-rotation-worklet.js هي وحدة عمل التخزين المشترَك التابعة لجهة خارجية والتي تبحث عن استراتيجية التناوب، وتحسب المحتوى الذي سيتم نشره بعد ذلك، وتُرجع هذا المحتوى.

آلية عمل العرض التجريبي

1. عندما يزور مستخدم صفحة الناشر، تحمّل الصفحة نص creative-rotation.js التابع لجهة خارجية. يتحمّل نصّ برمجي لتدوير المواد الإبداعية مسؤولية تحميل وحدة عمل مساحة التخزين المشتركة وتشغيلها. يزوِّد النص البرمجي طلب التشغيل بمجموعة من عناوين URL للاختيار من بينها.
2. في وحدة العمل، إذا لم يتمّت بدء مساحة التخزين المشتركة بعد، يتمّ بدء مساحة التخزين باستخدام استراتيجية التناوب الأوليّة لتصميم الإعلان وفهرس تصميم الإعلان. استراتيجية التناوب الأولية المستخدَمة في هذا العرض التجريبي هي استراتيجية تسلسلية.
3. تقرأ الوظيفة المصغّرة وضع العرض بالتناوب من مساحة التخزين المشتركة وتُعرِض فهرس الإعلان التالي. في حال وضع العرض التدرّجي، يتم أيضًا تعديل فهرس تصميم الإعلان في مساحة التخزين المشتركة بالقيمة الجديدة التي سيتم استخدامها في الطلب التالي.تعرِض الوظيفة المصغّرة FencedFrameConfig أو كائن URN غير الشفاف استنادًا إلى قيمة resolveToConfig المستخدَمة عند استدعاء selectURL.
4. يعرض نصّ برمجي لعرض الإعلانات بالتناوب الإعلان المحدّد في إطار محدود أو إطار iframe. راجِع عرض مستند إعلان للحصول على تفاصيل عن أنواع النتائج.
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. للوصول إلى ميزة "تبديل المواد الإبداعية" باستخدام Select URL API وShared Storage، انتقِل إلى https://shared-storage-demo.web.app/. اختَر عرض "عرض الإعلانات بالتناوب" التجريبي.

2. اختَر استكشاف العرض الترويجي بصفتك "الناشر "أ". ستتم إعادة توجيهك إلى https://shared-storage-demo-publisher-a.web.app/creative-rotation. تحمِّل الصفحة محتوى مرقّمًا استنادًا إلى بيانات تناوب المواد الإبداعية المحفوظة في Shared Storage، والتي يمكن الوصول إليها من خلال Select URL API. تتمثل أوضاع عرض تصميمات الإعلانات بالتناوب التجريبية في التوزيع التسلسلي والتوزيع العادل والتوزيع المرجّح. تنفِّذ الوظيفة المصغّرة المنطق لاختيار المحتوى الذي يظهر في إطار iframe. تعرض الصورة التالية صفحة الناشر.

   
   

3. للاطّلاع على ما يتم تخزينه في "مساحة التخزين المشتركة"، انتقِل إلى التطبيق -> مساحة التخزين المشتركة في "أدوات مطوّري البرامج" في Chrome. يتم إنشاء إدخالَين لمساحة التخزين المشتركة. تتوفّر مساحة تخزين فارغة لمصدر https://shared-storage-demo-publisher-a.web.app. سيحتوي هذا على مساحة تخزين خاصة بهذا المصدر وسيظل فارغًا في العرض التجريبي لأنّ الناشر لا يحتاج إلى الكتابة في مساحة التخزين المشتركة. يُرجى العِلم أنّه سيتم إنشاء مساحة تخزين مشابهة للناشر "ب" عند زيارة هذه الصفحة في وقت لاحق للعرض التجريبي.

   
   

4. سيتم إنشاء إدخال آخر لمساحة التخزين المشتركة لمصدر https://shared-storage-demo-content-producer.web.app. هذا هو تخزين إطار iframe التابع لجهة خارجية والمضمّن في صفحة الناشر. سيتم استخدام مساحة التخزين هذه لمشاركة البيانات بين الناشرين المتاحَين من أجل تنسيق اختيار المواد الإبداعية. سيتم استخدام مساحة التخزين المشترَكة هذه لحفظ معلومات عن تصميم الإعلان المعروض واستراتيجية التدوير من خلال حفظ زوجَين من مفتاحَي القيمة. المفتاح الأول المستخدَم في العرض التجريبي هو creative-rotation-index، وتكون قيمته هي فهرس تصميم الإعلان الحالي في الوضع التسلسلي. المفتاح الثاني هو creative-rotation-mode الذي يحدّد استراتيجية التغيير المستخدَمة.

   
   

5. سيؤدي إعادة تحميل الصفحة في الوضع التسلسلي إلى عرض تصميم الإعلان التالي في التسلسل 1، 2، 3، 1، …، وستتغيّر قيمة مفتاح فهرس-العرض-بالتناوب وفقًا لفهرس تصميم الإعلان المعروض في الوضع التسلسلي.

   
   

6. سيؤدي تغيير وضع تدوير تصميم الإعلان باستخدام أزرار التحكّم إلى تعديل قيمة مفتاح وضع تدوير تصميم الإعلان في الاستراتيجية المقابلة. سيستخدم رمز القطعة الصغيرة هذا لاختيار تصميم الإعلان التالي الذي سيتم عرضه في إطار iframe. يُرجى العلم أنّ القيمة المحفوظة لمؤشر "تبديل المواد الإبداعية" لا تتغيّر في أوضاع التبديل غير التسلسلي.

   
   

7. انتقِل إلى صفحة "الناشر "ب" على الرابط https://shared-storage-demo-publisher-b.web.app/creative-rotation. في الوضع التسلسلي، يجب أن يكون تصميم الإعلان المعروض هو تصميم الإعلان التالي في التسلسل المعروض عند الانتقال إلى عنوان URL الخاص بـ "الناشر "أ". عند فحص مساحة التخزين المشتركة لمنتج المحتوى، يمكنك العثور على أنّ "الناشر أ" و "الناشر ب" يتشاركان مساحة التخزين نفسها ويستخدمان الإعدادات المتاحة لاختيار تصميم الإعلان التالي الذي سيتم عرضه واستراتيجية التدوير التي سيتم استخدامها.

   
   

8. مساحة التخزين المشتركة الخاصة بـ "الناشر ب" فارغة، تمامًا مثل مساحة التخزين المشتركة الخاصة بـ "الناشر أ".

   
   

   Use cases

   All available use cases for Select URL API can be found in this section. We'll continue to add examples as we receive feedback and discover new test cases.

   • Rotate ad creatives: Store data, such as creative ID and user interaction, to determine which creative users' see across different sites.
   • Select ad creatives by frequency: Use view count data to determine which creative users' see across different sites.
   • Run A/B testing: You can assign a user to an experiment group, then store that group in Shared Storage to be accessed cross-site.
   • Customize experience for known customers: Share custom content and calls-to-action based on a user's registration status or other user states.

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.

Stay Informed

• Mailing List: Subscribe to our mailing list for the latest updates and announcements related to the Select URL and Shared Storage APIs.

Need Help?

• Developer Support: Connect with other developers and get answers to your questions in the Privacy Sandbox Developer Support repository.