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

מדריך לממשקי API של בית העסק והפניות למכרז של מודעות Protected Audience API.

עדכון: השם של FLEDGE השתנה ל-Protected Audience API. למידע נוסף על שינוי השם, ניתן לקרוא את הפוסט בבלוג.

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

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

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

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

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

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

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

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

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

1. המשתמש מבקר באתר שמשתתף בתוכנית.
2. מכרז פרוגרמטי מופעל על ידי אתר מכירה אחר כדי למצוא מודעה לפי הקשר למיקום מודעה זמין.
3. המכרז של Protected Audience API פועל.
4. scoreAd()משווה בין הצעות המחיר של הקונה לתוצאות של המכרז הראשון.

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

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

יש כמה גורמים שעשויים לנהל מכרז כדי למכור שטח להצגת מודעות.

לדוגמה:

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

למפיץ Protected Audience API, יש שלוש משימות:

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

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

הערה: מקור הסקריפט עם joinAdInterestGroup() חייב להיות תואם למקור של הבעלים של קבוצת האינטרס, ולכן צריך להפעיל את joinAdInterestGroup() מ-iframe (לדוגמה, מ-DSP) אלא אם המקור של הבעלים של קבוצת העניין תואם למקור של המסמך הנוכחי (לדוגמה, אתר עם קבוצות אינטרס משלו). ל-runAdAuction אין את אותן הדרישות, כך שהשימוש בתג <script> ככל הנראה יניב ביצועים הרבה יותר טובים מאשר השימוש ב-iframe ממקורות שונים.

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

auctionConfig מלונות

הערה: additionalBids לא נתמך בהטמעה הנוכחית של Protected Audience API. למידע נוסף, ניתן לקרוא את הקטע Auction-משתתפים בהסבר של Protected Audience API.

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

אופציונלי

דוגמה: {...}

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

sellerSignals

אופציונלי

דוגמה: {...}

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

sellerTimeout

אופציונלי

דוגמה: 100

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

perBuyerSignals

אופציונלי

דוגמה:

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

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

perBuyerTimeouts

אופציונלי

דוגמה: 50

תפקיד: זמן ריצה מקסימלי (ms) של סקריפטים מסוימים ב-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() משתמשת בארגומנטים הבאים:

ארגומנט	תפקיד
adMetadata	מטא-נתונים שרירותיים שסופקו על ידי הקונה.
auctionConfig	אובייקט הגדרת המכרז הועבר אל navigator.runAdAuction().
bid	ערך מספרי של הצעת מחיר.
trustedScoringSignals	ערכים שאוחזרו בזמן המכרז מהשרת המהימן של המפיץ, שמייצגים את הדעה של המפיץ על המודעה.

שאלות נפוצות

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

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

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

כל ההפניות ל-Protected Audience API

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

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

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