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

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

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

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

סטטוס הטמעה

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

מה זה Protected Audience API?

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

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

כדאי לנסות את Protected Audience API

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

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

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

הדגמה של Protected Audience API

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

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

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

תוכלו לבדוק את Protected Audience API למשתמש יחיד בגרסת Chrome בטא 101.0.4951.26 ואילך במחשב:

עיבוד מודעות ב-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 או בעל התוכן הדיגיטלי): על סמך הצעות מחיר במכרזים ומטא-נתונים מקונים.
  • רינדור המודעות בגרסה רגועה ורגועה של Fenced Frames: עיבוד המודעות מאפשר גישה לרשת ורישום ביומן.

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

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

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

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

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

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

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

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

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

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

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

לפני שמשתמשים ב-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. הדפדפן של המשתמש יתבקש להוסיף קבוצת תחומי עניין

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

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

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

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

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

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

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

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

עיינו בתיעוד למפתחים של generatedBid().

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

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

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

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

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

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

5. בית העסק והקונים המשתתפים מבקשים נתונים בזמן אמת מהשירות Key/Value

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

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

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

אדם צופה באתר חדשות בדפדפן במחשב נייד. מודעה ל-20% הנחה על אופניים מוצגת במסגרת מאובטחת ומגודרת.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

האם ה-worklets של Protected Audience נשמרו במטמון על ידי הדפדפן?

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

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

פנייה לתמיכה

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

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

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

הפסקת השימוש

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

קבלת עדכונים