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

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

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

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

סטטוס הטמעה

• The Protected Audience API proposal is now moving to general availability. Raise questions and follow discussion.
• Protected Audience API status of pending capabilities details changes and enhancements to the Protected Audience API API and features.
• Blink status
• Protected Audience API Chrome platform status: Specific to the Protected Audience API on Chrome.
• Ads API Chrome platform status: A collection of APIs to facilitate advertising: Protected Audience API, Topics, Fenced Frames and Attribution Reporting.

To be notified of status changes in the API, join the mailing list for developers.

מה זה 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 בטא 101.0.4951.26 ואילך ב- מחשב:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

מה ההבדל בין 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 כדי לשלוט בהתנהגות השמירה במטמון.

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

קבלת תמיכה

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

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

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

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

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

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

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

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