Mengindeks halaman yang mampu offline dengan Content Indexing API

Mengaktifkan pekerja layanan untuk memberi tahu browser halaman mana yang berfungsi secara offline

Jeff Posnick

Apa yang dimaksud dengan Content Indexing API?

Menggunakan progressive web app berarti memiliki akses ke informasi yang penting bagi pengguna—gambar, video, artikel, dan lainnya—terlepas dari status koneksi jaringan Anda saat ini. Teknologi seperti service worker, Cache Storage API, dan IndexedDB memberikan elemen penyusun untuk menyimpan dan menayangkan data saat pengguna berinteraksi langsung dengan PWA. Namun, membuat PWA offline-first berkualitas tinggi hanya sebagian dari cerita. Jika pengguna tidak menyadari bahwa konten aplikasi web tersedia saat mereka offline, mereka tidak akan memanfaatkan sepenuhnya pekerjaan yang Anda lakukan untuk menerapkan fungsi tersebut.

Ini adalah masalah penemuan; bagaimana PWA Anda dapat membuat pengguna menyadari kontennya yang mampu digunakan secara offline sehingga mereka dapat menemukan dan melihat apa yang tersedia? Content Indexing API adalah solusi untuk masalah ini. Bagian solusi ini yang ditampilkan kepada developer adalah ekstensi untuk pekerja layanan, yang memungkinkan developer menambahkan URL dan metadata halaman yang dapat digunakan secara offline ke indeks lokal yang dikelola oleh browser. Peningkatan tersebut tersedia di Chrome 84 dan yang lebih baru.

Setelah indeks diisi dengan konten dari PWA Anda, serta PWA lainnya yang diinstal, indeks akan ditampilkan oleh browser seperti yang ditunjukkan di bawah.

Screenshot item menu Download di halaman tab baru Chrome.
Pertama, pilih item menu Download di halaman tab baru Chrome.
Media dan artikel yang telah ditambahkan ke indeks.
Media dan artikel yang telah ditambahkan ke indeks akan ditampilkan di bagian Artikel untuk Anda.

Selain itu, Chrome dapat secara proaktif merekomendasikan konten saat mendeteksi bahwa pengguna sedang offline.

Content Indexing API bukan cara alternatif untuk meng-cache konten. Ini adalah cara untuk menyediakan metadata tentang halaman yang sudah di-cache oleh pekerja layanan Anda, sehingga browser dapat menampilkan halaman tersebut saat ada orang yang ingin melihatnya. Content Indexing API membantu kemampuan penemuan halaman yang di-cache.

Lihat penerapannya

Cara terbaik untuk merasakan Content Indexing API adalah dengan mencoba aplikasi contoh.

  1. Pastikan Anda menggunakan browser dan platform yang didukung. Saat ini, versi tersebut terbatas untuk Chrome 84 atau yang lebih baru di Android. Buka about://version untuk melihat versi Chrome yang Anda jalankan.
  2. Kunjungi https://contentindex.dev
  3. Klik tombol + di samping satu atau beberapa item dalam daftar.
  4. (Opsional) Nonaktifkan koneksi Wi-Fi dan data seluler perangkat, atau aktifkan mode pesawat untuk menyimulasikan browser Anda menjadi offline.
  5. Pilih Hasil download dari menu Chrome, lalu beralih ke tab Artikel untuk Anda.
  6. Jelajahi konten yang sebelumnya Anda simpan.

Anda dapat melihat sumber aplikasi contoh di GitHub.

Contoh aplikasi lainnya, Scrapbook PWA, mengilustrasikan penggunaan Content Indexing API dengan Web Share Target API. Kode ini menunjukkan teknik untuk menjaga Content Indexing API tetap sinkron dengan item yang disimpan oleh aplikasi web menggunakan Cache Storage API.

Menggunakan API

Untuk menggunakan API, aplikasi Anda harus memiliki pekerja layanan dan URL yang dapat dijelajahi secara offline. Jika aplikasi web Anda saat ini tidak memiliki pekerja layanan, library Workbox dapat menyederhanakan pembuatannya.

Jenis URL apa yang dapat diindeks karena dapat digunakan secara offline?

API ini mendukung URL pengindeksan yang sesuai dengan dokumen HTML. Misalnya, URL untuk file media yang di-cache tidak dapat diindeks secara langsung. Sebagai gantinya, Anda harus memberikan URL untuk halaman yang menampilkan media, dan yang berfungsi secara offline.

Pola yang direkomendasikan adalah membuat halaman HTML "pelihat" yang dapat menerima URL media pokok sebagai parameter kueri, lalu menampilkan konten file, mungkin dengan kontrol atau konten tambahan di halaman.

Aplikasi web hanya dapat menambahkan URL ke indeks konten yang berada dalam cakupan pekerja layanan saat ini. Dengan kata lain, aplikasi web tidak dapat menambahkan URL yang termasuk dalam domain yang sama sekali berbeda ke dalam indeks konten.

Ringkasan

Content Indexing API mendukung tiga operasi: menambahkan, mencantumkan, dan menghapus metadata. Metode ini diekspos dari properti baru, index, yang telah ditambahkan ke antarmuka ServiceWorkerRegistration.

Langkah pertama dalam mengindeks konten adalah mendapatkan referensi ke ServiceWorkerRegistration saat ini. Menggunakan navigator.serviceWorker.ready adalah cara yang paling mudah:

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!
}

Jika melakukan panggilan ke Content Indexing API dari dalam pekerja layanan, bukan dari dalam halaman web, Anda dapat merujuk ke ServiceWorkerRegistration secara langsung melalui registration. Kolom tersebut sudah ditetapkan sebagai bagian dari ServiceWorkerGlobalScope.

Menambahkan ke indeks

Gunakan metode add() untuk mengindeks URL dan metadata terkaitnya. Anda dapat memilih waktu item ditambahkan ke indeks. Anda mungkin ingin menambahkan data ke indeks sebagai respons terhadap input, seperti mengklik tombol "simpan offline". Atau, Anda dapat menambahkan item secara otomatis setiap kali data yang di-cache diperbarui melalui mekanisme seperti sinkronisasi latar belakang berkala.

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',
});

Menambahkan entri hanya memengaruhi indeks konten; entri tidak menambahkan apa pun ke cache.

Kasus ekstrem: Panggil add() dari konteks window jika ikon Anda mengandalkan pengendali fetch

Saat Anda memanggil add(), Chrome akan membuat permintaan untuk setiap URL ikon untuk memastikan bahwa Chrome memiliki salinan ikon yang akan digunakan saat menampilkan daftar konten yang diindeks.

  • Jika Anda memanggil add() dari konteks window (dengan kata lain, dari halaman web), permintaan ini akan memicu peristiwa fetch di pekerja layanan Anda.

  • Jika Anda memanggil add() dalam pekerja layanan (mungkin di dalam pengendali peristiwa lain), permintaan tersebut tidak akan memicu pengendali fetch pekerja layanan. Ikon akan diambil secara langsung, tanpa keterlibatan pekerja layanan. Perlu diingat hal ini jika ikon Anda mengandalkan pengendali fetch, mungkin karena ikon tersebut hanya ada di cache lokal, bukan di jaringan. Jika ya, pastikan Anda hanya memanggil add() dari konteks window.

Mencantumkan konten indeks

Metode getAll() menampilkan promise untuk daftar iterable dari entri yang diindeks beserta metadatanya. Entri yang ditampilkan akan berisi semua data yang disimpan dengan add().

const entries = await registration.index.getAll();
for (const entry of entries) {
  // entry.id, entry.launchUrl, etc. are all exposed.
}

Menghapus item dari indeks

Untuk menghapus item dari indeks, panggil delete() dengan id item yang akan dihapus:

await registration.index.delete('article-123');

Memanggil delete() hanya memengaruhi indeks. Tindakan ini tidak akan menghapus apa pun dari cache.

Menangani peristiwa penghapusan pengguna

Saat menampilkan konten yang diindeks, browser dapat menyertakan antarmuka penggunanya sendiri dengan item menu Hapus, sehingga pengguna dapat menunjukkan bahwa mereka telah selesai melihat konten yang diindeks sebelumnya. Berikut adalah tampilan antarmuka penghapusan di Chrome 80:

Item menu hapus.

Saat seseorang memilih item menu tersebut, pekerja layanan aplikasi web Anda akan menerima peristiwa contentdelete. Meskipun menangani peristiwa ini bersifat opsional, peristiwa ini memberikan kesempatan bagi pekerja layanan Anda untuk "membersihkan" konten, seperti file media yang di-cache secara lokal, yang telah selesai digunakan oleh seseorang.

Anda tidak perlu memanggil registration.index.delete() di dalam pengendali contentdelete; jika peristiwa telah diaktifkan, penghapusan indeks yang relevan telah dilakukan oleh browser.

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.
});

Masukan tentang desain API

Apakah ada sesuatu tentang API yang canggung atau tidak berfungsi seperti yang diharapkan? Atau apakah ada bagian yang hilang yang diperlukan untuk menerapkan ide Anda?

Ajukan masalah di repo GitHub penjelasan Content Indexing API, atau tambahkan pendapat Anda ke masalah yang ada.

Mengalami masalah dengan penerapan?

Apakah Anda menemukan bug pada penerapan Chrome?

Laporkan bug di https://new.crbug.com. Sertakan detail sebanyak mungkin, petunjuk sederhana untuk mereproduksi, dan tetapkan Components ke Blink>ContentIndexing.

Anda berencana menggunakan API?

Berencana menggunakan Content Indexing API di aplikasi web Anda? Dukungan publik Anda membantu Chrome memprioritaskan fitur, dan menunjukkan kepada vendor browser lain betapa pentingnya mendukung fitur tersebut.

Apa saja implikasi keamanan dan privasi dari pengindeksan konten?

Lihat jawaban yang diberikan sebagai respons terhadap kuesioner Keamanan dan Privasi W3C. Jika ada pertanyaan lebih lanjut, mulai diskusi melalui repo GitHub project.

Banner besar oleh Maksym Kaharlytskyi di Unsplash.