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 לניפוי באגים.

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

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

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

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

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

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

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

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

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

קבלת תמיכה

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

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

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

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

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

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