המדריך למפתחים של Topics API

למדו כיצד לעבוד עם ה-API, כולל כיצד להשתמש בדגלים של Chrome לצורך בדיקות.

סטטוס הטמעה

הפעל את ההדגמה

יש שתי הדגמות של Topics API שמאפשרות לנסות את Topics API כמשתמש יחיד.

אפשר גם להריץ את 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.

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

הדף chrome://topics-internals שבו נבחרה החלונית Topics State.
החלונית chrome://topics-internals page Topics State מציגה מזהי נושאים, הקצאות של נושאים אקראיות ואמיתיים, וכן גרסאות טקסונומיה וגרסאות מודלים.

בצילום המסך הזה ניתן לראות שהאתרים שביקרת בהם לאחרונה כוללים את topics-demo-cats.glitch.me ואת cats-cats-cats-cats.glitch.me. הסיבה לכך היא ש-Topics API בוחר ב-Pets וב-Cats כשני הנושאים המובילים בתקופה הנוכחית. שלושת הנושאים הנותרים נבחרו באופן אקראי, מפני שאין מספיק היסטוריית גלישה (באתרים שבודקים נושאים) כדי לספק חמישה נושאים.

העמודה דומיינים של הקשר שנצפו (מגובבים) מספקת את הערך המגובב של שם מארח שעבורו הנושא זוהה.

הצגת הנושאים שהמערכת מסיקה עבור שמות מארחים

ניתן גם להציג את הנושאים שהמערכת מסיקה ממודל הסיווג של הנושאים עבור שם מארח אחד או יותר ב-chrome://topics-internals.

הדף chrome://topics-internals כאשר נבחרה החלונית Classifier.
בחלונית הסיווג 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-internals עם החלונית &#39;תכונות ופרמטרים&#39; שנבחרה.
בחלונית chrome://topics-internals תכונות ופרמטרים מוצגות התכונות המופעלות, זמן לכל תקופה, מספר תקופות זמן שבהן ניתן להשתמש כדי לחשב נושאים, גרסת הטקסונומיה והגדרות אחרות.

הפרמטרים שמוצגים בצילום המסך תואמים לסימונים שניתן להגדיר כשמפעילים את 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")

השלבים הבאים

למידע נוסף

עניין ושיתוף משוב