החלפת נכסי קריאייטיב של מודעות באמצעות Select URL API

אפשר להשתמש ב-Select URL API כדי לנצל את היתרונות של Shared Storage ולקבוע איזה קריאייטיב יוצג למשתמש באתרים שונים.

מפרסם או יוצר תוכן עשויים לרצות להחיל על קמפיין אסטרטגיות שונות של רוטציה של תוכן, ולבצע רוטציה של התוכן או של נכסי הקריאייטיב כדי לשפר את היעילות. אפשר להשתמש ב-API של בחירת כתובת URL כדי להפעיל אסטרטגיות שונות של רוטציה, כמו רוטציה עוקבת ורוטציה עם חלוקה שווה, באתרים שונים.

ה-API של בחירת כתובת URL מאפשר לכם לאחסן נתונים, כמו מזהה קריאייטיב, מספר הצפיות ואינטראקציות של משתמשים, כדי לקבוע איזה קריאייטיב יוצג למשתמשים באתרים שונים.

מידע נוסף על ה-API הבסיסי ועל אופן הפעולה של הבחירה זמין במאמרי העזרה של Select URL API.

איך מפעילים סבב קריאייטיבים

כדי לבצע ניסוי בסבב קריאייטיבים, צריך לוודא שממשק ה-API לבחירת כתובת URL ו-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 הוא סקריפט של צד שלישי שמגדיר את התוכן שיוצג לסירוגין, יחד עם נתונים שקובעים איזה תוכן יוצג בהמשך, כמו משקלים בדוגמה הזו. הסקריפט הזה מופעל בדף של בעל התוכן הדיגיטלי. הסקריפט הזה קורא ל-worklet של Shared Storage כדי לקבוע איזה תוכן להציג על סמך הנתונים שזמינים באחסון ורשימת כתובות ה-URL שאפשר לבחור מתוכן.

• ‫creative-rotation-worklet.js הוא קטע קוד של צד שלישי שמשתמש בנפח אחסון משותף כדי לחפש את אסטרטגיית הרוטציה, לחשב איזה תוכן לפרסם בהמשך ולהחזיר את התוכן הזה.

איך ההדגמה פועלת

1. כשמשתמש נכנס לדף של בעל התוכן הדיגיטלי, הדף טוען את הסקריפט של הצד השלישי creative-rotation.js. הסקריפט של סבב הקריאייטיב אחראי לטעינה ולהרצה של ה-worklet של האחסון המשותף. הסקריפט מספק את הקריאה ל-worklet עם רשימה של כתובות URL לבחירה.
2. ב-worklet, אם עדיין לא בוצעה אתחול של Shared Storage, האחסון מאותחל עם אסטרטגיית הרוטציה הראשונית של הקריאייטיב ועם אינדקס הקריאייטיב. שיטת הרוטציה הראשונית שבה נעשה שימוש בהדגמה הזו היא שיטה עוקבת.
3. ה-worklet קורא את מצב הסבב מהאחסון המשותף ומחזיר את האינדקס של המודעה הבאה. במקרה של מצב רוטציה רציף, הפונקציה גם מעדכנת את אינדקס הקריאייטיב באחסון המשותף עם הערך החדש שישמש לקריאה הבאה.ה-worklet מחזיר אובייקט FencedFrameConfig או אובייקט URN אטום על סמך הערך resolveToConfig שבו נעשה שימוש כשקוראים ל-selectURL.
4. הסקריפט של סבב הקריאייטיבים מציג את המודעה שנבחרה במסגרת Fenced Frame או במסגרת iframe. פרטים על סוגי ההחזרה מופיעים במאמר בנושא עיבוד מודעה.
5. כשמשתמש משנה את מצב הרוטציה, ה-worklet של האחסון המשותף מעדכן את הערך של מצב הרוטציה של הקריאייטיב שמאוחסן באחסון המשותף.
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 ואחסון משותף, עוברים אל https://shared-storage-demo.web.app/. בוחרים בהדגמה 'הצגת סבב קריאייטיבים'.

2. בוחרים באפשרות 'בעל תוכן דיגיטלי א' כדי לראות את ההדגמה. תתבצע הפניה אוטומטית לכתובת https://shared-storage-demo-publisher-a.web.app/creative-rotation. הדף נטען עם תוכן ממוספר על סמך נתוני הרוטציה של הקריאייטיב שנשמרו ב-Shared Storage, שאליהם יש גישה דרך Select URL API. מצבי ההדגמה של סבב הקריאייטיב הם סדרתי, חלוקה שווה וחלוקה משוקללת. ה-worklet מריץ את הלוגיקה לבחירת התוכן שמופיע ב-iframe. בתמונה הבאה מוצג הדף של המוציא לאור.

   
   

3. כדי לראות מה מאוחסן ב-Shared Storage, עוברים אל Application -> Shared Storage בכלי הפיתוח של Chrome. נוצרות שתי רשומות לאחסון משותף. אחסון ריק זמין למקור https://shared-storage-demo-publisher-a.web.app. האחסון הזה ספציפי למקור הזה, והוא יישאר ריק בהדגמה שלנו כי בעל האתר לא צריך לכתוב לאחסון המשותף. שימו לב: כשתיכנסו לדף של בעל התוכן הדיגיטלי ב' במועד מאוחר יותר לצורך ההדגמה, ייצור מאגר נתונים דומה.

   
   

4. ייווצר עוד רשומה של Shared Storage למקור 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 בשיטה המתאימה. הקוד הזה ישמש את קוד ה-worklet כדי לבחור את הקריאייטיב הבא שיוצג ב-iframe. חשוב לדעת: הערך שנשמר עבור creative-rotation-index לא משתנה במצבי רוטציה אחרים מלבד מצב עוקב.

   
   

7. עוברים לדף של 'אתר חדשות ב' בכתובת https://shared-storage-demo-publisher-b.web.app/creative-rotation. במצב רציף, הקריאייטיב שמוצג צריך להיות הקריאייטיב הבא ברצף שמוצג כשמבקרים בכתובת ה-URL של 'בעל האתר א'. בבדיקה של האחסון המשותף של יוצר התוכן, אפשר לראות שגם 'בעל אתר א' וגם 'בעל אתר ב' חולקים את אותו אחסון ומשתמשים בהגדרות שבו כדי לבחור את הקריאייטיב הבא שיוצג ואת אסטרטגיית הרוטציה שבה ישתמשו.

   
   

8. ה-Shared Storage של 'בעל תוכן דיגיטלי ב' ריק, בדומה ל-Shared Storage של 'בעל תוכן דיגיטלי א'.

   
   

   תרחישים לדוגמה

   בקטע הזה מפורטים כל תרחישי השימוש הזמינים של Select URL API. נמשיך להוסיף דוגמאות ככל שנקבל משוב ונמצא תרחישי בדיקה חדשים.

   • החלפת נכסי הקריאייטיב של המודעות: אחסון נתונים, כמו מזהה הקריאייטיב והאינטראקציה של המשתמש, כדי לקבוע אילו נכסי קריאייטיב המשתמשים יראו באתרים שונים.
   • בחירת נכסי קריאייטיב של מודעות לפי תדירות: אתם יכולים להשתמש בנתוני מספר הצפיות כדי לקבוע אילו נכסי קריאייטיב המשתמשים רואים באתרים שונים.
   • הרצת בדיקות A/B: אפשר להקצות משתמש לקבוצת ניסוי, ולאחר מכן לאחסן את הקבוצה הזו ב-Shared Storage כדי לגשת אליה באתרים שונים.
   • התאמה אישית של חוויית השימוש ללקוחות מוכרים: שיתוף תוכן מותאם אישית וקידומים מכירה על סמך סטטוס ההרשמה של המשתמש או מצבים אחרים של המשתמש.

השתתפות ושיתוף משוב

שימו לב שההצעה לגבי Select URL API נמצאת כרגע בתהליכי דיון ופיתוח, ויכול להיות שהיא תשתנה.

נשמח לשמוע מה דעתכם על Select URL API.

• הצעה: כדאי לעיין בהצעה המפורטת.
• דיון: הצטרפו לדיון הפעיל כדי לשאול שאלות ולשתף תובנות.