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

bookmark_border קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

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

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

סטטוס ההטמעה

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

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

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

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

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

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

שירות Key/Value

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

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

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

לצורך הבדיקה הראשונית, הושק מודל Bring Your Own Server (BYOS). בטווח הארוך, טכנולוגיות הפרסום יצטרכו להשתמש בשירותי המפתח/הערך של 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

קבלת תמיכה

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

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

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

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

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

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

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

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