نمایه سازی صفحات دارای قابلیت آفلاین خود با Content Indexing API، نمایه سازی صفحات دارای قابلیت آفلاین خود با Content Indexing API

فعال کردن سرویس ورکرها برای اینکه به مرورگرها بگویند کدام صفحات به صورت آفلاین کار می‌کنند

Jeff Posnick

API ایندکس گذاری محتوا چیست؟

استفاده از یک برنامه وب پیش‌رونده به معنای دسترسی به اطلاعاتی است که مردم به آنها اهمیت می‌دهند - تصاویر، ویدیوها، مقالات و موارد دیگر - صرف نظر از وضعیت فعلی اتصال شبکه شما. فناوری‌هایی مانند service workerها ، Cache Storage API و IndexedDB بلوک‌های سازنده‌ای را برای ذخیره و ارائه داده‌ها در هنگام تعامل مستقیم افراد با یک PWA در اختیار شما قرار می‌دهند. اما ساخت یک PWA با کیفیت بالا و آفلاین تنها بخشی از داستان است. اگر افراد متوجه نشوند که محتوای یک برنامه وب در حالت آفلاین نیز در دسترس است، از تمام تلاشی که برای پیاده‌سازی آن قابلیت انجام می‌دهید، بهره نخواهند برد.

این یک مشکل کشف است؛ چگونه PWA شما می‌تواند کاربران را از محتوای آفلاین آن آگاه کند تا بتوانند آنچه را که در دسترس است کشف و مشاهده کنند؟ API فهرست‌بندی محتوا، راه‌حلی برای این مشکل است. بخش مربوط به توسعه‌دهندگان این راه‌حل، افزونه‌ای برای سرویس ورکرها است که به توسعه‌دهندگان اجازه می‌دهد URLها و ابرداده‌های صفحات آفلاین را به یک فهرست محلی که توسط مرورگر نگهداری می‌شود، اضافه کنند. این بهبود در کروم ۸۴ و بالاتر موجود است.

وقتی ایندکس با محتوای PWA شما و همچنین هر PWA نصب شده دیگری پر شد، توسط مرورگر به صورت زیر نمایش داده می‌شود.

علاوه بر این، کروم می‌تواند به صورت پیشگیرانه، زمانی که تشخیص می‌دهد کاربر آفلاین است، محتوا را پیشنهاد دهد.

API فهرست‌بندی محتوا (Content Indexing API) یک روش جایگزین برای ذخیره‌سازی محتوا نیست . این روشی برای ارائه فراداده (metadata) در مورد صفحاتی است که از قبل توسط سرویس ورکر شما ذخیره‌سازی شده‌اند، به طوری که مرورگر می‌تواند این صفحات را زمانی که افراد احتمالاً می‌خواهند آنها را مشاهده کنند، نمایش دهد. API فهرست‌بندی محتوا به قابلیت کشف صفحات ذخیره‌سازی شده کمک می‌کند.

آن را در عمل ببینید

بهترین راه برای آشنایی با API فهرست‌بندی محتوا، امتحان کردن یک برنامه نمونه است.

1. مطمئن شوید که از مرورگر و پلتفرم پشتیبانی‌شده‌ای استفاده می‌کنید که محدود به کروم ۸۴ یا بالاتر در اندروید باشد. برای دیدن نسخه کرومی که اجرا می‌کنید، به about://version بروید.
2. به آدرس https://contentindex.dev مراجعه کنید
3. روی دکمه + کنار یک یا چند مورد از موارد موجود در لیست کلیک کنید.
4. (اختیاری) اتصال WiFi و داده تلفن همراه دستگاه خود را غیرفعال کنید، یا حالت هواپیما را فعال کنید تا حالت آفلاین شدن مرورگر شما شبیه‌سازی شود.
5. از منوی کروم، گزینه‌ی «دانلودها» را انتخاب کنید و به برگه‌ی «مقالات برای شما» بروید.
6. محتوایی را که قبلاً ذخیره کرده‌اید، مرور کنید.

می‌توانید منبع برنامه نمونه را در GitHub مشاهده کنید.

یک برنامه نمونه دیگر، یک Scrapbook PWA ، استفاده از Content Indexing API را با Web Share Target API نشان می‌دهد. این کد، تکنیکی را برای همگام‌سازی Content Indexing API با موارد ذخیره شده توسط یک برنامه وب با استفاده از Cache Storage API نشان می‌دهد.

با استفاده از API

برای استفاده از API، برنامه شما باید یک سرویس ورکر و URLهایی داشته باشد که به صورت آفلاین قابل پیمایش باشند. اگر برنامه وب شما سرویس ورکر ندارد، کتابخانه‌های Workbox می‌توانند ایجاد آن را ساده کنند.

چه نوع URL هایی را می توان به عنوان قابلیت آفلاین فهرست بندی کرد؟

این API از ایندکس کردن URL های مربوط به اسناد HTML پشتیبانی می‌کند. برای مثال، URL یک فایل رسانه‌ای ذخیره شده را نمی‌توان مستقیماً ایندکس کرد. در عوض، باید URL صفحه‌ای را که رسانه را نمایش می‌دهد و به صورت آفلاین کار می‌کند، ارائه دهید.

یک الگوی پیشنهادی، ایجاد یک صفحه HTML «نمایشگر» است که بتواند URL رسانه اصلی را به عنوان پارامتر پرس‌وجو بپذیرد و سپس محتوای فایل را نمایش دهد، که احتمالاً شامل کنترل‌ها یا محتوای اضافی در صفحه نیز می‌شود.

برنامه‌های وب فقط می‌توانند 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 فراخوانی انجام می‌دهید، می‌توانید مستقیماً با استفاده از registration به ServiceWorkerRegistration مراجعه کنید. این ServiceWorkerRegistration از قبل به عنوان بخشی از ServiceWorkerGlobalScope تعریف شده است 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:
  // 'homepage', 'article', 'video', 'audio', or '' (default).
  category: 'article',
});

اضافه کردن یک ورودی فقط بر فهرست محتوا تأثیر می‌گذارد؛ چیزی به حافظه پنهان اضافه نمی‌کند.

حالت لبه‌ای: اگر آیکون‌های شما به یک کنترل‌کننده‌ی fetch متکی هستند، تابع add() را از متن window فراخوانی کنید.

وقتی تابع add() را فراخوانی می‌کنید، کروم برای هر آیکون یک درخواست URL ارسال می‌کند تا مطمئن شود که یک کپی از آیکون برای استفاده هنگام نمایش لیستی از محتوای ایندکس شده دارد.

• اگر add() از متن window (به عبارت دیگر، از صفحه وب خود) فراخوانی کنید، این درخواست باعث ایجاد یک رویداد fetch ) در سرویس ورکر شما می‌شود.

• اگر تابع add() درون سرویس ورکر خود (شاید درون یک رویداد دیگر) فراخوانی کنید، درخواست، کنترل‌کننده‌ی fetch سرویس ورکر را فعال نمی‌کند . آیکون‌ها مستقیماً و بدون هیچ گونه دخالتی در سرویس ورکر واکشی می‌شوند. اگر آیکون‌های شما به کنترل‌کننده‌ی fetch شما وابسته هستند، این نکته را در نظر داشته باشید، شاید به این دلیل که فقط در حافظه‌ی پنهان محلی وجود دارند و نه در شبکه. اگر وجود دارند، مطمئن شوید که فقط add() از متن window فراخوانی می‌کنید.

فهرست کردن محتویات فهرست

متد getAll() ‎ یک promise برای یک لیست قابل تکرار از ورودی‌های اندیس‌گذاری شده و ابرداده‌های آنها برمی‌گرداند. ورودی‌های برگردانده شده شامل تمام داده‌های ذخیره شده با 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 ) داشته باشد که به افراد این امکان را می‌دهد تا اعلام کنند که دیگر محتوای ایندکس‌شده قبلی را مشاهده نمی‌کنند. رابط حذف در کروم ۸۰ به این شکل است:

وقتی کسی آن آیتم منو را انتخاب می‌کند، سرویس ورکر برنامه وب شما یک رویداد 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.
});

بازخورد در مورد طراحی API

آیا چیزی در مورد API وجود دارد که ناخوشایند است یا آنطور که انتظار می‌رود کار نمی‌کند؟ یا قطعات گمشده‌ای وجود دارد که برای پیاده‌سازی ایده خود به آنها نیاز دارید؟

یک مشکل را در مخزن GitHub مربوط به Content Indexing API ثبت کنید، یا نظرات خود را به یک مشکل موجود اضافه کنید.

مشکل در اجرا؟

آیا در پیاده‌سازی کروم اشکالی پیدا کردید؟

یک اشکال را در https://new.crbug.com ثبت کنید. تا جایی که می‌توانید جزئیات، دستورالعمل‌های بازتولید و تنظیم کامپوننت‌ها روی Blink>ContentIndexing ذکر کنید.

قصد استفاده از API را دارید؟

آیا قصد دارید از API فهرست‌بندی محتوا در برنامه وب خود استفاده کنید؟ پشتیبانی عمومی شما به Chrome کمک می‌کند تا ویژگی‌ها را در اولویت قرار دهد و به سایر فروشندگان مرورگر نشان می‌دهد که پشتیبانی از آنها چقدر مهم است.

• با استفاده از هشتگ #ContentIndexingAPI یک توییت به @ChromiumDev ارسال کنید و جزئیات مربوط به محل و نحوه استفاده از آن را شرح دهید.

برخی از پیامدهای امنیتی و حریم خصوصی ایندکس کردن محتوا چیست؟

پاسخ‌های ارائه شده در پرسشنامه امنیت و حریم خصوصی W3C را بررسی کنید. اگر سؤال بیشتری دارید، بحث را در مخزن گیت‌هاب پروژه آغاز کنید.