Protected Audience API: מדריך למפתחים

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

אם אתם חדשים ב-Protected Audience API, כדאי לקרוא את סקירת Protected Audience API כדי לקבל הסבר כללי על ה-API.

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

סטטוס ההטמעה

• ההצעה ל-Protected Audience API עוברת עכשיו לזמינות כללית. לשאול שאלות ולהשתתף בדיון.
• סטטוס Protected Audience API של יכולות בהמתנה פרטים על שינויים ושיפורים ב-Protected Audience API ובמאפיינים שלו.
• סטטוס Blink
• סטטוס הפלטפורמה של Protected Audience API ב-Chrome: ספציפי ל-Protected Audience API ב-Chrome.
• סטטוס של פלטפורמת Chrome Ads API: אוסף של ממשקי API שמסייעים בפרסום: Protected Audience API, ‏ Topics, ‏ Fenced Frames ו-Attribution Reporting.

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

מה זה Protected Audience API?

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

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

התנסות ב-Protected Audience API

הפניית API זמינה

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

• מדריך לקונים של joinAdInterestGroup() ושל generateBid().
• מדריך למוכרים בנושא Protected Audience API runAdAuction()
• מדריך לקונים בנושא reportWin() ומדריך למוֹכרים בנושא reportResult()
• פתרון בעיות ב-Protected Audience API

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

הדגמה של Protected Audience API

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

בדיקת ה-API

אתם יכולים לבדוק את Protected Audience API למשתמש יחיד ב-Chrome Beta 101.0.4951.26 ואילך במחשב:

• מפעילים את כל ממשקי ה-API לשמירה על פרטיות בפרסום בקטע chrome://settings/adPrivacy.
• הגדרת דגלים משורת הפקודה רשימה מלאה של הדגלים הזמינים של Protected Audience API זמינה בחיפוש קוד Chromium.

רינדור מודעות ב-iframes או במסגרות בלי שיתוף נתונים

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

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

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

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

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

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

תכונות נתמכות

‫Protected Audience API מאחורי דגלי תכונות ב-Chromium הוא ניסוי ראשון לבדיקת התכונות הבאות של Protected Audience API:

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

מידע נוסף על תמיכה בתכונות ומגבלות זמין בהסבר על Protected Audience API.

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

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

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

Key/Value service

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

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

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

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

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

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

לפני שמשתמשים ב-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 API?

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

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

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

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

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

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

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

• מידע נוסף על Protected Audience API: Browsers Record Interest Groups.
• במדריך ל-API: קונים ו-DSP, מוסבר איך joinAdInterestGroup() וליצור הצעות מחיר.

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

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

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

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

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

אפשר לקרוא את generatedBid()התיעוד למפתחים.

3. המשתמש מבקר באתר שמוכר שטחי פרסום

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

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

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

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

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

במהלך מכרז על שטחי פרסום, המוכר יכול לבקש נתונים בזמן אמת על נכסי קריאייטיב ספציפיים של מודעות על ידי שליחת בקשה לשירות Key/Value שלו. המוֹכר יכול לבקש את המידע הזה במהלך runAdAuction() באמצעות המאפיין trustedScoringSignalsUrl, יחד עם המפתחות מהמאפיינים 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 API: שליפת נתונים בזמן אמת משירות המפתח/הערך של Protected Audience API.
• מומלץ לקרוא את המאמר הפיכת שירות המפתח/הערך של Protected Audience API לקוד פתוח.

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

ההבטחה שמוחזרת על ידי runAdAuction() נפתרת לאובייקט הגדרות של fenced frame ‏ (FencedFrameConfig) כשהדגל resolveToConfig מוגדר ל-true בהגדרות המכרז. הגדרת המסגרת משמשת מסגרת מגודרת כדי לנווט את המסגרת למודעה הזוכה, אבל כתובת ה-URL של המודעה לא גלויה למטמיע המסגרת.

אובייקט ההגדרה של fenced frame זמין החל מגרסה M114. מידע נוסף על האובייקט FencedFrameConfig זמין במאמר בבלוג של Chrome.

• קראו את ההסבר על Protected Audience API: הדפדפנים מציגים את המודעה הזוכה

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

התוכנית לטווח הארוך היא לאפשר לדפדפן לדווח על תוצאות המכרז למוכר ולרוכשים באמצעות Private Aggregation APIs.

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

• קוראים את מדריך ה-API: מידע על דיווח למוכרים ולקונים

8. מדווח על קליק על מודעה

המערכת מדווחת על קליק על מודעה שמוצגת ב-fenced frame. מידע נוסף על האופן שבו זה עשוי לפעול זמין במאמר דיווח על מודעות ב-Fenced Frames.

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

‫Protected Audience API הוא הניסוי הראשון שמיושם ב-Chromium במסגרת סדרת ההצעות של TURTLEDOVE.

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

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

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

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

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

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

האם אפשר להשתמש ב-Topics API עם Protected Audience API?

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

• ‫auctionSignals, מאפיין של אובייקט ההגדרות של המכירה הפומבית שמועבר אל navigator.runAdAuction()
• ‫userBiddingSignals, מאפיין של אובייקט ההגדרה של קבוצת הנושאים שמועבר אל navigator.joinAdInterestGroup()

הגדרות הדפדפן שזמינות

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

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

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

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

האם הדפדפן שומר במטמון את ה-worklet של Protected Audience?

הדפדפן שומר במטמון את המשאבים שמכילים את ה-worklets של Protected Audience – ה-worklets של הקונה ליצירת הצעות מחיר ודיווח, וה-worklets של המוכר לדירוג מודעות ודיווח. אפשר להשתמש בכותרת Cache-Control כדי לשלוט בהתנהגות של שמירת נתונים במטמון.

השתתפות ושיתוף משוב

קבלת תמיכה

כדי לשאול שאלות ולקבל תמיכה בהטמעה, בהדגמה או במסמכים:

• ‫GitHub: אפשר לקרוא את ההסבר, לשאול שאלות ולעקוב אחרי הדיון.
• הדגמה: אפשר לפתוח בעיה במאגר קוד ההדגמה.
• הטמעה ב-Chrome: אם יש באגים או בעיות בהטמעה של Protected Audience API ב-Chrome, אפשר לראות בעיות קיימות או לדווח על בעיה חדשה.

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

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

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

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

שלחו לי עדכונים

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