דף זה תורגם על ידי Cloud Translation API.

דיווח מכרזים של Protected Audience API

מדידת הנתונים והתוצאות של מכרזים ב-Protected Audience API

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

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

צבירה פרטית שאוספת אותות ותוצאות של מכרזים כדי ליצור דוחות סיכום.
Ads Reporting API עבור Fenced Frames ו-iframes, שהוא ערוץ במסגרות שמאפשר תקשורת עם worklet של Protected Audience API. ה-API מאפשר לשייך נתונים ברמת האירוע לאותות מכרז. הדיווח ברמת האירוע של Ads Reporting API הוא מנגנון מעבר, עד ליצירת מנגנון דיווח פרטי יותר.
Attribution Reporting שמאפשר לכם לשייך נתוני המרות לאותות מכרזים.
אחסון משותף, המאפשר לכתוב אותות של מכרזים באחסון ממקורות שונים ולדווח על הנתונים האלה מאוחר יותר באמצעות צבירה פרטית.

סקירה כללית של דוחות Protected Audience API

תהליך עבודה כולל של 'קהל מוגן' — תהליך העבודה הכולל של Protected Audience

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

במהלך המכרז, אפשר לדווח על נתוני המכרז באמצעות מודולי worklet של דיווח. במהלך זמן העיבוד, תוכלו לדווח על נתוני מעורבות מ-iframe או ממסגרת מגודרת. במהלך מועד ההמרה, ניתן להשתמש ב-Attribution Reporting API כדי לדווח על נתוני שיוך מדף היעד.

דיווח על מיקומים

במכרזים, הקונים יכולים לדווח על אותות שזמינים ב-worklets generateBid() ו-reportWin(), ואתרי המכירה יכולים לדווח על אותות שזמינים ב-scoreAd() וב-reportResult(). מחוץ למכרז, הקונים והמוכרים יכולים לדווח על נתונים ממסגרת שמציגה את המודעה ומהאתר שממנו בוצעה ההמרה.

תקופת זמן	יעד	מיקום	יש נתונים זמינים	ממשקי Reporting API זמינים
מכרז	קונים	`generateBid()`	אותות, תוצאות מכרזים וביצועי מכרזים	API לצבירה פרטית
	קונים	`reportWin()`		Private Aggregation API Ads Reporting API
	משווק	`scoreAd()`		API לצבירה פרטית
	משווק	`reportResult()`		Private Aggregation API Ads Reporting API
עיבוד	קונה / מפיץ	מסגרת באתר של בעל התוכן הדיגיטלי	נתונים ברמת האירוע במסגרת המודעה	Private Aggregation API Ads Reporting API
המרה	קונה / מפיץ	אתר המרות	נתונים ברמת ההמרה והאירוע מאתר ההמרות	Attribution Reporting API API של צבירה פרטית Ads Reporting API

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

הנתונים זמינים במכרז של Protected Audience API

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

אותות

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

אות	‫תיאור	הגדרת מיקום	משתמשים	זמינות
auctionSignals	הנתונים הזמינים בהקשר שבו מתקיימת המכרז. הנתונים האלה יכולים לכלול מידע על תוכן הדף, נתוני משתמשים מאינטראקציה ישירה ועוד.	המפיץ מוגדר על ידי בית העסק מהאתר של בעל התוכן הדיגיטלי בהגדרת המכרז.	קונה מפיץ	createBid scoreAd reportWin של דוח מנצח
directFromSellerSignals	אותם הנתונים לגבי `auctionSignals`, `perBuyerSignals`, `sellerSignals`, אבל מובטח שהאותות יגיעו מבית העסק שצוין.	מוגדר דרך כותרות תגובת HTTP של בית העסק	קונה מפיץ	createBid scoreAd reportWin של דוח מנצח
browserSignals	נתונים שונים שסופקו על ידי הדפדפן (`topWindowHostname`, `interestGroupOwner`, `renderUrl`, `adComponents`, `biddingDurationMsec`, `IGJoinCount`, `IGRecency`, `modelingSignals`).	מוגדר על ידי הדפדפן.	קונה מפיץ	createBid scoreAd reportWin של דוח מנצח
sellerSignals	אותות המסופקים לבית העסק לצורך דירוג מודעות.	המפיץ מוגדר על ידי בית העסק מהאתר של בעל התוכן הדיגיטלי בהגדרת המכרז.	משווק	ניקודAd reportWin תוצאת דוח
trustedScoringSignals	אותות בזמן אמת שמספקים לבית העסק לצורך דירוג המודעות.	כתובת ה-URL מוגדרת על ידי בית העסק מהאתר של בעל התוכן הדיגיטלי בהגדרת המכרז.	משווק	תוצאה של דוח מודעות
perBuyerSignals	נתונים לפי הקשר של מכרזים שסופקו לקונים ספציפיים. אתר המכירה יכול לאחזר את הערכים של הקונים לפני תחילת המכרז. זהו הידע של הקונה לגבי ההזדמנות להצגת מודעה.	המפיץ מוגדר על ידי בית העסק מהאתר של בעל התוכן הדיגיטלי בהגדרת המכרז.	קונים	createBid scoreAd reportWin של דוח מנצח
trustedBiddingSignals	אותות בזמן אמת שניתן לקונים לצורך בידינג להצגת מודעות.	כתובת ה-URL הוגדרה על ידי הקונה מאתר המפרסם כאשר קבוצת תחומי העניין מוגדרת.	קונים	generateBid
userBiddingSignals	נתוני משתמש שסופקו על ידי הקונה.	מוגדר על ידי הקונה מאתר המפרסם כאשר קבוצת העניין מוגדרת .	קונים	generateBid

האובייקט הגדרת המכרז הוא המקור העיקרי של הנתונים שמסופקים כדי להיות זמינים כאותות בסביבות עבודה. בעל התוכן הדיגיטלי ואתר המכירה יכולים לספק נתונים לפי הקשר ונתונים מאינטראקציה ישירה (First-Party) בהגדרת המכרז. ניתן להעשיר את האותות האלה בנתונים של הקבוצות של תחומי העניין מהקונה, נתונים ברמת האירוע מהמסגרת של הצגת המודעות, ונתוני שיוך מדף הקליקים. הנתונים שדווחו יכולים לשמש לדיווח על קונים/מוכרים, חיוב, תקצוב, אימון מודלים של למידת מכונה ועוד.

נתונים זמינים אחרים

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

נתונים זמינים מחוץ למכרז של Protected Audience API

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

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

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

דיווח ברמת האירוע

דוחות ברמת האירוע מכילים מידע מאירוע אחד או יותר. אירוע יכול להיות זכייה במכרז, חשיפה של מודעה או המרה. עד שנת 2026 לפחות, דוחות על זכיות במכרז ברמת האירוע יישארו בתוקף, לא יהיה צורך במסגרות מגודרות כדי לעבד מודעה מסוג Protected Audience, ואפשר להשתמש ב-iframe עם גישה לא מוגבלת לרשת לצורך דיווח ברמת האירוע. בנוסף, Ads Reporting API זמין במסגרות מגודרות ובמסגרות iframe כדי שתוכלו לשייך את נתוני המכרז ונתוני ההמרות לנתונים ברמת האירוע מהמסגרת. מטרת השינויים האלה היא לאפשר למערכת לבצע את ההעברה בקלות רבה יותר, כי בזמן ההעברה של המערכת ל-Protected Audience API, תוכלו להמשיך להשתמש בתשתית הדיווח הקיימת שלכם עד שנת 2026 לפחות.

דיווח על זכייה במכרז ברמת האירוע עם `sendReportTo()`

מנגנון זמין לדיווח על נתונים ברמת האירוע במכרזים של Protected Audience API הוא sendReportTo() function שזכה במכרז. הפונקציה זמינה ב-worklets של הדיווח על הקונה והמוכר, והדפדפן שולח בקשת GET למחרוזת של כתובת ה-URL שצוינה כשהצגת המודעה מתחילה. אפשר לקודד כל אות שזמין ב-worklet כפרמטרים של שאילתה בכתובת ה-URL.

לדוגמה, קונה יכול לדווח על סכום הצעת המחיר הזוכה מה-worklet של reportWin() למטרות חיוב:

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

אפשר להשתמש בפונקציה sendReportTo() כדי ליצור דוח זכייה לאתר המכירה כשמקבלים קריאה מ-reportResult(), ודוח זכייה לקונה אם הוא נשלח מ-reportWin(). הפונקציה sendReportTo() זמינה עד שנת 2026 לפחות.

הדוח 'מעורבות' (Engagement)

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

אפשר להשתמש בפונקציה sendReportTo() שמתוארת למעלה כדי לשייך נתוני מכרז לנתונים ברמת האירוע מ-iframe, אבל היא לא פועלת במסגרת מגודרת כי לא ניתן להעביר מזהה ייחודי מהכלי המוטמע כי התקשורת בין כלי ההטמעה למסגרת הגוברת מוגבלת. כדי לשייך נתוני מכרז לנתונים ברמת האירוע ממודעה עם מסגרת מגודרת, ניתן להשתמש ב-Ads Reporting API.

Ads Reporting API עבור מסגרות מגודרות ו-iframes

Ads Reporting API למסגרות מגודרות ולמסגרות iframe מאפשר לשייך נתונים ברמת האירוע של משתמש ממסגרת מודעה לאותות במסגרת מכרז של Protected Audience.

ב-worklet של Protected Audience API לדיווח, אתם יכולים לרשום חיישן מודעה באמצעות הפונקציה registerAdBeacon() ולהעביר את כתובת ה-URL לדיווח עם האותות שנוספים כפרמטרים של שאילתה. מציינים גם את האירוע המותאם אישית שרוצים לשייך לכתובת ה-URL לדיווח. לאחר מכן, במועד מאוחר יותר, כשהמודעה תוצג במסגרת מגודרת, תוכלו להפעיל את האירוע המותאם אישית על ידי קריאה לפונקציה window.fence.reportEvent(). ניתן להוסיף למטען הייעודי (payload) נתונים שזמינים בתוך המסגרת המוגבלת.

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

בדוגמה הבאה, מזהה קמפיין משויך למטען ייעודי (payload) ברמת האירוע עם הקואורדינטות של הקליקים:

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

גם Fenced Frames Ads Reporting API יהיה זמין עד שנת 2026 לפחות, מאותן סיבות שקשורות לדיווח על זכיות.

כדי לקבל הסבר מעמיק יותר, כדאי לעיין בהסבר.

גישה לא מוגבלת לרשת

פריימים בגדר (Fenced Frame) יאפשרו טעינה של משאבי רשת באותו אופן כמו iframe, ותוכלו לשלוח נתונים ברמת האירוע בתוך מסגרות מגודרות לשרת שלכם. בהמשך תהיה לך אפשרות ליצור דוחות ברמת האירוע בצד השרת. כדי לעשות זאת, יש לשייך את הנתונים ברמת האירוע ממסגרת מגודרת לנתוני המכרז שנשלחו באמצעות sendReportTo(), שעליהם דיברנו בקטע מנגנון הדיווח ברמת האירוע של המכרז שלמעלה.

הגישה לרשת תוגבל מתישהו אחרי ההוצאה משימוש של קובצי cookie של צד שלישי.

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

דוח ייחוס למקורות תנועה

דוח שיוך (Attribution) מאפשר לכם לשייך המרה באתר למודעה שנבחרה ממכרז של Protected Audience API. לדוגמה, משתמש עשוי ללחוץ על מודעת מוצר שאתם מפרסמים, לעבור לאתר של המפרסם, לבצע בו רכישה ואתם רוצים לשייך את הרכישה למודעה שהוצגה. Attribution Reporting API ישולב עם Protected Audience API כדי לשלב את נתוני המכרז מהאתר של בעל התוכן הדיגיטלי ונתוני ההמרות מהאתר של המפרסם.

אנחנו מתכננים פתרון קבוע יותר, אבל אפשר להשתמש ב-Ads Reporting API לפריימים מגודרים כמנגנון מעבר ליצירת דוח מצטבר ברמת האירוע עם דוחות השיוך (Attribution). שימו לב: הדוחות האלה מיועדים למדידת המרות, והם נפרדים מדוחות ההתעניינות ברמת האירוע ומדוחות האינטראקציות המצטברים, שנוצרו מהמכרז וממסגרת המודעות. כשיהיה מוכן, נפרסם הודעת הסבר כדי לפתור אותה באופן קבוע יותר.

מנגנון מעבר

כשרושמים משׂואת רשת (beacon) של מודעה, אפשר להשתמש במילת המפתח reserved.top_navigation. הכותרת הזו תוסיף באופן אוטומטי את הכותרת Attribution-Reporting-Eligible כדי שהחיישן יעמוד בדרישות לרישום כמקור שיוך.

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

כדי לצרף נתונים ברמת האירוע לאיתות Bluetooth שרשמת, אפשר להפעיל setReportEventDataForAutomaticBeacons() מהפריים המגודר באמצעות המטען הייעודי (payload) של האירוע.

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

מידע נוסף זמין בקטע Attribution Reporting API בהסבר על Ads Reporting API.

דוגמה לדיווח על מעורבות והמרות

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

בתהליך העבודה הזה, הקונה מתואם עם המפיץ כדי לשלוח מזהה ייחודי למכרז. במהלך המכרז, הקונה שולח את המזהה הייחודי הזה עם נתוני המכרז. במהלך העיבוד ומועד ההמרה, הנתונים מהמסגרת המגוונת או מה-iframe נשלחים גם הם עם אותו מזהה ייחודי. לאחר מכן, ניתן יהיה להשתמש במזהה הייחודי כדי לשייך את הדוחות האלה יחד.

תהליך עבודה:

לפני שהמכרז מתחיל, הקונה שולח לאתר המכירה מזהה ייחודי כחלק מהתגובה הפרוגרמטית להצעות מחיר בזמן אמת (RTB). אפשר להגדיר את המזהה בתור משתנה כמו auctionId. המזהה מועבר בתור perBuyerSignals ב-auctionConfig והוא הופך לזמין ב-worklet של הקונה.
בזמן המכרז, הקונה יכול לרשום אלומת מודעה שתופעל במהלך מועד עיבוד המודעה ומועד ההמרה (registerAdBeacon()).
1. כדי לשייך אותות של מכרז לאירוע של מסגרת מודעות, צריך להגדיר את auctionId כפרמטר של שאילתה בכתובת ה-URL של האלומה.
2. כדי לשייך אותות של מכרז לאירוע המרה, צריך להגדיר את הערך auctionId בכתובת ה-URL של החיישן.
בזמן עיבוד המודעה, אפשר להפעיל או לשפר את איתות Bluetooth שרשמתם בזמן המכרז באמצעות נתונים ברמת האירוע.
1. מפעילים את אירוע המסגרת עם reportEvent() ומעבירים את הנתונים ברמת האירוע.
2. הוספת מטען ייעודי (payload) ברמת האירוע לאיתות השיוך באמצעות setReportEventDataForAutomaticBeacons()
3. כדי לרשום את המודעה ב-Attribution Reporting API, צריך להגיב לבקשות של חיישן המודעה עם הכותרת Attribution-Reporting-Register-Source.
במהלך מועד ההמרה, אתם יכולים להפעיל את המקור שרשמתם בזמן המכרז.

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

תהליך עבודה דומה רלוונטי לאתר מכירה אם נדרשת גישה לנתוני שיוך, וגם אתר מכירה יכול להשתמש במזהה ייחודי לשליחה באמצעות registerAdBeacon(). מהמסגרת, הקריאה ל-reportEvent() מכילה נכס יעד שאפשר להשתמש בו כדי לשלוח את הדוח גם לקונה וגם לאתר המכירה. שימו לב שה-SSP חייב להופיע גם בדף הנחיתה כדי שהטריגר ישויך למקור.

צבירת נתונים של 'קהל מוגן'

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

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

מידע נוסף על ה-API זמין במאמר צבירה פרטית.

צבירת אותות במכרזים

ניתן לצבור את האותות שזמינים ב-worklets לשרת שלכם באמצעות צבירה פרטית. לצבירת אותות, אפשר להשתמש בשיטה privateAggregation.contributeToHistogram() שזמינה ב-worklet של הבידינג של הקונה, ב-worklet של דירוג בית העסק וב-worklets לדיווח על קונים/מוכרים.

בדוגמה הזו, הצעת המחיר הזוכה נצברת בקטגוריית הבעלים של קבוצת תחומי העניין:

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
}

זה המנגנון הכללי שבו צריך להשתמש כשהאותות שרוצים לצבור לא משויכים לנתונים ברמת האירוע ולא מופעלים על ידי אירוע שנמצא מחוץ למכרז. מידע נוסף בנושא דיווח על אותות של מכרזים זמין במאמר הסבר.

צבירת אותות ממכרז עם נתוני אירועים

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

כדי לצבור אותות של מכרזים לפי אירועים, אפשר להשתמש בפונקציה privateAggregation.contributeToHistogramOnEvent(eventType, contribution). הפונקציה הזו משתמשת במחרוזת שמציינת את סוג האירוע ואת התרומה שידווחו כשהאירוע הזה מופעל. אפשר לקרוא לשיטה עם סוג אירוע מותאם אישית, ולאחר מכן להפעיל את window.fence.reportEvent(eventType) ממסגרת המודעה כדי להפעיל את שליחת הדוח.

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

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

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

// Ad frame
window.fence.reportEvent('click');

לאחר מכן, מאוחר יותר, במסגרת המודעה, אפשר להפעיל את שליחת הדוח באמצעות קריאה ל-reportEvent(eventType):

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

דיווח על תוצאות וביצועים במכרזים

אפשר גם לצבור תוצאות מכרזים שמופעלות על ידי אירוע ניצחון או הפסד במכרז עם contributeToHistogramOnEvent(eventType, contribution), אם מעבירים מילות מפתח מסוג אירוע שמור (reserved.win, reserved.loss ו-reserved.always).

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

אם אתם מקבלים ערך בסיס כלשהו, למשל סכום הצעת המחיר שזכתה במכרז, אתם יכולים להגדיר כמה להוסיף או להפחית מהערך הזה, ואז לדווח על הערך הסופי. לדוגמה, אם הצעת המחיר הזוכה, בסך 20 ש"ח, מוגדרת כערך הבסיס, תוכלו להחסיר את הצעת המחיר בסך 8 ש"ח כדי לחשב את הערך בפועל של 12 ש"ח מתוך הסכום שהחמצתם במכירה הפומבית.

דיווח על תוצאות מכרזים

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

כדי לבדוק בכמה החמצתם את המכרז, תוכלו להחסיר את הצעת המחיר שלכם ממחיר הצעת המחיר שזכתה במכרז:

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

אחרי שליחת הדוח, הערך שדווח בפועל יהיה הערך המותאם של baseValue עם סטייה של הערך offset. מידע נוסף זמין במאמר הסבר.

דוחות ביצועים

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

למידע נוסף, יש לעיין בהסבר.

אחסון אותות ממכרזים באחסון משותף

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

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

מ-worklet של Protected Audience API, אתם יכולים לכתוב מפתחות וערכים באחסון המשותף:

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

במועד מאוחר יותר, תוכלו לטעון worklet של אחסון משותף כדי לקרוא ולשלוח את הערך באמצעות צבירה פרטית:

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

מידע נוסף על 'אחסון משותף' זמין בקטע על 'נפח אחסון משותף' במדריך למפתחים שמשתמשים ב-Protected Audience API, הסבר, הדגמה פעילה וקוד ההדגמה ב-GitHub.

מה השלב הבא?

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

דיון על ה-API

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

התנסות עם ה-API

אתם יכולים לערוך ניסויים ולהשתתף בשיחה על Protected Audience API.