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

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

Jeff Posnick

Content Indexing API چیست؟

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

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

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

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

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

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

بهترین راه برای دریافت حسی نسبت به Content Indexing API این است که یک برنامه نمونه را امتحان کنید.

1. مطمئن شوید که از یک مرورگر و پلتفرم پشتیبانی شده استفاده می کنید. در حال حاضر، در Android به Chrome 84 یا جدیدتر محدود شده است. به 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 برنامه شما باید دارای یک سرویس دهنده و URL هایی باشد که به صورت آفلاین قابل پیمایش هستند. اگر برنامه وب شما در حال حاضر سرویس‌دهنده ندارد، کتابخانه‌های Workbox می‌توانند ایجاد آن را ساده کنند.

چه نوع 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 از داخل یک سرویس دهنده، به جای داخل یک صفحه وب هستید، می توانید مستقیماً از طریق registration به ServiceWorkerRegistration مراجعه کنید. قبلاً به عنوان بخشی از 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',
});

افزودن یک ورودی فقط بر نمایه محتوا تأثیر می گذارد. چیزی به کش اضافه نمی کند.

Edge case: اگر نمادهای شما به یک کنترل کننده fetch متکی هستند add() از زمینه window فراخوانی کنید

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

• اگر 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() فقط روی ایندکس تأثیر می گذارد. چیزی را از کش پاک نمی کند.

مدیریت یک رویداد حذف کاربر

هنگامی که مرورگر محتوای نمایه شده را نمایش می دهد، ممکن است رابط کاربری خود را با یک آیتم منوی حذف شامل شود که به افراد این فرصت را می دهد تا نشان دهند که مشاهده محتوای نمایه شده قبلی را تمام کرده اند. رابط حذف در کروم 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.
});

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

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

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

مشکل در اجرا؟

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

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

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

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

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

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

پاسخ های ارائه شده در پاسخ به پرسشنامه امنیت و حریم خصوصی W3C را بررسی کنید. اگر سؤال بیشتری دارید، لطفاً از طریق مخزن GitHub پروژه بحثی را شروع کنید.

تصویر قهرمان توسط Maksym Kaharlytskyi در Unsplash .

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

Jeff Posnick

Content Indexing API چیست؟

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

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

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

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

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

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

بهترین راه برای دریافت حسی نسبت به Content Indexing API این است که یک برنامه نمونه را امتحان کنید.

1. مطمئن شوید که از یک مرورگر و پلتفرم پشتیبانی شده استفاده می کنید. در حال حاضر، در Android به Chrome 84 یا جدیدتر محدود شده است. به 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 برنامه شما باید دارای یک سرویس دهنده و URL هایی باشد که به صورت آفلاین قابل پیمایش هستند. اگر برنامه وب شما در حال حاضر سرویس‌دهنده ندارد، کتابخانه‌های Workbox می‌توانند ایجاد آن را ساده کنند.

چه نوع 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 از داخل یک سرویس دهنده، به جای داخل یک صفحه وب هستید، می توانید مستقیماً از طریق registration به ServiceWorkerRegistration مراجعه کنید. قبلاً به عنوان بخشی از 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',
});

افزودن یک ورودی فقط بر نمایه محتوا تأثیر می گذارد. چیزی به کش اضافه نمی کند.

Edge case: اگر نمادهای شما به یک کنترل کننده fetch متکی هستند add() از زمینه window فراخوانی کنید

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

• اگر 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() فقط روی ایندکس تأثیر می گذارد. چیزی را از کش پاک نمی کند.

مدیریت یک رویداد حذف کاربر

هنگامی که مرورگر محتوای نمایه شده را نمایش می دهد، ممکن است رابط کاربری خود را با یک آیتم منوی حذف شامل شود که به افراد این فرصت را می دهد تا نشان دهند که مشاهده محتوای نمایه شده قبلی را تمام کرده اند. رابط حذف در کروم 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.
});

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

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

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

مشکل در اجرا؟

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

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

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

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

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

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

پاسخ های ارائه شده در پاسخ به پرسشنامه امنیت و حریم خصوصی W3C را بررسی کنید. اگر سؤال بیشتری دارید، لطفاً از طریق مخزن GitHub پروژه بحثی را شروع کنید.

تصویر قهرمان توسط Maksym Kaharlytskyi در Unsplash .

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

Jeff Posnick

Content Indexing API چیست؟

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

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

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

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

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

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

بهترین راه برای دریافت حسی نسبت به Content Indexing API این است که یک برنامه نمونه را امتحان کنید.

1. مطمئن شوید که از یک مرورگر و پلتفرم پشتیبانی شده استفاده می کنید. در حال حاضر، در Android به Chrome 84 یا جدیدتر محدود شده است. به 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 برنامه شما باید دارای یک سرویس دهنده و URL هایی باشد که به صورت آفلاین قابل پیمایش هستند. اگر برنامه وب شما در حال حاضر سرویس‌دهنده ندارد، کتابخانه‌های Workbox می‌توانند ایجاد آن را ساده کنند.

چه نوع 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 از داخل یک سرویس دهنده، به جای داخل یک صفحه وب هستید، می توانید مستقیماً از طریق registration به ServiceWorkerRegistration مراجعه کنید. قبلاً به عنوان بخشی از 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',
});

افزودن یک ورودی فقط بر نمایه محتوا تأثیر می گذارد. چیزی به کش اضافه نمی کند.

Edge case: اگر نمادهای شما به یک کنترل کننده fetch متکی هستند add() از زمینه window فراخوانی کنید

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

• اگر 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() فقط روی ایندکس تأثیر می گذارد. چیزی را از کش پاک نمی کند.

مدیریت یک رویداد حذف کاربر

هنگامی که مرورگر محتوای نمایه شده را نمایش می دهد، ممکن است رابط کاربری خود را با یک آیتم منوی حذف شامل شود که به افراد این فرصت را می دهد تا نشان دهند که مشاهده محتوای نمایه شده قبلی را تمام کرده اند. رابط حذف در کروم 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.
});

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

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

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

مشکل در اجرا؟

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

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

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

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

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

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

پاسخ های ارائه شده در پاسخ به پرسشنامه امنیت و حریم خصوصی W3C را بررسی کنید. اگر سؤال بیشتری دارید، لطفاً از طریق مخزن GitHub پروژه بحثی را شروع کنید.

تصویر قهرمان توسط Maksym Kaharlytskyi در Unsplash .