فهرسة الصفحات التي يمكن الوصول إليها بلا اتصال بالإنترنت باستخدام Content Indexing API

تمكين موظفي الخدمات من إبلاغ المتصفحات بالصفحات التي تعمل بلا اتصال بالإنترنت

Jeff Posnick

ما هي Content Indexing API؟

استخدام تطبيق ويب تقدّمي يعني التمتع بإمكانية الوصول إلى المعلومات التي تهمّ المستخدمين، مثل الصور والفيديوهات والمقالات وغير ذلك، بغض النظر عن للحالة الحالية لاتصال الشبكة. وتكنولوجيات مثل عاملي الخدمات، ذاكرة التخزين المؤقت لواجهة برمجة التطبيقات، وIndexedDB بتزويدك بالكتل البرمجية الإنشائية لتخزين البيانات وعرضها عندما يستخدم الأشخاص للتفاعل مباشرة مع تطبيق الويب التقدّمي. مع ذلك، إنّ إنشاء تطبيق ويب تقدّمي (PWA) عالي الجودة وبلا اتصال بالإنترنت هو جزءًا فقط من القصة. إذا لم يدرك الناس أن محتوى تطبيق الويب أثناء عدم اتصالهم بالإنترنت، فلن يستفيدوا بشكل كامل من العمل الذي تقوم به وضعها في تنفيذ هذه الوظيفة.

في ما يتعلّق بمشكلة الاكتشاف، كيف يمكن لتطبيق الويب التقدّمي (PWA) أن يجعل المستخدمين على دراية محتوى يمكن تشغيله بلا اتصال بالإنترنت حتى يتمكنوا من اكتشاف المحتوى المتاح وعرضه؟ تشير رسالة الأشكال البيانية وتمثل واجهة برمجة التطبيقات لفهرسة المحتوى حلاً لهذه المشكلة. الجزء المخصّص للمطوّرين يُعد امتدادًا لموظفي الخدمة، مما يتيح للمطورين إضافة عناوين URL وبيانات وصفية للصفحات التي تتاح بلا اتصال بالإنترنت إلى فهرس محلي يتم الاحتفاظ به بواسطة المتصفح. يتوفّر هذا التحسين في الإصدار 84 من Chrome والإصدارات الأحدث.

بعد تعبئة الفهرس بمحتوى من تطبيق الويب التقدّمي (PWA)، بالإضافة إلى أي محتوى آخر تطبيقات الويب التقدّمية (PWA) المثبَّتة، ستظهر في المتصفّح كما هو موضّح أدناه.

لقطة شاشة لعنصر قائمة "عمليات التنزيل" في صفحة علامة التبويب الجديدة في Chrome.
أولاً، اختَر عنصر القائمة عمليات التنزيل في صفحة علامة التبويب الجديدة في Chrome.
الوسائط والمقالات التي تمت إضافتها إلى الفهرس.
سيتم عرض الوسائط والمقالات التي تمت إضافتها إلى الفهرس في مقالات مقترَحة لك.

بالإضافة إلى ذلك، يمكن لمتصفّح Chrome اقتراح محتوى بشكل استباقي عند اكتشاف المستخدم غير متصل بالإنترنت.

إنّ 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.

نموذج تطبيق آخر، وهو تطبيق الويب التقدّمي (PWA) الخاص بسجلّ القصاصات يوضّح استخدام واجهة Content Indexing API مع Web Share Target API. يوضح الرمز أسلوبًا للحفاظ على مزامنة واجهة برمجة التطبيقات للفهرسة للمحتوى مع العناصر المُخزَّنة بواسطة تطبيق ويب باستخدام cache Storage API.

استخدام واجهة برمجة التطبيقات

لاستخدام واجهة برمجة التطبيقات، يجب أن يتوفّر في تطبيقك مشغّل خدمات وعناوين URL يمكن التنقّل فيها. بلا اتصال بالإنترنت. إذا لم يكن تطبيق الويب يتضمّن مشغّل خدمات حاليًا، بإمكان مكتبات صندوق العمل تبسيط إنشاء واحدة.

ما هو نوع عناوين URL التي يمكن فهرستها كعناصر متوافقة مع وضع عدم الاتصال بالإنترنت؟

تتيح واجهة برمجة التطبيقات فهرسة عناوين URL المقابلة لمستندات HTML. عنوان URL لنسخة مخزّنة مؤقتًا ملف وسائط مباشرةً مثلاً. بدلاً من ذلك، تحتاج إلى تقديم عنوان URL لصفحة تعرض وسائط وتعمل بلا اتصال بالإنترنت.

النمط الموصى به هو إنشاء "عارض" صفحة HTML التي يمكنها قبول عنوان URL للوسائط الأساسية كمعلمة طلب البحث ثم يتم عرض محتوى من المحتمل أن يحتوي على عناصر تحكم إضافية أو محتوى إضافي على الصفحة.

ويمكن لتطبيقات الويب إضافة عناوين URL إلى فهرس المحتوى فقط ضمن النطاق لمشغّل الخدمات الحالي أو بعبارةٍ أخرى، لا يمكن لتطبيق ويب إضافة عنوان URL ينتمي إلى نطاق مختلف تمامًا في فهرس المحتوى.

نظرة عامة

تتيح واجهة برمجة التطبيقات لفهرسة المحتوى ثلاث عمليات: إضافة وإدراج إزالة بيانات التعريف. تظهر هاتان الطريقتان من خلال خاصية جديدة، index، تمت إضافته إلى ServiceWorkerRegistration من واجهة pyplot.

تتمثل الخطوة الأولى في فهرسة المحتوى في الحصول على إشارة إلى 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!
}

إذا كنت تجري اتصالات بواجهة برمجة تطبيقات فهرسة المحتوى من داخل مشغّل خدمات، بدلاً من أن تكون داخل صفحة ويب، يمكنك الرجوع إلى 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',
});

لا تؤثر إضافة إدخال إلا في فهرس المحتوى، فإنه لا يضيف أي شيء إلى cache.

حالة الحافة: يمكنك طلب add() من سياق window إذا كانت رموزك تعتمد على معالِج fetch.

عند الاتصال بـ add()، سيطلب Chrome من عنوان URL لكل أيقونة للتأكد من أنها تحتوي على نسخة من الرمز لاستخدامها عند من خلال عرض قائمة بالمحتوى المفهرَس

  • إذا كنت تستدعي add() من سياق window (بعبارة أخرى، من الويب الخاص بك) )، سيؤدي هذا الطلب إلى تشغيل حدث fetch على مشغّل الخدمات لديك.

  • عند الاتصال بـ add() داخل مشغّل الخدمات (ربما داخل حدث آخر) معالج البيانات)، لن يؤدي الطلب إلى تشغيل معالج fetch لعامل الخدمة. سيتم جلب الرموز مباشرةً، بدون أي تدخل من عاملي الخدمات. عدم الحذف يُرجى أخذ ذلك في الاعتبار إذا كانت رموزك تعتمد على معالِج 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() إلا في الفهرس. ولا يؤدي إلى حذف أي شيء من cache.

التعامل مع حدث حذف المستخدم

عندما يعرض المتصفّح المحتوى المفهرَس، قد يشمل ذلك المستخدم نفسه. مع عنصر القائمة حذف، ما يتيح للمستخدمين الإشارة إلى أن الانتهاء من مشاهدة المحتوى المفهرَس سابقًا هذه هي الطريقة التي يؤدي بها حذف واجهة المستخدم في Chrome 80:

عنصر القائمة "حذف".

وعندما يختار أحد الأشخاص عنصر القائمة هذا، سيستلم مشغّل الخدمات في تطبيق الويب الخاص بك. حدث contentdelete. إنّ التعامل مع هذا الحدث اختياري، ولكنه يوفّر فرصة عامل الخدمة "لتنظيف" المحتوى، مثل الوسائط المخزّنة محليًا من الملفات، والتي أشار شخص ما إلى استغراقها.

لست بحاجة إلى الاتصال بـ 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.
});

ملاحظات حول تصميم واجهة برمجة التطبيقات

هل هناك ما يبدو غريبًا أو لا يعمل على النحو المتوقّع في واجهة برمجة التطبيقات؟ أو هل هناك أجزاء مفقودة تحتاجها لتنفيذ فكرتك؟

يمكنك الإبلاغ عن مشكلة في مستودع GitHub التوضيحي لـ Content Indexing API أو إضافة أفكارك. بمشكلة حالية.

هل تواجه مشكلة في عملية التنفيذ؟

هل واجهت مشكلة في التنفيذ في Chrome؟

يمكنك الإبلاغ عن الخطأ على https://new.crbug.com. تضمين أكبر قدر ممكن قدر الإمكان، وإرشادات بسيطة لإعادة إنتاجها، وتعيين المكونات إلى Blink>ContentIndexing.

هل تخطط لاستخدام واجهة برمجة التطبيقات؟

هل تريد استخدام Content Indexing API في تطبيق الويب؟ الدعم العام لمساعدة Chrome في تحديد أولويات الميزات، كما يُظهر لموردي المتصفحات الآخرين مدى أهمية لدعمهم.

  • إرسال تغريدة إلى @ChromiumDev باستخدام علامة التصنيف #ContentIndexingAPI وتفاصيل حول مكان وكيفية استخدامك.

ما هي بعض التأثيرات المرتبطة بفهرسة المحتوى والأمان والخصوصية؟

يمكنك الاطّلاع على الإجابات. المقدَّمة استجابةً لاستبيان الأمان والخصوصية الخاص بـ W3C. إذا كنت إذا كانت لديك أسئلة أخرى، يُرجى بدء مناقشة من خلال مستودع GitHub الخاص بالمشروع.

صورة رئيسية من تصميم "ماكسيم كاهارليتسكيي" على قناة Un الهدف