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

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

Jeff Posnick

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

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

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

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

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

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

ה-Content Indexing API לא מהווה דרך חלופית לשמירת תוכן במטמון. זו דרך לספק מטא-נתונים על דפים שכבר נשמרו במטמון על ידי השירות עובד, כדי שהדפדפן יוכל להציג את הדפים האלה כאשר אנשים צפויים שרוצים לצפות בהן. 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 שניתן לנווט אליהן במצב אופליין. אם אין כרגע קובץ שירות (service worker) באפליקציית האינטרנט, אפשר להשתמש בספריות של תיבת העבודה כדי לפשט את ה אנחנו יוצרים תיעוד.

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

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

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

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

סקירה כללית

ה-Content Indexing 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.

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

משתמשים בשיטה 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). שמירה כדאי לזכור את זה אם הסמלים מסתמכים על ה-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 של הפריט כדי remove:

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 של הסבר על Content Indexing API או כותבים משוב לבעיה קיימת.

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

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

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

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

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

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

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

תמונה ראשית (Hero) של מקסימים קחרליצקי בסרטון Unbounce.