מדריך למוכרים: הפעלת מכרזים של מודעות

מדריך ורכיבי עזר למוכרים בנושא מכרזים למודעות ב-Protected Audience API.

במאמר הזה מופיע חומר עזר טכני בנושא מכרז המודעות, כפי שמשמש באיטרציה הנוכחית של Protected Audience API הניסיוני.

במדריך למפתחים מוסבר על מחזור החיים המלא של Protected Audience API. בנוסף, במסמך ההסבר על Protected Audience API מפורט איך מוכרים מפעילים מכרזים במכשיר.

אתם לא מפתחים? מידע נוסף מופיע בסקירה הכללית על Protected Audience API.

מהו מכרז המודעות של Protected Audience API?

מכרז מודעות של Protected Audience API הוא אוסף של תוכניות JavaScript קטנות שהדפדפן מריץ במכשיר של המשתמש כדי לבחור מודעה. כדי לשמור על הפרטיות, כל קוד מכרז המודעות של המוכר והקונים מופעל בוורקלטים מבודדים של JavaScript שלא יכולים לתקשר עם העולם החיצוני.

1. משתמש מבקר באתר שמוצגות בו מודעות.
2. הקוד של המוכר מופעל navigator.runAdAuction(). במאפיין הזה מציינים את שטחי הפרסום שמוצעים למכירה ואת הגורמים שיכולים להגיש הצעות מחיר. המוֹכרים צריכים לכלול גם סקריפט שנותן ציון לכל הצעת מחיר, scoreAd().
3. הקוד של הקונה המוזמן מופעל כדי ליצור הצעת מחיר, כתובת URL של קריאייטיב רלוונטי של מודעה ונתונים אחרים. סקריפט הבידינג יכול לשלוח שאילתות לגבי נתונים בזמן אמת, כמו התקציב שנותר לקמפיין הפרסום, משירות המפתח/הערך של הקונה.
4. הקוד של המוכר מדרג כל הצעת מחיר ובוחר את ההצעה המנצחת. הלוגיקה הזו משתמשת בערך הצעת המחיר ובנתונים אחרים כדי להחזיר את מידת הרצויות של הצעת המחיר. מודעות שלא יכולות לנצח את המודעה הזוכה בהקשר נדחות. המוֹכר יכול להשתמש בשירות משלו של זוגות מפתח/ערך כדי להציג נתונים בזמן אמת.
5. המודעה המנצחת מוחזרת כערך אטום שמוצג במסגרת מוגבלת. גם המוכר וגם בעל התוכן הדיגיטלי לא יוכלו לראות את הערך הזה.
6. הדיווח על המכרז נשלח למוכר ולמפרסמים שזכו בו.

מתי מתקיים המכרז?

אפשר להריץ את Protected Audience API בנפרד או עם מכרזים פרוגרמטיים. במכרז פרוגרמטי עם כמה מוכרים:

1. המשתמש מבקר באתר שמשתתף בתוכנית.
2. מכרז פרוגרמטי מופעל על ידי מוכר אחר כדי למצוא מודעה קונטקסטואלית לחריץ מודעה פנוי.
3. המכרז של Protected Audience API מופעל.
4. ‫scoreAd()compares the buyer's bids with the results of the first auction.

הצעות מחיר שלא יכולות לנצח את הצעת המחיר הזוכה בהקשר נדחות.

מי מריץ את המכרז של מודעות באמצעות Protected Audience API?

יכול להיות שיש כמה גורמים שמנהלים מכרז למכירת שטחי פרסום.

לדוגמה:

• בעל תוכן דיגיטלי: פועל באופן עצמאי כדי לארח תוכן מודעות באתר שלו.
• פלטפורמה לספקים (SSP): עובדת עם בעל התוכן הדיגיטלי ומספקת שירותים אחרים.
• סקריפט של צד שלישי: פועל בשם בעל האתר כדי לאפשר השתתפות במכרזים של מודעות.

ב-Protected Audience API, למוכר יש שלוש משימות:

• אכיפת כללים של בעלי תוכן דיגיטלי: אילו קונים ואילו הצעות מחיר עומדים בדרישות.
• הפעלת לוגיקה של מכרז: קוד JavaScript שמופעל ב-worklets כדי לחשב ציון רצויות לכל הצעת מחיר.
• מדווחים על תוצאת המכרז.

המשימות האלה מתבצעות באופן פרוגרמטי, בקוד שסופק על ידי המוכר כשהוא יוזם מכרז למודעות על ידי קריאה לפונקציית JavaScript‏ navigator.runAdAuction().

פונקציות API

runAdAuction()

המוכר שולח בקשה לדפדפן של המשתמש כדי להתחיל במכרז למודעות על ידי הפעלת navigator.runAdAuction().

לדוגמה:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

‫runAdAuction() מחזירה הבטחה שמובילה ל-URN ‏ (urn:uuid:<something>) שמייצג את תוצאת המכרז על שטחי הפרסום. הדפדפן יכול לפענח את הנתונים האלה רק כשהם מועברים למסגרת מוגבלת לצורך רינדור: דף בעל האתר לא יכול לבדוק את המודעה הזוכה.

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

auctionConfig מלונות

seller

חובה

דוגמה: 'https://ssp.example'

תפקיד: מקור המוכר.

decisionLogicUrl

חובה

דוגמה: 'https://ssp.example/auction-decision-logic.js'

תפקיד: כתובת URL של קובץ JavaScript של worklet למכרז.

trustedScoringSignalsUrl

אופציונלי

דוגמה: 'https://ssp.example/scoring-signals'

תפקיד: כתובת ה-URL של השרת המהימן של המוכר.

interestGroupBuyers

חובה

דוגמה: ['https://dsp.example', 'https://buyer2.example', ...]

תפקיד: מקורות של כל הבעלים של קבוצות אינטרסים שהתבקשו להגיש הצעות במכרז.

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

auctionSignals

אופציונלי

דוגמה: {...}

Role: Seller information about page context, type of auction, etc.

sellerSignals

אופציונלי

דוגמה: {...}

תפקיד: מידע שמבוסס על הגדרות המפיק, על בקשה להצגת מודעה בהתאם להקשר וכו'.

sellerTimeout

אופציונלי

דוגמה: 100

תפקיד: זמן הריצה המקסימלי (באלפיות השנייה) של סקריפט scoreAd() של המוכר.

perBuyerSignals

אופציונלי

דוגמה:

{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }

תפקיד: אותות הקשריים לגבי הדף לכל קונה ספציפי, מהשרת שלו.

perBuyerTimeouts

אופציונלי

דוגמה: 50

תפקיד: זמן הריצה המקסימלי (באלפיות השנייה) של סקריפטים מסוימים של generateBid() קונים.

componentAuctions

אופציונלי

דוגמה:

[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]

תפקיד: הגדרות נוספות למכרזים של רכיבים.

decisionLogicUrl

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

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

‫browserSignals הוא אובייקט שנבנה על ידי הדפדפן, כולל מידע שהדפדפן יודע ושסקריפט המכרז של המוכר עשוי לרצות לאמת:

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}

לפני שמכרז מתחיל, המוכר מחפש את המודעה הקונטקסטואלית הכי טובה למיקום המודעה הפנוי. חלק מהלוגיקה של scoreAd() דוחה כל מודעה שלא יכולה להיות טובה יותר מהמודעה הזוכה בהקשר.

scoreAd()

‫scoreAd() מקבל את הארגומנטים הבאים:

שאלות נפוצות

איך נקבעת המודעה הזוכה במכרז ומי בוחר אותה?

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

המוכר כולל לוגיקה בפונקציה scoreAd(), והדפדפן מפעיל את הפונקציה ב-worklet עם תקשורת מוגבלת עם קוד מחוץ ל-worklet. הדפדפן עצמו לא נותן ניקוד למודעות. הדפדפן אחראי באופן בלעדי להפעלת לוגיקת הניקוד ולבחירת הצעת המחיר עם הניקוד הגבוה ביותר.

כל חומרי העזר בנושא Protected Audience API

תוכלו להיעזר במדריכים הבאים עם ה-API:

• מדריך למפתחים של Protected Audience API.
• המדריך לקונים של מודעות בנושא קבוצות תחומי עניין ויצירת הצעות מחיר של Protected Audience.
• המדריך למוכר מודעות למכרזי מודעות של Protected Audience.
• מדריך לדיווח על תוצאות מכרזים
• שיטות מומלצות לזמן אחזור של מכרז מודעות עם Protected Audience
• פתרון בעיות ב'קהל מוגן'

הסבר על Protected Audience API כולל גם פרטים על התמיכה בתכונות והאילוצים.