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

bookmark_border קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מדריך API למוכרים ומקורות מידע למכרז המודעות של Protected Audience API.

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

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

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

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

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

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

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

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

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

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

מי מפעיל את מכרז המודעות של 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 של וורקלט במכרז.

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

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

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

API reference guides are available:

• Developer guide for the Protected Audience API.
• Ad buyer guide to Protected Audience interest groups and bid generation.
• Ad seller guide to Protected Audience ad auctions.
• Guide to reporting auction results
• Best practices for Protected Audience ad auction latency
• Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.