הטמעת Topics API

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

צפייה בנושאים וגישה אליהם

יש שתי דרכים לזהות נושאים בתחומי העניין של המשתמשים ולגשת אליהם: כותרות HTTP ו-JavaScript API.

כותרות HTTP

מומלץ להשתמש בכותרות HTTP כדי לצפות בנושאים של משתמשים ולגשת אליהם. הגישה הזו יכולה להיות יעילה יותר בהרבה מהשימוש ב-JavaScript API. בכותרות HTTP, כתובת ה-URL של הבקשה מספקת את הדומיין שניתן לרישום שנרשם כדומיין של המתקשר. זהו הדומיין שנראה שצפה בנושאים של המשתמש.

שליחת בקשה

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

• על ידי גישה לכותרות של בקשות ותגובות בבקשת fetch() שכוללת אפשרות browsingTopics: true.
• על ידי גישה לכותרות של אלמנט iframe שכולל מאפיין browsingtopics.

שליחת בקשה באמצעות אחזור

באמצעות fetch, המתקשר ל-API שולח בקשה שכוללת את {browsingTopics: true} בפרמטר האפשרויות. המקור של פרמטר כתובת ה-URL של בקשת האחזור הוא המקור שזוהה כמי שצפה בנושאים.

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });

שליחת בקשה באמצעות iframe

מוסיפים את המאפיין browsingtopics לרכיב <iframe>. הדפדפן יכלול את הכותרת Sec-Browsing-Topics בבקשה של ה-iframe, עם המקור של ה-iframe בתור המתקשר.

   <iframe src="https://adtech.example" browsingtopics></iframe>

הסבר על הערכים של כותרות הבקשות

בשתי הגישות (fetch ו-iframe) אפשר לאחזר את הנושאים שנצפו אצל משתמש בשרת מכותרת הבקשה Sec-Browsing-Topics. ‫Topics API יכלול אוטומטית נושאים שמעניינים את המשתמש בכותרת בבקשת fetch() או בבקשת iframe. אם ה-API מחזיר נושא אחד או יותר, בקשת אחזור למקור שממנו נצפו הנושאים תכלול כותרת Sec-Browsing-Topics כמו זו:

   (325);v=chrome.1:1:1, ();p=P000000000

אם ה-API לא מחזיר נושאים, הכותרת תיראה כך:

   ();p=P0000000000000000000000000000000

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

טיפול בתגובה בצד השרת

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

   res.setHeader('Observe-Browsing-Topics', '?1');

שיתוף נושאים שנצפו עם שותפים

מכיוון שפלטפורמות SSP פועלות רק בצד של בעל התוכן הדיגיטלי, פלטפורמות DSP יכולות לשתף עם פלטפורמות ה-SSP השותפות שלהן נושאים שהן מזהות באתרים של המפרסם. כדי לעשות זאת, הם יכולים לשלוח בקשת fetch() עם כותרת הנושאים אל פלטפורמות ה-SSP מההקשר ברמה העליונה של המפרסם.

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

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

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

מומלץ ליצור Fork של הדמו של Topics API ב-JavaScript ולהשתמש בו כנקודת התחלה לקוד.

זמינות API

לפני שמשתמשים ב-API, צריך לוודא שהוא נתמך וזמין:

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

הטמעה של iframe

צריך להשתמש ב-iframe חוצה מקורות לקריאה, כי ההקשר שממנו מופעל ה-API משמש כדי לוודא שהדפדפן מחזיר את הנושאים שמתאימים לגורם ששלח את הקריאה. כוללים רכיב <iframe> בקוד ה-HTML:

<iframe src="https://example.com" browsingtopics></iframe>

אפשר גם ליצור iframe באופן דינמי באמצעות JavaScript:

 const iframe = document.createElement('iframe');
 iframe.setAttribute('src', 'https://adtech.example/');
 document.body.appendChild(iframe);

קריאה ל-API מתוך מסגרת iframe

 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() גורמת גם לדפדפן לתעד את הביקור הנוכחי בדף כפי שנצפה על ידי המתקשר, כדי שאפשר יהיה להשתמש בו מאוחר יותר בחישוב הנושאים. אפשר להעביר לשיטה ארגומנט אופציונלי כדי לדלג על תיעוד הביקור בדף: {skipObservation:true}.

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

הסבר על התשובה

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

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]

• ‫configVersion: מחרוזת שמזהה את גרסת ההגדרה של אלגוריתם הנושאים בדפדפן.
• ‫modelVersion: מחרוזת שמזהה את המסווג של למידת המכונה ששימש להסקת נושאים.
• ‫taxonomyVersion: מחרוזת שמזהה את קבוצת הנושאים שנמצאת בשימוש בדפדפן.
• ‫topic: מספר שמזהה את הנושא בטקסונומיה.
• ‫version: מחרוזת שנוצרת משרשור של configVersion, ‏taxonomyVersion ו-modelVersion. הפרמטרים שמתוארים במדריך הזה, ופרטים על ה-API (כמו גודל הטקסונומיה, מספר הנושאים שמחושבים בכל שבוע ומספר הנושאים שמוחזרים בכל קריאה) עשויים להשתנות ככל שאנחנו משלבים משוב מהמערכת האקולוגית ומשפרים את ה-API.

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

השלבים הבאים

בדיקה והפעלה

איך פורסים, בודקים ומתאימים לעומס פתרונות שמבוססים על Topics

כלים

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

ראה גם

כדאי לעיין במקורות המידע שלנו כדי להבין טוב יותר את Topics API באינטרנט.

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