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

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

Jeff Posnick

מהו ה-API להוספת תוכן לאינדקס?

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

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

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

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

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

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

ראו הדגמה

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

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

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

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

שימוש ב-API

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

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

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

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

אפליקציות אינטרנט יכולות להוסיף כתובות 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!
}

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

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

משתמשים בשיטה 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() בתוך קובץ השירות (service worker), אולי בתוך handler אחר של אירועים, הבקשה לא תפעיל את ה-handler של fetch של ה-Service Worker. הסמלים יישלפו ישירות, ללא מעורבות של קובץ שירות (service worker). חשוב לזכור את זה אם הסמלים מסתמכים על ה-handler של fetch, אולי כי הם קיימים רק במטמון המקומי ולא ברשת. במקרה כזה, צריך להקפיד להפעיל את add() רק מההקשר של window.

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

השיטה 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() משפיעה רק על האינדקס. הוא לא מוחק שום דבר מהמטמון.

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

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

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

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

אין צורך להפעיל את registration.index.delete() בתוך ה-handler של 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 API של הוספת תוכן לאינדקס, או הוסיפו את דעתכם לבעיה קיימת.

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

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

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

מתכנן להשתמש ב-API?

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

  • ניתן לשלוח ציוץ לכתובת @ChromiumDev באמצעות ה-hashtag #ContentIndexingAPI ופרטים על המקום ואופן השימוש בו.

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

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

תמונה ראשית (Hero) של מקסים קהרליצקי ב-UnFlood.