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

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

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

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

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

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

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

תהליך העבודה הכולל של Protected Audience

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

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

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

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

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

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

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

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

אותות

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

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

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

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

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

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

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

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

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

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

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

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

מנגנון זמין לדיווח על נתונים ברמת האירוע במכרז Protected Audience הוא sendReportTo() function במקרה של זכייה במכרז. הפונקציה זמינה ב-worklets של דוחות קונים ומוכרים, והדפדפן שולח בקשת GET למחרוזת כתובת ה-URL שסופקה כאשר עיבוד המודעה מתחיל. אפשר לקודד כל אות שזמין ב-worklets כפרמטרים של שאילתה בכתובת ה-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.

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

Ads Reporting API למסגרות מגודרות ומסגרות iframe

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

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

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

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

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

בעתיד הגישה לרשת תוגבל.

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

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

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

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

מנגנון מעבר

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

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

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

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

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

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

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

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

תהליך העבודה:

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

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

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

צבירת נתונים של Protected Audience API

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

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

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

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

אפשר לצבור את האותות הזמינים ב-worklet של השרת שלכם באמצעות צבירה פרטית. לצורך צבירת אותות, אפשר להשתמש בשיטה 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):

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

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

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

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

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

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

מה השלב הבא?

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

דיון על ה-API

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

התנסות עם ה-API

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