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

מדריך FLEDGE API למפתחים

למי המאמר הזה מיועד?

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

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

מהו Protected Audience?

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

Protected Audience API הוא הניסוי הראשון שמוטמע ב-Chromium בקבוצת ההצעות TURTLEDOVE.

בתרשים הבא מוצגת סקירה כללית של מחזור החיים של FLEDGE:

איור שמספק סקירה כללית של כל שלב במחזור החיים של FLEDGE — מחזור החיים של FLEDGE.

איך אפשר לנסות את Protected Audience?

הדגמה של Protected Audience

הדרכה מפורטת בנושא פריסה בסיסית של Protected Audience באתרים של מפרסמים ובעלי תוכן דיגיטלי זמינה בכתובת Protect-audience-demo.web.app.

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

השתתפות בגרסת מקור לניסיון של Protected Audience

גרסת המקור לניסיון של רלוונטיות ומדידה של ארגז החול לפרטיות זמינה בגרסת בטא 101.0.4951.26 ואילך של Chrome למחשב עבור ממשקי ה-API של Protected Audience, Topics ו-Attribution Reporting.

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

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

ההדגמה של Protected Audience מספקת דוגמה בסיסית לפריסה מקצה לקצה של Protected Audience.

צריך לספק אסימון לניסיון לכל דף שבו רוצים להריץ קוד Protected Audience API:

כמטא תג בתג <head>:

<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
ככותרת HTTP:

Origin-Trial: TOKEN_GOES_HERE

מתן אסימון באופן פרוגרמטי:

const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

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

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

בדיקה באמצעות `chrome://flags` או פריטי Feature flags

אפשר לבדוק את Protected Audience אצל משתמש יחיד בגרסת Chrome בטא 101.0.4951.26 ואילך במחשב: * על ידי הפעלת chrome://flags/#privacy-sandbox-ads-apis. * הגדרת סימונים משורת הפקודה.

עיבוד מודעות ב-iframes או במסגרות מגודרות

אפשר לעבד מודעות ב<iframe> או ב-<fencedframe>, בהתאם לסימונים שהוגדרו.

כדי להשתמש ב-<fencedframe> כדי לעבד מודעות:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

כדי להשתמש ב-<iframe> כדי לעבד מודעות:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

יש לכלול את הדגל BiddingAndScoringDebugReportingAPI כדי להפעיל את שיטות הדיווח הזמניות מסוג הפסד/מנצח לניפוי באגים.

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

אילו תכונות נתמכות בגרסה האחרונה של Chrome?

התכונה Protected Audience API זמינה מאחורי התכונות הניסיוניות ב-Chromium, כניסוי ראשון לבדיקת התכונות הבאות של ההצעה 'Protected Audience':

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

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

הרשאות לקבוצות של תחומי עניין

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

שירות מפתחות/ערך

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

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

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

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

זיהוי תמיכה בתכונות

לפני השימוש ב-API, יש לבדוק אם הוא נתמך על ידי הדפדפן וזמין במסמך:

'joinAdInterestGroup' in navigator &&
  document.featurePolicy.allowsFeature('join-ad-interest-group') &&
  document.featurePolicy.allowsFeature('run-ad-auction') ?
  console.log('navigator.joinAdInterestGroup() is supported on this page') :
  console.log('navigator.joinAdInterestGroup() is not supported on this page');

איך אפשר לבטל את ההצטרפות ל-Protected Audience?

אפשר לחסום את הגישה ל-Protected Audience API בתור בעלי האתר או משתמשים פרטיים.

איך אתרים יכולים לשלוט בגישה?

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

יש שני עקרונות מדיניות בנושא הרשאות 'קהל מוגן' שאפשר להגדיר בנפרד: * join-ad-interest-group מפעיל או משבית את הפונקציונליות להוספת דפדפן לקבוצות של תחומי עניין * run-ad-auction מאפשר או משבית את הפונקציונליות להפעלת מכרז במכשיר

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

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

כדי להשבית את השימוש בממשקי API ב-iframe, צריך להוסיף את המאפיין allow הבא לרכיב iframe:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

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

ביטול הצטרפות של משתמש

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

להשבית את גרסאות הניסיון של ארגז החול לפרטיות בהגדרות Chrome: הגדרות > אבטחה ופרטיות > ארגז החול לפרטיות. אפשר לגשת לפריט הזה גם דרך chrome://settings/adPrivacy.
משביתים קובצי Cookie של צד שלישי בהגדרות Chrome: הגדרות > אבטחה ופרטיות.
מגדירים את קובצי Cookie ונתונים אחרים מאתרים לאפשרות 'חסימת קובצי cookie של צד שלישי' או ל'חסימת כל קובצי ה-cookie' מ-chrome://settings/cookies.
שימוש במצב פרטי.

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

ניפוי באגים של worklet של 'קהל מוגן'

החל מגרסה 98.0.4718.0 של Chrome Canary, ניתן לבצע ניפוי באגים ב-Worklets של Protected Audience בכלי הפיתוח ל-Chrome.

השלב הראשון הוא להגדיר נקודות עצירה (breakpoint) דרך קטגוריה חדשה בחלונית Event Listener Breakpoints בחלונית Sources.

צילום מסך של
כלי הפיתוח ב-Chrome Canary, עם הדגשה של החלונית Event Listener Breakpoints בחלונית 'מקורות'.
האפשרות 'תחילת שלב הבידינג של מגיש הצעות מחיר' מסומנת בקטע Worklet של Ad Auction (מכרז של מודעות).

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

הסקריפטים הפעילים של worklet יופיעו גם בחלונית 'שרשורים'.

צילום מסך של כלי הפיתוח ב-Chrome Canary, עם הדגשה של החלונית Threads בחלונית 'מקורות', שבו מוצג סקריפט העבודה הנוכחי שהושהה.

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

צפייה באירועים של קהלים מוגנים

בחלונית 'אפליקציה' בכלי הפיתוח ל-Chrome תוכלו לראות אירועי מכרזים וקבוצת תחומי עניין של Protected Audience API.

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

החלונית

של אפליקציית DevTools ב-Chrome Canary, שמוצגת בה מידע על אירוע הצטרפות לקבוצת אינטרס מוגנת של Protected Audience.

עכשיו, אם תבקרו באתר ההדגמה של Protected Audience בדפדפן שמופעל בו Protected Audience, כלי הפיתוח יציג מידע על האירועים bid ו-win.

החלונית
של אפליקציית DevTools ב-Chrome Canary, שמוצגת בה מידע על הצעת מחיר במכרז של Protected Audience במכרז
ואירועי זכייה.

איך Protected Audience API פועל?

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

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

1. משתמש מבקר באתר של מפרסם

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

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

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

2. הדפדפן של המשתמש יתבקש להוסיף קבוצת תחומי עניין

איור שמציג אדם שצופה באתר בדפדפן במחשב הנייד. קוד ה-JavaScript
שלjoinAdInterestGroup() פועל בדפדפן.

קטע הסבר: דפדפנים מתעדים קבוצות של תחומי עניין

הפלטפורמה בצד הדרישה (DSP) של המפרסם (או המפרסם עצמו) מפעילה את navigator.joinAdInterestGroup() כדי לבקש מהדפדפן להוסיף קבוצת תחומי עניין לרשימת הקבוצות שהדפדפן חבר בהן. בדוגמה הזו, הקבוצה נקראת custom-bikes והבעלים של הקבוצה הוא dsp.example. הבעלים של קבוצת תחומי העניין (במקרה זה, ה-DSP) יהיה קונה במכרז המודעות המתואר בשלב 4. חברות בקבוצת תחומי עניין נשמרת על ידי הדפדפן, במכשיר של המשתמש, ולא משותפת עם ספק הדפדפן או עם אף אחד אחר.

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

joinAdInterestGroup() זקוק להרשאה מהגורמים הבאים: * האתר שבו מבקרים * הבעלים של קבוצת תחומי העניין

לדוגמה: אסור ש-malicious.example יוכל להפעיל את joinAdInterestGroup() עם dsp.example כבעלים ללא הרשאה מה-dsp.example.

הרשאה מהאתר שבו מבקרים

מקור זהה: כברירת מחדל, ההרשאה מוענקת באופן מרומז לקריאות joinAdInterestGroup() מאותו מקור כמו האתר שבו מבקרים, כלומר מאותו מקור כמו המסגרת ברמה העליונה של הדף הנוכחי. אתרים יכולים להשתמש בכותרת של מדיניות ההרשאות join-ad-interest-group כדי להשבית קריאות joinAdInterestGroup() ל-Protected Audience API.

מקורות שונים: קריאה ל-joinAdInterestGroup() ממקורות שהם שונים מהדף הנוכחי יכולה להצליח רק אם לאתר שאליו נכנסת הוגדרה מדיניות הרשאות שמאפשרת קריאות ל-joinAdInterestGroup() ממסגרות iframe ממקורות שונים.

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

הרשאה מהבעלים של קבוצת האינטרס

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

ההצעה היא ש-joinAdInterestGroup() יוכל לפעול בדף או ב-iframe בדומיין של הבעלים, או לקבל ייפוי כוח לדומיינים אחרים שסופקו באמצעות רשימה בכתובת URL של .well-known.

שימוש ב-navigator.joinAdInterestGroup()

הדוגמה הבאה ממחישה איך אפשר להשתמש ב-API:

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

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

נקודה חשובה: כל כתובות ה-URL המשמשות כפרמטרים לשיטות של Protected Audience API חייבות להגיע ממקורות מאובטחים: צריך להציג את כל המשאבים באמצעות כתובות URL מסוג HTTPS. איך להשתמש ב-HTTPS לפיתוח מקומי מסביר איך לעשות זאת כשמפעילים את Protected Audience באופן מקומי. בנוסף, biddingLogicUrl, decisionLogicUrl ו-trustedBiddingSignals מחייבים כותרת תגובת HTTP מסוג X-Allow-FLEDGE: true.

מאפיינים של קבוצת תחומי עניין

מאפיין (property)	חובה	דוגמה	תפקיד
`owner`	חובה	`'https://dsp.example'`	מקור הבעלים של קבוצת תחומי העניין.
`name`	חובה	`'custom-bikes'`	השם של קבוצת האינטרס.
`biddingLogicUrl`**	אופציונלי*	`'https://dsp.example/bid/custom-bikes/bid.js'`	כתובת URL להפעלת JavaScript להגשת הצעות מחיר רצה ב-worklet.
`biddingWasmHelperUrl`**	אופציונלי*	`'https://dsp.example/bid/custom-bikes/bid.wasm'`	כתובת URL של קוד WebAssembly שנוצר מ-`biddingLogicUrl`.
`dailyUpdateUrl`**	אופציונלי	`'https://dsp.example/bid/custom-bikes/update'`	כתובת URL שמחזירה קובץ JSON כדי לעדכן את המאפיינים של קבוצת תחומי העניין. (עדכון של קבוצת תחומי העניין).
`trustedBiddingSignalsUrl`**	אופציונלי	`'https://dsp.example/trusted/bidding-signals'`	כתובת URL בסיסית לבקשות ערך מפתח לשרת המהימן של מגיש הצעות המחיר.
`trustedBiddingSignalsKeys`	אופציונלי	`['key1', 'key2' ...]`	מפתחות לבקשות לשרת מהימן עם ערך מפתח.
`userBiddingSignals`	אופציונלי	`{...}`	מטא-נתונים נוספים שהבעלים יכולים להשתמש בהם במהלך הבידינג.
`ads`	אופציונלי*	`[bikeAd1, bikeAd2, bikeAd3]`	מודעות שייתכן שיוצגו עבור קבוצת תחומי העניין הזו.
`adComponents`	אופציונלי	`[customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]`	רכיבים למודעות שמורכבות מכמה חלקים.

* כל המאפיינים הם אופציונליים, מלבד owner ו-name. המאפיינים biddingLogicUrl ו-ads הם אופציונליים, אבל הם נדרשים כדי להשתתף במכרז. יכולים להיות תרחישים לדוגמה ליצירת קבוצת תחומי עניין בלי המאפיינים האלה: לדוגמה, יכול להיות שבעלים של קבוצת תחומי עניין ירצה להוסיף דפדפן לקבוצת תחומי עניין בקמפיין שעדיין לא פועל או לשימוש עתידי אחר, או שתקציב הפרסום שלו ייגמר באופן זמני.

** כתובות ה-URL biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl ו-trustedBiddingSignalsUrl חייבות להיות מאותו מקור כמו הבעלים. אין מגבלה כזו בכתובות ה-URL ads ו-adComponents.

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

dailyUpdateUrl מציין שרת אינטרנט שמחזיר את המאפיינים של קבוצת תחומי העניין בפורמט JSON בהתאם לאובייקט של קבוצת תחומי העניין שהועבר אל navigator.joinAdInterestGroup(). כך יש מנגנון שמאפשר לבעל הקבוצה לעדכן מדי פעם את המאפיינים של קבוצת תחומי העניין. בהטמעה הנוכחית, אפשר לשנות את המאפיינים הבאים:

biddingLogicUrl
biddingWasmHelperUrl
trustedBiddingSignalsUrl
trustedBiddingSignalsKeys
ads
priority

כל שדה שלא צוין ב-JSON לא יוחלף – רק שדות שצוינו ב-JSON יתעדכנו – בעוד שקריאה ל-navigator.joinAdInterestGroup() תחליף כל קבוצת אינטרס קיימת.

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

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

עדכונים ידניים

אפשר להפעיל באופן ידני עדכונים של קבוצות של תחומי עניין שבבעלות המקור של המסגרת הנוכחית דרך navigator.updateAdInterestGroups(). הגבלת הקצב של יצירת בקשות מונעת עדכונים בתדירות גבוהה מדי: קריאות חוזרות אל navigator.updateAdInterestGroups() לא יעשו שום דבר עד לסיום תקופת מגבלת הקצב (יום אחד). הגבלת הקצב של יצירת בקשות מתאפסת אם תתבצע הפעלה חוזרת של navigator.joinAdInterestGroup() לאותה קבוצת אינטרסים, owner ו-name.

עדכונים אוטומטיים

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

ציון מודעות לקבוצת עניין

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

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

איך קונים מגישים הצעות מחיר?

הסקריפט ב-biddingLogicUrl שסופק על ידי בעלים של קבוצת תחומי עניין חייב לכלול פונקציה generateBid(). כשהמוכר במרחב מודעות קורא לפונקציה navigator.runAdAuction(), הפונקציה generatedBid() מופעלת פעם אחת לכל אחת מקבוצות העניין שהדפדפן חבר בהן, במקרה שהבעלים של קבוצת תחומי העניין הוזמן להגיש הצעות מחיר. במילים אחרות, הפונקציה generateBid() מופעלת פעם אחת לכל מודעה מועמדת. בית העסק מספק מאפיין decisionLogicUrl בפרמטר של הגדרת המכרז שמועבר אל navigator.runAdAuction(). הקוד בכתובת ה-URL צריך לכלול פונקציית scoreAd(), שמופעלת לכל מגיש הצעות מחיר במכרז, כדי לדרג כל אחת מהצעות המחיר שהוחזרו על ידי generateBid().

הערה: המאפיין biddingWasmHelperUrl הוא אופציונלי, אבל הוא מאפשר למגיש הצעות המחיר לספק ב-WebAssembly תתי-תרחישים יקרים מבחינה חישובית, במקום ב-JavaScript, שייווצר מפונקציית ה-JavaScript שסופקה על ידי biddingLogicUrl. אם מציינים אותו, הוא צריך להפנות לקובץ בינארי של WebAssembly שנשלח עם application/wasm mimetype. ה-WebAssembly.Module התואם הופך לזמין על ידי הדפדפן לפונקציה generateBid().

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

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

הפונקציה generateBid() משתמשת בארגומנטים הבאים:

interestGroup
האובייקט מועבר אל joinAdInterestGroup() על ידי קונה המודעה. (ייתכן שקבוצת העניין תתעדכן דרך dailyUpdateUrl).
auctionSignals
מאפיין של הארגומנט הגדרת המכרז שהועבר אל navigator.runAdAuction() על ידי אתר המכירה במרחב המודעות. כך ניתן לקבל מידע על ההקשר של הדף (כמו גודל המודעה ומזהה בעל האתר), סוג המכרז (מחיר ראשון או מחיר שני) ומטא-נתונים אחרים.
perBuyerSignals
כמו במקרה של auctionSignals, מאפיין של ארגומנט הגדרת המכרז שהועבר אל navigator.runAdAuction() על ידי בית העסק. כך ניתן לספק אותות לפי הקשר מהשרת של הקונה לגבי הדף, אם המוכר הוא SSP שמבצע קריאה לבידינג בזמן אמת לשרתים של הקונים ומקשר את התגובה חזרה, או אם הדף של בעל התוכן הדיגיטלי יוצר קשר ישירות עם השרת של הקונה. אם כן, הקונה רשאי לבדוק חתימה קריפטוגרפית של האותות האלה ב-generateBid() כדי להגן מפני פגיעה.
trustedBiddingSignals
אובייקט שהמפתחות שלו הם trustedBiddingSignalsKeys של קבוצת תחומי העניין, והערכים שלו מוחזרים בבקשה trustedBiddingSignals.
browserSignals
אובייקט שנבנה על ידי הדפדפן, שעשוי לכלול מידע על הקשר הדף (למשל hostname של הדף הנוכחי, שהמוכר יכול לזייף בדרך אחרת) ונתונים של קבוצת תחומי העניין עצמה (למשל תיעוד של המועד שבו הקבוצה זכתה בעבר במכרז, כדי לאפשר מכסת תדירות במכשיר).

לאובייקט browserSignals יש את המאפיינים הבאים:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

כדי לחשב ערך של bid, הקוד ב-generateBid() יכול להשתמש במאפיינים של הפרמטרים של הפונקציה. לדוגמה:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

הפונקציה generateBid() מחזירה אובייקט בעל ארבעה מאפיינים:

ad
מטא-נתונים שרירותיים לגבי המודעה, כמו מידע שהמוכר מצפה לקבל על הצעת המחיר הזו או על הקריאייטיב של המודעה. המפיץ](/privacy-sandbox/resources/googleplay#ssp) משתמש במידע הזה בקריאייטיב של המודעה במכרז ובנכסי הקריאייטיב שלו. אתר המכירה משתמש במידע הזה במסגרת המכרז וההחלטות שלו.
bid
הצעת מחיר מספרית שתיכנס למכרז. המפיץ צריך להיות מסוגל להשוות הצעות מחיר מקונים שונים, ולכן הצעות המחיר חייבות להיות ביחידה מסוימת שנבחרת על ידי בית העסק (למשל, "USD לאלף"). אם הצעת המחיר היא אפס או שלילית, קבוצת תחומי העניין הזו לא תשתתף כלל במכרז של המוכר. באמצעות מנגנון זה, הקונה יכול ליישם כל כלל למפרסם לגבי המקומות שבהם המודעות שלו עשויות להופיע או לא להופיע.
render
כתובת URL או רשימה של כתובות URL שישמשו להצגת הקריאייטיב אם הצעת המחיר הזו תזכה במכרז. (ראו מודעות שמורכבות מכמה חלקים בהסבר על ה-API). הערך צריך להתאים לערך renderUrl של אחת מהמודעות שהוגדרו עבור קבוצת תחומי העניין.
adComponents
רשימה אופציונלית של עד 20 רכיבים עבור מודעות שמורכבות מכמה חלקים, שנלקחה מהמאפיין adComponents של הארגומנט של קבוצת תחומי העניין שהועבר אל navigator.joinAdInterestGroup().

שליחת בקשה לדפדפן לעזוב קבוצת אינטרס

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

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

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

3. המשתמש מבקר באתר שמוכר שטח להצגת מודעות.

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

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

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

4. מכרז של מודעות מופעל בדפדפן

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

קטע ההסבר: מפיצים מפעילים מכרזים במכשיר

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

אתר המכירה בשטחים להצגת מודעות מגיש לדפדפן של המשתמש בקשה להתחיל מכרז של מודעות באמצעות קריאה ל-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': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

הפונקציה runAdAuction() מחזירה הבטחה שתואמת ל-URN (urn:uuid:<something>) שמייצג את תוצאת המכרז של המודעה. אפשר לפענח את ההצפנה על ידי הדפדפן רק כשמעבירים אותה למסגרת מגודרת לצורך רינדור: הדף של בעל האתר לא יכול לבדוק את המודעה הזוכה.

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

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

`auctionConfig` מלונות

מאפיין (property)	חובה	דוגמה	תפקיד
`seller`	חובה	`'https://ssp.example'`	מקור המפיץ.
`decisionLogicUrl`	חובה	`'https://ssp.example/auction-decision-logic.js'`	כתובת URL ל-JavaScript של worklet של מכרז.
`trustedScoringSignalsUrl`	אופציונלי	`'https://ssp.example/scoring-signals'`	כתובת האתר של השרת המהימן של המפיץ.
`interestGroupBuyers*`	חובה	`['https://dsp.example', 'https://buyer2.example', ...]`	המקורות של כל הבעלים של קבוצות האינטרס שביקשו להגיש הצעות מחיר במכרז.
`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': ..., ...}, ...]`	הגדרות נוספות למכרזים של רכיבים.

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

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

איך המודעות נבחרות?

הקוד ב-decisionLogicUrl (מאפיין של אובייקט תצורת המכרז שמועבר אל runAdAuction()) חייב לכלול פונקציית scoreAd(). היא מוצגת פעם אחת לכל מודעה כדי לקבוע אם המודעה רצויה.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

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

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

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

5. המוכר והקונים המשתתפים מקבלים נתונים בזמן אמת מהשירות 'מפתח/ערך'

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

קטע הסבר: אחזור נתוני זמן אמת משירות הערך/מפתח של 'קהל מוגן'.

במהלך מכרז של מודעות, אתר המכירה של שטחי פרסום יכול לקבל נתונים בזמן אמת לגבי נכסי קריאייטיב ספציפיים של מודעות. כדי לעשות את זה, שולחים בקשה לשירות מפתח/ערך באמצעות המאפיין trustedScoringSignalsUrl של הארגומנט הגדרת המכרז שנשלח אל navigator.runAdAuction(), יחד עם המפתחות מהמאפיינים renderUrl של כל הרשומות בשדות ads ו-adComponents של כל קבוצות תחומי העניין במכרז.

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

כשמתבצעת קריאה ל-runAdAuction(), הדפדפן שולח בקשה לשרת המהימן של כל קונה מודעה. כתובת ה-URL של הבקשה עשויה להיראות כך:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2

כתובת ה-URL הבסיסית מגיעה מ-trustedBiddingSignalsUrl.
הדומיין hostname סופק על ידי הדפדפן.
הערך keys נלקח מ-trustedBiddingSignalsKeys.

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

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

6. המודעה הזוכה מוצגת

איור של אדם שצופה באתר חדשות בדפדפן במחשב הנייד. מוצגת מודעה
לקידום אופניים (20% הנחה) – עם מנעול מעל כדי לציין שהמודעה מוצגת
במסגרת מגודרת.

קטע ההסבר: דפדפנים מעבדים את המודעה המנצחת

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

7. תוצאת המכרז מדווחת

קטע ההסבר: דיווח ברמת האירוע (בינתיים)

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

בית העסק מדווח על תוצאה

סעיף הסברים: דיווח על בית העסק בנוגע לעיבוד

קוד ה-JavaScript של בית העסק שסופק ב-decisionLogicUrl (גם scoreAd()) יכול לכלול פונקציית reportResult() לדיווח על תוצאת המכרז.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

הארגומנטים שמועברים לפונקציה הזו הם:

auctionConfig
אובייקט הגדרת המכרז מועבר אל navigator.runAdAuction().

browserSignals
אובייקט שנבנה על ידי הדפדפן ומספק מידע על המכרז. לדוגמה:

{
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

הערך המוחזר של הפונקציה הזו משמש כארגומנט sellerSignals של הפונקציה reportWin() של מגיש הצעות המחיר הזוכה.

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

קטע הסבר: דיווח קונים על עיבוד ואירועי מודעות

קוד ה-JavaScript של מגיש הצעות המחיר הזוכה (שגם סיפק את generateBid()) יכול לכלול פונקציית reportWin() לדיווח על תוצאת המכרז.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

הערה: אם לא מגדירים את reportWin(), ההטמעה הנוכחית של Protected Audience ב-Chrome תציג אזהרה.

הארגומנטים שמועברים לפונקציה הזו הם:

auctionSignals ו-perBuyerSignals
אותם הערכים מועברים אל generateBid() של מגיש הצעות המחיר הזוכה.
sellerSignals
הערך המוחזר reportResult(), שמאפשר לאתר המכירה הזדמנות להעביר מידע לקונה.

browserSignals
אובייקט שנבנה על ידי הדפדפן ומספק מידע על המכרז. לדוגמה:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

הטמעת דיווח על אובדן זמני/זכייה

יש ב-Chrome שתי שיטות שזמינות באופן זמני לדיווח על מכירות פומביות:

forDebuggingOnly.reportAdAuctionLoss()
forDebuggingOnly.reportAdAuctionWin()

כל אחת מהשיטות האלה משתמשות בארגומנט אחד: כתובת אתר שיש לאחזר לאחר סיום המכרז. אפשר לקרוא להם כמה פעמים, גם ב-scoreAd() וגם ב-generateBid(), עם ארגומנטים שונים של כתובות URL.

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

השיטות האלה זמינות כברירת מחדל ב-Chrome אם מפעילים את chrome://flags/#privacy-sandbox-ads-apis. אבל, אם אתם מפעילים את Chrome עם תכונות ניסיוניות בשורת הפקודה כדי להפעיל את Protected Audience, תצטרכו להפעיל את השיטות באופן מפורש באמצעות הדגל BiddingAndScoringDebugReportingAPI. אם הדגל לא מופעל, השיטות עדיין יהיו זמינות אבל לא יקרה דבר.

8. המערכת מדווחת על קליק על מודעה

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

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

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

איור שמספק סקירה כללית של כל שלב במכרז המודעות של Protected Audience

מה ההבדל בין Protected Audience לבין TURTLEDOVE?

Protected Audience הוא הניסוי הראשון שמוטמע ב-Chromium בתוך משפחת ההצעות של TURTLEDOVE.

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

המאמץ של TURTLEDOVE הוא להציע ממשק API חדש שיענה על התרחיש לדוגמה הזה, תוך הצעת שיפורים עיקריים לשמירה על הפרטיות:

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

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

בקטע SPARROW: Criteo הציע להוסיף מודל שירות ("Gatekeeper") שפועל בסביבת ביצוע מהימנה (TEE). Protected Audience API כולל שימוש מוגבל יותר בסביבת TEE, שמאפשרת לחפש נתונים בזמן אמת ולקבל דוחות אגרגטיבים.
ההצעות של NextRollTERN ושל Magnite PARRROT תיארו את התפקידים השונים שהיו לקונים ולמוכרים במכרז במכשיר. תהליך מתן הצעות המחיר או מתן ציונים למודעות של Protected Audience מבוסס על עבודה זו.
השינויים ב-TURTLEDOVE המבוססים על תוצאות וברמת המוצר ב-TURTLEDOVE שיפרו את מודל האנונימיות ואת יכולות ההתאמה האישית של המכרז במכשיר
PARAKEET היא ההצעה של Microsoft לשירות מודעות דמוי TURTLEDOVE, שמסתמך על שרת proxy שפועל בסביבת TEE בין הדפדפן לספקי טכנולוגיות הפרסום, כדי לבצע אנונימיזציה של בקשות להצגת מודעות ולאכוף מאפיינים של פרטיות. שירות Protected Audience לא השתמש במודל הזה של שרת proxy. אנחנו משלבים את ממשקי ה-API של JavaScript עבור PARAKEET ו-Protected Audience API כדי לתמוך בפעולות עתידיות על השילוב בין התכונות הטובות ביותר של שתי ההצעות.

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

אילו הגדרות דפדפן זמינות?

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

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

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

יצירת מעורבות ושיתוף משוב

GitHub: קראו את ההצעה, העלו שאלות ועקבו אחר הדיון.
W3C: שוחח על תרחישים לדוגמה בתחום בשיפור הקבוצה העסקית לפרסום באינטרנט.
תמיכה למפתחים: אפשר לשאול שאלות ולהצטרף לדיונים בנושא מאגר התמיכה למפתחים של ארגז חול לפרטיות.
רשימת תפוצה של FLEDGE: fledge-api-announce – הודעות ועדכונים לגבי ה-API.
מצטרפים לשיחות המתוזמנות של Protected Audience (כל שבוע). כולם מוזמנים להצטרף – כדי להשתתף, חשוב קודם להצטרף אל WICG. אפשר להשתתף באופן פעיל או רק להאזין!
תוכלו להשתמש בטופס המשוב של ארגז החול לפרטיות כדי לשתף משוב באופן פרטי עם צוות Chrome מחוץ לפורומים ציבוריים.

פנייה לתמיכה

כדי לשאול שאלה לגבי ההטמעה שלך, לגבי ההדגמה או לגבי המסמכים: * פתח בעיה חדשה במאגר התמיכה של privacy-sandbox-dev-support. צריך להקפיד לבחור את התבנית של הבעיה ל-Protected Audience API. * העלאת בעיה במאגר הקוד לדוגמה ב-GitHub. * אם יש לכם שאלות כלליות יותר לגבי עמידה בתרחישים לדוגמה עם ה-API, תוכלו לדווח על בעיה במאגר ההצעות.

במקרה של באגים ובעיות בהטמעה של Protected Audience API ב-Chrome: * הצגת הבעיות הקיימות שמדווחים עבור ה-API. * אפשר להעלות בעיה חדשה בכתובת crbug.com/new.

קבלת עדכונים

כדי לקבל התראות על שינויים בסטטוס ב-API, הצטרפו לרשימת הדיוור למפתחים.
כדי לעקוב מקרוב אחרי כל הדיונים המתמשכים על ה-API, לחצו על הלחצן Watch (לצפות) בדף ההצעה ב-GitHub. לשם כך צריך ליצור חשבון GitHub.
כדי לקבל עדכונים כלליים לגבי ארגז החול לפרטיות, תוכלו להירשם לפיד ה-RSS [התקדמות בארגז החול לפרטיות].

למידע נוסף

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

תמונה מאת Ray Hennessy ב-UnFlood.