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 באתרים של מפרסמים ובעלי תוכן דיגיטלי זמינה בכתובת copyright-audience-demo.web.app/.

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

בדיקת ה-API הזה

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

עיבוד מודעות במסגרות iframe או במסגרות מגודרות

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

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

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

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

כמנגנון דיווח זמני ברמת האירוע, הקוד שמטמיע את 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 ו-PARRROT של NextRoll תיארו את התפקידים השונים שהיו לקונים ולמוכרים במכרז במכשיר. תהליך הבידינג או תהליך הציון של Protected Audience API ב-Protected Audience API מבוססים על העבודה הזו.
  • השינויים מבוססי התוצאות וברמת המוצר ב-TURTLEDOVE של 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 על ידי הפעלה או השבתה של ההגדרה ברמה העליונה ב-chrome://settings/adPrivacy.

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

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

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

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

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

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

פנייה לתמיכה

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

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

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

הפסקת השימוש

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

קבלת עדכונים