Mengindeks halaman yang mampu offline dengan Content Indexing API

Memungkinkan pekerja layanan memberi tahu browser halaman mana yang berfungsi offline

Jeff Posnick

Apa itu Content Indexing API?

Menggunakan progressive web app berarti memiliki akses ke informasi yang penting bagi orang-orang—gambar, video, artikel, dan banyak lagi—terlepas dari status koneksi jaringan Anda saat ini. Teknologi seperti pekerja layanan, Cache Storage API, dan IndexedDB memberi Anda elemen penyusun untuk menyimpan dan menyajikan data saat orang berinteraksi langsung dengan PWA. Namun, membuat PWA offline-first yang berkualitas tinggi hanyalah bagian dari ceritanya. Jika tidak menyadari bahwa konten aplikasi web tersedia saat offline, pengguna tidak akan memanfaatkan sepenuhnya pekerjaan yang Anda lakukan dalam menerapkan fungsi tersebut.

Ini adalah masalah penemuan. Bagaimana PWA Anda dapat membuat pengguna menyadari kontennya yang mampu offline sehingga mereka dapat menemukan dan melihat apa yang tersedia? Content Indexing API adalah solusi untuk masalah ini. Bagian yang ditujukan bagi developer dari solusi ini adalah ekstensi untuk pekerja layanan, yang memungkinkan developer menambahkan URL dan metadata halaman yang dapat diakses 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 lain yang diinstal, indeks akan ditampilkan oleh browser seperti yang ditunjukkan di bawah ini.

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 bukanlah cara alternatif untuk menyimpan konten dalam cache. Ini adalah cara untuk menyediakan metadata tentang halaman yang sudah di-cache oleh pekerja layanan, sehingga browser dapat menampilkan halaman tersebut saat orang ingin melihatnya. Content Indexing API membantu visibilitas halaman yang di-cache.

Lihat penerapannya

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

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

Anda dapat melihat sumber aplikasi contoh di GitHub.

Aplikasi contoh lainnya, PWA Scrapbook, menggambarkan 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 sebagai URL yang kemampuan offline?

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

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

Aplikasi web hanya dapat menambahkan URL ke indeks konten yang berada di bawah cakupan pekerja layanan saat ini. Dengan kata lain, aplikasi web tidak dapat menambahkan URL milik 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 Anda 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 ini sudah ditentukan sebagai bagian dari ServiceWorkerGlobalScope.

Menambahkan ke indeks

Gunakan metode add() untuk mengindeks URL dan metadata yang terkait. Terserah Anda untuk memilih kapan item akan ditambahkan ke indeks. Anda mungkin ingin menambahkan 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',
});

Penambahan entri hanya memengaruhi indeks konten; tindakan tersebut tidak menambahkan apa pun ke cache.

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

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

  • Jika Anda memanggil add() dari konteks window (dengan kata lain, dari halaman web Anda), permintaan ini akan memicu peristiwa fetch pada 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 entri terindeks 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 akan memengaruhi indeks. Tindakan ini tidak menghapus apa pun dari cache.

Menangani peristiwa penghapusan pengguna

Saat browser menampilkan konten yang diindeks, browser mungkin menyertakan antarmuka penggunanya sendiri dengan item menu Hapus, sehingga pengguna dapat menunjukkan bahwa mereka telah melihat konten yang telah diindeks sebelumnya. Berikut ini 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 penanganan peristiwa ini bersifat opsional, hal ini memberikan kesempatan bagi pekerja layanan Anda untuk "membersihkan" konten, seperti file media yang di-cache secara lokal, yang telah menunjukkan bahwa seseorang telah selesai menangani peristiwa ini.

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 pada API yang aneh atau tidak berfungsi seperti yang diharapkan? Atau apakah ada bagian yang hilang yang diperlukan untuk menerapkan ide Anda?

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

Ada masalah dengan penerapan?

Apakah Anda menemukan bug pada implementasi Chrome?

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

Berencana menggunakan API?

Berencana menggunakan Content Indexing API di aplikasi web? 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.