יצירת אינדקס של הדפים שיכולים להיות במצב אופליין באמצעות ממשק ה-API להוספת תוכן לאינדקס

איך מאפשרים לשירותי העבודה לומר לדפדפנים אילו דפים פועלים במצב אופליין

מהו Content Indexing API?

כשמשתמשים באפליקציית אינטרנט מתקדמת, יש גישה למידע שחשוב לאנשים – תמונות, סרטונים, כתבות ועוד – ללא קשר למצב הנוכחי של חיבור הרשת. טכנולוגיות כמו service workers,‏ Cache Storage API ו-IndexedDB מספקות את אבני הבניין לאחסון ולצגת נתונים כשאנשים מקיימים אינטראקציה ישירה עם אפליקציית PWA. אבל פיתוח אפליקציית PWA איכותית שמתמקדת בעבודה אופליין היא רק חלק מהסיפור. אם אנשים לא מבינים שהתוכן של אפליקציית אינטרנט זמין בזמן שהם במצב אופליין, הם לא יפיקו את המרב מהעבודה שהשקעתם בהטמעת הפונקציונליות הזו.

זוהי בעיית גילוי: איך אפשר להציג למשתמשים את התוכן של האפליקציה לניהול עסקים באינטרנט שזמין במצב אופליין, כדי שהם יוכלו לגלות ולצפות בתוכן שזמין? Content Indexing API הוא פתרון לבעיה הזו. החלק של הפתרון הזה שמיועד למפתחים הוא תוסף ל-service workers, שמאפשר למפתחים להוסיף כתובות URL ומטא-נתונים של דפים שפועלים במצב אופליין לאינדקס מקומי שמנוהל על ידי הדפדפן. השיפור הזה זמין ב-Chrome מגרסה 84 ואילך.

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

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

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

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

ראו הדגמה

הדרך הטובה ביותר להבין את Content Indexing API היא לנסות אפליקציה לדוגמה.

  1. מוודאים שאתם משתמשים בדפדפן ובפלטפורמה נתמכים. נכון לעכשיו, התכונה מוגבלת ל-Chrome 84 ואילך ב-Android. אפשר להיכנס אל about://version כדי לראות איזו גרסה של Chrome מותקנת.
  2. נכנסים אל https://contentindex.dev
  3. לוחצים על הלחצן + לצד פריט אחד או יותר ברשימה.
  4. (אופציונלי) משביתים את ה-Wi-Fi ואת חיבור הנתונים הסלולריים במכשיר, או מפעילים את מצב הטיסה כדי לדמות מצב אופליין בדפדפן.
  5. בתפריט של Chrome, בוחרים באפשרות הורדות ומנווטים לכרטיסייה מאמרים בשבילך.
  6. עיינו בתוכן ששמרתם בעבר.

אפשר לראות את המקור של האפליקציה לדוגמה ב-GitHub.

אפליקציה לדוגמה נוספת, Scrapbook PWA, ממחישה את השימוש ב-Content Indexing API עם Web Share Target API. הקוד מדגים שיטה לשמירה על סנכרון של Content Indexing API עם פריטים שמאוחסנים באפליקציית אינטרנט באמצעות Cache Storage API.

שימוש ב-API

כדי להשתמש ב-API, באפליקציה צריך להיות שירות עבודה (service worker) וכתובות URL שניתן לנווט בהן אופליין. אם לאפליקציית האינטרנט שלכם אין כרגע עובד שירות, תוכלו להיעזר בספריות Workbox כדי ליצור עובד שירות בקלות.

אילו סוגים של כתובות URL אפשר להוסיף לאינדקס ככאלה שזמינות אופליין?

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

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

אפליקציות אינטרנט יכולות להוסיף לאינדקס התוכן רק כתובות URL שנמצאות בהיקף של ה-service worker הנוכחי. במילים אחרות, אפליקציית אינטרנט לא יכלה להוסיף לאינדקס התוכן כתובת URL ששייכת לדומיין אחר לגמרי.

סקירה כללית

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

השלב הראשון בהוספת תוכן לאינדקס הוא קבלת הפניה ל-ServiceWorkerRegistration הנוכחי. הדרך הפשוטה ביותר היא להשתמש ב-navigator.serviceWorker.ready:

const registration = await navigator.serviceWorker.ready;

// Remember to feature-detect before using the API:
if ('index' in registration) {
 
// Your Content Indexing API code goes here!
}

אם אתם מבצעים קריאות ל-Content Indexing API מתוך service worker, ולא מתוך דף אינטרנט, תוכלו להפנות ל-ServiceWorkerRegistration ישירות דרך registration. הוא כבר מוגדר כחלק מ-ServiceWorkerGlobalScope.

הוספה לאינדקס

משתמשים ב-method‏ add() כדי להוסיף לאינדקס כתובות URL ואת המטא-נתונים המשויכים אליהן. אתם אלה שקובעים מתי פריטים יתווספו לאינדקס. יכול להיות שתרצו להוסיף לאינדקס בתגובה להזנה, למשל לחיצה על הלחצן 'שמירה במצב אופליין'. לחלופין, תוכלו להוסיף פריטים באופן אוטומטי בכל פעם שנתונים שנשמרו במטמון מתעדכנים באמצעות מנגנון כמו סנכרון תקופתי ברקע.

await registration.index.add({
 
// Required; set to something unique within your web app.
  id
: 'article-123',

 
// Required; url needs to be an offline-capable HTML page.
  url
: '/articles/123',

 
// Required; used in user-visible lists of content.
  title
: 'Article title',

 
// Required; used in user-visible lists of content.
  description
: 'Amazing article about things!',

 
// Required; used in user-visible lists of content.
  icons
: [{
    src
: '/img/article-123.png',
    sizes
: '64x64',
    type
: 'image/png',
 
}],

 
// Optional; valid categories are currently:
 
// 'homepage', 'article', 'video', 'audio', or '' (default).
  category
: 'article',
});

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

אותיות רישיות: add() מההקשר של window אם הסמלים מסתמכים על handler של fetch

כשמפעילים את add(), Chrome שולח בקשה לכתובת ה-URL של כל סמל כדי לוודא שיש לו עותק של הסמל לשימוש כשמציגים רשימה של תוכן שנוסף לאינדקס.

  • אם קוראים ל-add() מההקשר window (כלומר, מדף האינטרנט), הבקשה הזו תפעיל אירוע fetch ב-service worker.

  • אם קוראים לפונקציה add() בתוך קובץ השירות (אולי בתוך גורם אחר לטיפול באירועים), הבקשה לא תפעיל את הטיפול באירועים fetch של קובץ השירות. האיקונים יאוחזו ישירות, ללא מעורבות של שירות העבודה. חשוב לזכור את זה אם הסמלים מסתמכים על ה-handler של fetch, אולי כי הם קיימים רק במטמון המקומי ולא ברשת. אם כן, חשוב לוודא שמפעילים את add() רק מההקשר window.

הצגת תוכן האינדקס

ה-method getAll() מחזירה הבטחה לרשימה קבועה של רשומות שנוספו לאינדקס ולמטא-נתונים שלהן. הרשומות המוחזרות יכילו את כל הנתונים שנשמרו באמצעות add().

const entries = await registration.index.getAll();
for (const entry of entries) {
 
// entry.id, entry.launchUrl, etc. are all exposed.
}

הסרת פריטים מהאינדקס

כדי להסיר פריט מהאינדקס, קוראים ל-delete() עם ה-id של הפריט שרוצים להסיר:

await registration.index.delete('article-123');

קריאה ל-delete() משפיעה רק על האינדקס. הפעולה הזו לא מוחקת שום דבר מהמטמון.

טיפול באירוע מחיקה של משתמש

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

האפשרות 'מחיקה' בתפריט.

כשמישהו בוחר באפשרות הזו בתפריט, ה-Service Worker של אפליקציית האינטרנט יקבל אירוע contentdelete. הטיפול באירוע הוא אופציונלי, אבל הוא מאפשר ל-Service Worker "לנקות" תוכן, כמו קובצי מדיה ששמורים במטמון מקומי, שמישהו ציין שהוא סיים לעבוד איתו.

אין צורך לבצע קריאה ל-registration.index.delete() בתוך הטיפול contentdelete. אם האירוע הופעל, הדפדפן כבר ביצע את המחיקה הרלוונטית של האינדקס.

self.addEventListener('contentdelete', (event) => {
 
// event.id will correspond to the id value used
 
// when the indexed content was added.
 
// Use that value to determine what content, if any,
 
// to delete from wherever your app stores it—usually
 
// the Cache Storage API or perhaps IndexedDB.
});

משוב על עיצוב ה-API

האם יש משהו ב-API שקשה להשתמש בו או שהוא לא פועל כצפוי? או שחסרים חלקים שצריך כדי ליישם את הרעיון?

אפשר לשלוח דיווח על בעיה במאגר ה-GitHub של ההסבר על Content Indexing API או להוסיף את המחשבות שלכם לבעיה קיימת.

נתקלתם בבעיה בהטמעה?

מצאתם באג בהטמעה של Chrome?

שולחים דיווח על באג בכתובת https://new.crbug.com. מוסיפים כמה שיותר פרטים, הוראות פשוטות לשחזור הבעיה ומגדירים את Components לערך Blink>ContentIndexing.

מתכננים להשתמש ב-API?

מתכננים להשתמש ב-Content Indexing API באפליקציית האינטרנט שלכם? התמיכה הציבורית שלכם עוזרת לנו לקבוע את סדר העדיפויות של התכונות ב-Chrome, ומראה ליצרני דפדפנים אחרים כמה חשובה התמיכה בהן.

מהן ההשלכות של הוספת תוכן לאינדקס על האבטחה והפרטיות?

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

התמונה הראשית (Hero) היא של Maksym Kaharlytskyi ב-Unsplash.