למדו כיצד לעבוד עם ה-API, כולל כיצד להשתמש בדגלים של Chrome לצורך בדיקות.
סטטוס הטמעה
- Topics API השלים את שלב הדיון הציבורי והוא זמין כרגע ל-99% מהמשתמשים, עד 100 אחוזים.
- כדי לשלוח משוב על Topics API, אפשר ליצור בעיה בהסבר של Topics או להשתתף בדיונים ב-שיפור הקבוצה העסקית של הפרסום באינטרנט. הסבר מכיל מספר שאלות פתוחות שעדיין מחייבות הגדרה נוספת.
- לוח הזמנים של ארגז החול לפרטיות מספק לוחות זמנים להטמעה של Topics API והצעות אחרות של ארגז החול לפרטיות.
- ב-Topics API: העדכונים האחרונים מפורטים השינויים והשיפורים ב-Topics API ובהטמעות.
הפעל את ההדגמה
יש שתי הדגמות של Topics API שמאפשרות לנסות את Topics API כמשתמש יחיד.
- הדגמה של JavaScript API: topics-demo.glitch.me.
- הדגמה של כותרת: topics-fetch-demo.glitch.me
אפשר גם להריץ את colab של Topics כדי לנסות את מודל הסיווג של נושאים.
שימוש ב-JavaScript API כדי לגשת לנושאים ולתעד אותם כפי שזוהו
ל-Topics JavaScript API יש שיטה אחת: document.browsingTopics()
. יש לכך שתי מטרות:
- אומרים לדפדפן לתעד את הביקור הנוכחי בדף ככזה שנצפה עבור המתקשר, כך שאפשר יהיה להשתמש בתכונה הזו מאוחר יותר לחישוב נושאים עבור המשתמש (עבור המתקשר).
- גישה לנושאים עבור המשתמש שזוהו על ידי המתקשר/ת.
השיטה מחזירה הבטחה שמתחילה במערך של עד שלושה נושאים, אחד לכל אחד משלושת התקופות האחרונות, בסדר אקראי. תקופה של זמן מערכת (epoch) היא תקופה שמוגדרת לשבוע אחד בהטמעה של Chrome.
לכל אובייקט נושא במערך שמוחזר על ידי document.browsingTopics()
יש את המאפיינים הבאים:
configVersion
: מחרוזת המזהה את ההגדרה הנוכחית של Topics API, לדוגמהchrome.2
modelVersion
: מחרוזת שמזהה את המסווג של למידת המכונה שמשמש להסקת נושאים לאתר, לדוגמה4
taxonomyVersion
: מחרוזת המזהה את קבוצת הנושאים שבהם משתמש הדפדפן, לדוגמה2
topic
: מספר המזהה את הנושא בטקסונומיה, לדוגמה309
version
: מחרוזת המשרשרת אתconfigVersion
,taxonomyVersion
ו-modelVersion
, לדוגמהchrome.2:2:4
הפרמטרים המתוארים במדריך הזה ופרטי ה-API (כגון גודל הטקסונומיה, מספר הנושאים המחושבים בשבוע ומספר הנושאים המוחזרים בכל קריאה) כפופים לשינויים בזמן שאנחנו משלבים משוב על הסביבה העסקית וחוזרים עליה ב-API.
זיהוי תמיכה ב-document.browsingTopics
לפני השימוש ב-API, יש לבדוק אם הוא נתמך על ידי הדפדפן וזמין במסמך:
'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
console.log('document.browsingTopics() is supported on this page') :
console.log('document.browsingTopics() is not supported on this page');
גישה לנושאים באמצעות ממשק ה-API של JavaScript
הנה דוגמה בסיסית לשימוש אפשרי ב-API כדי לגשת לנושאים עבור המשתמש הנוכחי.
try {
// Get the array of top topics for this user.
const topics = await document.browsingTopics();
// Request an ad creative, providing topics information.
const response = await fetch('https://ads.example/get-creative', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(topics)
})
// Get the JSON from the response.
const creative = await response.json();
// Display ad.
} catch (error) {
// Handle error.
}
גישה לנושאים בלי לשנות את המצב
ה��ונקציה document.browsingTopics()
מחזירה נושאים שזוהו על ידי המתקשר/ת אצל המשתמש הנוכחי. כברירת מחדל, השיטה גם גורמת לדפדפן לתעד את הביקור הנוכחי בדף כפי שנקבע על ידי המתקשר, כך שניתן להשתמש בו מאוחר יותר בחישוב הנושאים. בגרסה 108 של Chrome, ניתן להעביר את השיטה כארגומנט אופציונלי לדילוג על התיעוד של הביקור בדף: {skipObservation:true}
.
במילים אחרות, המשמעות של {skipObservation:true}
היא שקריאת השיטה לא תגרום לכך שהדף הנוכחי ייכלל בחישוב של הנושאים.
שימוש בכותרות כדי לגשת לנושאים ולסמן אותם כ'נצפו'
בעזרת כותרות בקשות ותגובות אפשר לגשת לנושאים ולסמן ביקורים בדף כמתועדים.
שימוש בגישת הכותרת יכול להיות הרבה יותר יעיל משימוש ב-JavaScript API, כי ה-API מחייב ליצור iframe ממקורות שונים ולבצע ממנו קריאה ל-document.browsingTopics()
. (יש להשתמש ב-iframe חוצה-מקורות עבור הקריאה, מאחר שנעשה שימוש בהקשר שממנו מופעל ה-API על מנת להבטיח שהדפדפן מחזיר את הנושאים המתאימים למבצע הקריאה). בהסבר של 'נושאים' יש דיון נוסף: האם יש דרך לשלוח נושאים באמצעות 'אחזור ככותרת בקשה'? .
אפשר לגשת לנושאים מהכותרת Sec-Browsing-Topics
של בקשת fetch()
או XHR
.
אם מגדירים כותרת Observe-Browsing-Topics: ?1
בתגובה לבקשה, הדפדפן יתעד את הביקור הנוכחי בדף כפי שזוהה מבצע הקריאה החוזרת, כך שאפשר יהיה להשתמש בו מאוחר יותר בחישוב הנושאים.
אפשר לגשת לנושאים ולראות אותם באמצעות כותרות HTTP בשתי דרכים:
fetch()
: מוסיפים את{browsingTopics: true}
לפרמטר האפשרויות של בקשה שלfetch()
. הדגמת כותרת הנושאים מציגה דוגמה פשוטה לכך.- מאפיין iframe: מוסיפים את המאפיין
browsingtopics
לרכיב<iframe>
, או מגדירים את מאפיין ה-JavaScript המקבילiframe.browsingTopics = true
. הדומיין שניתן לרשום של מקור ה-iframe הוא דומיין מבצע הקריאה. לדוגמה, עבור<iframe src="https://example.com" browsingtopics></iframe>
: מבצע הקריאה הואexample.com
.
כמה הערות נוספות לגבי כותרות:
- תתבצע מעקב אחר הפניות אוטומטיות, והנושאים שיישלחו בבקשה להפניה אוטומטית יהיו ספציפיים לכתובת ה-URL להפניה אוטומטית.
- מצב כותרת הבקשה לא ישתנה אצל מבצע הקריאה החוזרת, אלא אם יש כותרת תגובה תואמת. כלומר, ללא כותרת התגובה, הביקור בדף לא יתועד כפי שנמדד ולכן הוא לא ישפיע על חישוב הנושא של המשתמש בתקופה הבאה.
- כותרת התגובה תקפה רק אם הבקשה המתאימה כללה את כותרת הנושאים.
- בכתובת ה-URL של הבקשה מצוין הדומיין שניתן לרשום שמתועד כדומיין של מבצע הקריאה.
ניפוי באגים בהטמעת ה-API
הדף chrome://topics-internals
יהיה זמין ב-Chrome במחשב אחרי הפעלת Topics API. בדוח מוצגים נושאים למשתמש הנוכחי, נושאים שהסקנו לגבי שמות המארחים ומידע טכני לגבי הטמעת ה-API. אנחנו חוזרים על עיצוב הדף ומשפרים אותו על סמך משוב ממפתחים: אפשר להוסיף את המשוב בכתובת bugs.chromium.org.
הצגת נושאים שמחושבים לדפדפן שלך
chrome://topics-internals
יכול להציג מידע על נושאים שנצפו בדפדפן שלהם בתקופה הנוכחית ובתקופות קודמות.
בצילום המסך הזה ניתן לראות שהאתרים שביקרת בהם לאחרונה כוללים את topics-demo-cats.glitch.me
ואת cats-cats-cats-cats.glitch.me
. הסיבה לכך היא ש-Topics API בוחר ב-Pets
וב-Cats
כשני הנושאים המובילים בתקופה הנוכחית. שלושת הנושאים הנותרים נבחרו באופן אקראי, מפני שאין מספיק היסטוריית גלישה (באתרים שבודקים נושאים) כדי לספק חמישה נושאים.
העמודה דומייני�� של הקשר שנצפו (מגובבים) מספקת את הערך המגובב של שם מארח שעבורו הנושא זוהה.
הצגת הנושאים שהמערכת מסיקה עבור שמות מארחים
ניתן גם להציג את הנושאים שהמערכת מסיקה ממודל הסיווג של הנושאים עבור שם מארח אחד או יותר ב-chrome://topics-internals
.
היישום הנוכחי של Topics API מסיק נושאים משמות מארחים בלבד, ולא מחלקים אחרים של כתובת URL.
אפשר להשתמש בשמות מארחים בלבד (ללא פרוטוקול או נתיב) כדי להציג נושאים שהוסקו מהמסווג chrome://topics-internals
. אם תנסו לכלול "/" בשדה 'מארח', תוצג לכם שגיאה ב-chrome://topics-internals
.
הצגת מידע של Topics API
ניתן למצוא מידע על ההטמעה וההגדרות של Topics API, כמו גרסת הטקסונומיה ומשך התקופה של זמן מערכת (epoch), ב-chrome://topics-internals
. הערכים האלה משקפים את הגדרות ברירת המחדל של ה-API או את הפרמטרים שהוגדרו בהצלחה משורת הפקודה. מומלץ להיעזר במידע הזה כדי לוודא שסימונים בשורת הפקודה פעלו כמצופה.
בדוגמה, time_period_per_epoch
הוגדר כ-15 שניות (ברירת המחדל היא 7 ימים).
הפרמטרים שמוצגים בצילום המסך תואמים לסימונים שניתן להגדיר כשמפעילים את Chrome משורת הפקודה. לדוגמה, בהדגמה שבכתובת topics-fetch-demo.glitch.me מומלץ להשתמש בדגלים הבאים:
--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting
הרשימה הבאה מסבירה כל פרמטר, ערך ברירת המחדל שלו ומטרתו.
תכונות ניסיוניות ב-Chrome
BrowsingTopics
- ערך ברירת המחדל: מופעל
- האם Topics API מופעל.
PrivacySandboxAdsAPIsOverride
- ערך ברירת המחדל: מופעל
- הפעלת ממשקי API של מודעות: Attribution Reporting, Protected Audience, Topics, Fenced Frames.
PrivacySandboxSettings4
- ערך ברירת המחדל: מושבת
- הפעלת הגרסה הרביעית של הגדרות ממשק המשתמש של ארגז החול לפרטיות.
OverridePrivacySandboxSettingsLocalTesting
- ערך ברירת המחדל: מופעל
- אם האפשרות מופעלת, כבר לא צריך להפעיל בדפדפן את ההגדרות הבסיסיות כדי להפעיל את התכונות של ארגז החול לפרטיות.
BrowsingTopicsBypassIPIsPubliclyRoutableCheck
- ערך ברירת המחדל: מושבת
- אם המדיניות מופעלת, המערכת תעקוף את הבדיקה כדי לקבוע אם כתובת ה-IP ניתנת לניתוב באופן ציבורי, כשקובעים את הכשירות של דף להיכלל בחישוב הנושאים.
BrowsingTopics:number_of_epochs_to_expose
- ערך ברירת המחדל: 3
- מספר התקופות שבמהלכן יש לחשב את הנושאים שיש לספק להקשר המבוקש. הדפדפן ישמור באופן פנימי עד תקופות זמן של N+1.
BrowsingTopics:time_period_per_epoch
- ערך ברירת המחדל: 7d-0h-0m-0s
- משך זמן של כל תקופה של זמן מערכת. לצורך ניפוי באגים, כדאי להגדיר את משך הזמן הזה (למשל) 15 שניות, במקום ברירת המחדל של 7 ימים.
BrowsingTopics:number_of_top_topics_per_epoch
- ערך ברירת מחדל: 5
- מספר הנושאים המחושבים בכל תקופה של זמן מערכת.
BrowsingTopics:use_random_topic_probability_percent
- ערך ברירת המחדל: 5
- ההסתברות שנושא מסוים בתקופת זמן מסוימת מוחזר באופן אקראי מכל הטקסונומיה של הנושאים. הרנדומיזציה נשארת למשך תקופה של זמן מערכת ואתר.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
- ערך ברירת המחדל: 3
- כמה תקופות של זמן מערכת של נתוני שימוש ב-API (כלומר תצפיות על נושאים) ישמשו לסינון הנושאים לפי הקשר קריאה.
BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
- ערך ברירת המחדל: 1,000
- המספר המקסימלי של דומיינים המתועדים לפי הקשר שיש לשמור בכל נושא ראשי. הכוונה היא להגביל את הזיכרון בשימוש.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
- ערך ברירת המחדל: 100000
- המספר המקסימלי של רשומות שאפשר לאחזר ממסד הנתונים לכל שאילתה, בהקשרים של שימוש ב-API. השאילתה תתבצע פעם אחת בכל תקופה של זמן מערכת בזמן חישוב הנושאים. הכוונה היא להגביל את השימוש בזיכרון.
BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
- ערך ברירת המחדל: 30
- המספר המקסימלי של דומיינים בהקשר של שימוש ב-API שניתן לאחסן בכל טעינת דף.
BrowsingTopics:config_version
- ערך ברירת המחדל: 1
- מקודד את הפרמטרים של הגדרת Topics API. יש למפות כל מספר גרסה לקבוצת הגדרות אישיות אחת בלבד. עדכון הפרמטרים של ההגדרות בלי לעדכן את
config_version
בדרך כלל מתאים לבדיקה מקומית, אבל במצבים מסוימים יכול להיות שהדפדפן יישאר במצב ל�� עקבי ולגרום לקריסת הדפדפן, למשל עדכון שלnumber_of_top_topics_per_epoch
. BrowsingTopics:taxonomy_version
- ערך ברירת המחדל: 1
- גרסת הטקסונומיה שבה נעשה שימוש ב-API.
ביטול ההצטרפות לאתר
כדי לבטל את ההסכמה לחישוב נושאים ��דפ��ם ��פ��י��י��ם ��א��ר, א��שר ל��לול בדף את הכותרת Permissions-Policy: browsing-topics=()
Permissions-Policy. כך המערכת לא תחשב את הנושאים שרלוונטיים לכל המשתמשים בדף הזה בלבד. הביקורים הבאים בדפים אחרים באתר לא יושפעו: אם מגדירים מדיניות לחסימת Topics API בדף אחד, לא תהיה לכך השפעה על דפים אחרים.
כדי לקבוע לאילו צדדים שלישיים תהיה גישה לנושאים בדף שלכם, אתם יכולים להשתמש בכותרת Permissions-Policy
כדי לשלוט בגישה של צדדים שלישיים ל-Topics API. כפרמטרים לכותרת, צריך להשתמש ב-self
ובכל דומיין שרוצים להעניק לו גישה ל-API. לדוגמה, כדי להשבית לחלוטין את השימוש ב-Topics API בכל הקשרי הגלישה מלבד המקור שלכם ו-https://example.com
, צריך להגדיר את כותרת תגובת ה-HTTP הבאה:
Permissions-Policy: browsing-topics=(self "https://example.com")
השלבים הבאים
- למידע נוסף על נושאים ועל איך הם עובדים
- כדאי לנסות את ההדגמה.
מידע נוסף
עניין ושיתוף משוב
- GitHub: קוראים את ההסבר של Topics API, ומעלים שאלות ועוקבים אחרי דיונים בבעיות במאגר ה-API.
- W3C: דיון על מקרי שימוש בתחום בשיפור הקבוצה העסקית של הפרסום באינטרנט.
- הודעות: הצטרפות לרשימת התפוצה או הצגה של רשימת התפוצה
- תמיכה למפתחים של ארגז חול לפרטיות: אפשר לשאול שאלות ולהצטרף לדיונים על מאגר התמיכה למפתחים של ארגז החול לפרטיות.
- Chromium: דיווח על באג ב-Chromium כדי לשאול שאלות לגבי ההטמעה שזמינה כרגע לבדיקה ב-Chrome.