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

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

סטטוס ההטמעה

נסה את ההדגמה

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

אתם יכולים גם להריץ את Colab של Topics כדי לנסות את מודל הסיווג של 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');

גישה לנושאים באמצעות JavaScript API

הנה דוגמה בסיסית לשימוש אפשרי ב-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} היא שהקריאה לשיטה לא תגרום לדף הנוכחי להיכלל בחישוב של נושאים.

ניתן להשתמש בכותרות כדי לגשת לנושאים ולסמן אותם כנושאים שנצפו

אפשר לגשת לנושאים, וגם לסמן ביקורים בדף כביקורים מתועדים, בעזרת request וגם כותרות response.

שימוש בגישה לכותרת יכול להניב ביצועים הרבה יותר טובים משימוש ב-API של JavaScript, כי ה-API מחייב יצירת iframe ממקורות שונים וביצוע קריאת document.browsingTopics() ממנו. (יש להשתמש ב-iframe ממקורות שונים עבור הקריאה, מפני שההקשר שממנו מופעל ה-API משמש כדי להבטיח שהדפדפן יחזיר את הנושאים המתאימים למתקשר). בהסבר על Topics API יש דיון נוסף: האם יש דרך לשלוח נושאים באמצעות כותרת הבקשה של 'אחזור'? .

ניתן לגשת לנושאים מהכותרת Sec-Browsing-Topics של בקשה ב-fetch() או ב-XHR.

הגדרת כותרת Observe-Browsing-Topics: ?1 בתשובה לבקשה גורמת לדפדפן להקליט את הביקור הנוכחי בדף כפי שנצפה על ידי המתקשר, כך שניתן יהיה להשתמש בה מאוחר יותר בחישוב נושאים.

אפשר לגשת לנושאים ולצפות בהם באמצעות כותרות HTTP בשתי דרכים:

  • fetch(): הוספה של {browsingTopics: true} לפרמטר האפשרויות של בקשת fetch(). הדגמה של הכותרת של Topics מציגה דוגמה פשוטה לכך.
  • מאפיין 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.

הצגת נושאים שחושבו לדפדפן שלך

המשתמשים יכולים לראות מידע על נושאים שנצפו בדפדפן שלהם בתקופת הזמן הנוכחית ובתקופת הזמן הקודמת (epoch) באמצעות צפייה ב-chrome://topics-internals.

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

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

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

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

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

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

ההטמעה הנוכחית של Topics API מסיקה נושאים משמות מארחים בלבד; לא מחלק אחר של כתובת URL.

אפשר להשתמש בשמות מארחים בלבד (ללא פרוטוקול או נתיב) כדי לראות נושאים שהמערכת מפיקה מהסיווג של chrome://topics-internals. chrome://topics-internals יציג שגיאה אם תנסה לכלול "/" בשדה 'מארח'.

הצגת מידע על Topics API

בchrome://topics-internals אפשר למצוא מידע על ההטמעה וההגדרות של Topics API, כמו גרסת הטקסונומיה ומשך התקופה של תקופת הזמן (epoch). הערכים האלה משקפים את הגדרות ברירת המחדל של ה-API או הפרמטרים שהוגדרו בהצלחה משורת הפקודה. האפשרות הזו יכולה לעזור כדי לאשר שסימונים של שורת הפקודה פועלים כצפוי.

בדוגמה, הערך של time_period_per_epoch הוגדר ל-15 שניות (ברירת המחדל היא 7 ימים).

הדף chrome://topics-internals שבו נבחרה החלונית &#39;תכונות ופרמטרים&#39;.
החלונית chrome://topics-internals features and Parameters (תכונות ופרמטרים) מציגה תכונות מופעלות, זמן לכל תקופה, מספר תקופות זמן של שימוש לחישוב נושאים, גרסת טקסונומיה והגדרות אחרות.

הפרמטרים שמוצגים בצילום המסך תואמים לסימונים שאפשר להגדיר כשמריצים את 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
ערך ברירת המחדל: מופעל
הפעלת ממשקי Ads API: דוחות שיוך (Attribution), 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
ערך ברירת המחדל: 100,000
מספר הרשומות המקסימלי שמותר לאחזר ממסד הנתונים לכל שאילתה להקשרים של השימוש ב-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")

השלבים הבאים

למידע נוסף

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