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

מדריך ל-Seller API וחומרי עזר למכרז של מודעות ב-Protected Audience API.

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

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

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

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

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

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 של 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

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

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

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