jendela-kerja

Paket workbox-window adalah kumpulan modul yang dimaksudkan untuk berjalan dalam konteks window, yaitu di dalam halaman web Anda. Mereka adalah pelengkap paket workbox lainnya yang berjalan di pekerja layanan.

Fitur/sasaran utama workbox-window adalah:

• Untuk menyederhanakan proses pendaftaran dan update pekerja layanan dengan membantu developer mengidentifikasi momen paling penting dalam siklus proses pekerja layanan, dan memudahkan untuk merespons momen tersebut.
• Untuk membantu mencegah developer melakukan kesalahan paling umum.
• Untuk mengaktifkan komunikasi yang lebih mudah antara kode yang berjalan di pekerja layanan dan kode yang berjalan di jendela.

Mengimpor dan menggunakan workbox-window

Titik entri utama untuk paket workbox-window adalah class Workbox, dan Anda dapat mengimpornya dalam kode dari CDN kami atau menggunakan alat pemaketan JavaScript yang populer.

Menggunakan CDN kami

Cara termudah untuk mengimpor class Workbox di situs Anda adalah dari CDN kami:

<script type="module">
  import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-window.prod.mjs';

  if ('serviceWorker' in navigator) {
    const wb = new Workbox('/sw.js');

    wb.register();
  }
</script>

Perhatikan bahwa contoh ini menggunakan <script type="module"> dan pernyataan import untuk memuat class Workbox. Meskipun Anda mungkin berpikir bahwa Anda perlu melakukan transpilasi kode ini agar berfungsi di browser lama, hal tersebut sebenarnya tidak diperlukan.

Semua browser utama yang mendukung pekerja layanan juga mendukung modul JavaScript native, sehingga sebaiknya menyajikan kode ini ke browser apa pun (browser lama akan mengabaikannya).

Memuat Workbox dengan pemaket JavaScript

Meskipun sama sekali tidak diperlukan alat untuk menggunakan workbox-window, jika infrastruktur pengembangan Anda sudah menyertakan pemaket seperti webpack atau Rollup yang berfungsi dengan dependensi npm, Anda dapat menggunakannya untuk memuat workbox-window.

Langkah pertama adalah menginstal workbox-window sebagai dependensi aplikasi Anda:

npm install workbox-window

Kemudian, di salah satu file JavaScript aplikasi Anda, workbox import dengan merujuk nama paket workbox-window:

import {Workbox} from 'workbox-window';

if ('serviceWorker' in navigator) {
  const wb = new Workbox('/sw.js');

  wb.register();
}

Jika bundler Anda mendukung pemisahan kode melalui pernyataan impor dinamis, Anda juga dapat memuat workbox-window secara bersyarat, yang akan membantu mengurangi ukuran paket utama halaman Anda.

Meskipun workbox-window cukup kecil, tidak ada alasan situs perlu dimuat dengan logika aplikasi inti situs Anda, karena pekerja layanan, pada dasarnya, merupakan peningkatan progresif.

if ('serviceWorker' in navigator) {
  const {Workbox} = await import('workbox-window');

  const wb = new Workbox('/sw.js');
  wb.register();
}

Konsep pemaketan lanjutan

Tidak seperti paket Workbox yang berjalan di pekerja layanan, file build yang dirujuk oleh kolom main dan module workbox-window di package.json ditranspilasi ke ES5. Hal ini membuatnya kompatibel dengan alat build saat ini—beberapa di antaranya tidak mengizinkan developer mentranspilasi apa pun dari dependensi node_module mereka.

Jika sistem build memang memungkinkan Anda melakukan transpilasi dependensi (atau jika Anda tidak perlu mentranspilasi kode apa pun), sebaiknya impor file sumber tertentu, bukan paket itu sendiri.

Berikut adalah berbagai cara untuk mengimpor Workbox, beserta penjelasan tentang apa yang akan ditampilkan masing-masing:

// Imports a UMD version with ES5 syntax
// (pkg.main: "build/workbox-window.prod.umd.js")
const {Workbox} = require('workbox-window');

// Imports the module version with ES5 syntax
// (pkg.module: "build/workbox-window.prod.es5.mjs")
import {Workbox} from 'workbox-window';

// Imports the module source file with ES2015+ syntax
import {Workbox} from 'workbox-window/Workbox.mjs';

Contoh

Setelah mengimpor class Workbox, Anda dapat menggunakannya untuk mendaftar dan berinteraksi dengan pekerja layanan. Berikut beberapa contoh cara menggunakan Workbox di aplikasi Anda:

Mendaftarkan pekerja layanan dan memberi tahu pengguna saat pertama kali pekerja layanan tersebut aktif

Banyak pekerja layanan pengguna aplikasi web melakukan precache aset, sehingga aplikasi mereka berfungsi secara offline pada pemuatan halaman berikutnya. Dalam beberapa kasus, sebaiknya beri tahu pengguna bahwa aplikasi kini tersedia secara offline.

const wb = new Workbox('/sw.js');

wb.addEventListener('activated', event => {
  // `event.isUpdate` will be true if another version of the service
  // worker was controlling the page when this version was registered.
  if (!event.isUpdate) {
    console.log('Service worker activated for the first time!');

    // If your service worker is configured to precache assets, those
    // assets should all be available now.
  }
});

// Register the service worker after event listeners have been added.
wb.register();

Memberi tahu pengguna jika pekerja layanan telah diinstal, tetapi terhenti saat menunggu diaktifkan

Jika halaman yang dikontrol oleh pekerja layanan yang ada mendaftarkan pekerja layanan baru, secara default pekerja layanan tersebut tidak akan aktif hingga semua klien yang dikontrol oleh pekerja layanan awal telah menghapus muatannya sepenuhnya.

Ini menjadi sumber kebingungan umum bagi developer, terutama dalam kasus ketika memuat ulang halaman saat ini tidak menyebabkan pekerja layanan baru diaktifkan.

Untuk membantu meminimalkan kebingungan dan memperjelas kapan situasi ini terjadi, class Workbox menyediakan peristiwa waiting yang dapat Anda proses:

const wb = new Workbox('/sw.js');

wb.addEventListener('waiting', event => {
  console.log(
    `A new service worker has installed, but it can't activate` +
      `until all tabs running the current version have fully unloaded.`
  );
});

// Register the service worker after event listeners have been added.
wb.register();

Memberi tahu pengguna tentang pembaruan cache dari paket workbox-broadcast-update

Paket workbox-broadcast-update adalah cara terbaik untuk dapat menayangkan konten dari cache (untuk pengiriman cepat) sekaligus dapat memberi tahu pengguna tentang pembaruan konten tersebut (menggunakan strategi yang sudah tidak berlaku saat validasi ulang).

Untuk menerima update tersebut dari jendela, Anda dapat memproses peristiwa message dengan jenis CACHE_UPDATED:

const wb = new Workbox('/sw.js');

wb.addEventListener('message', event => {
  if (event.data.type === 'CACHE_UPDATED') {
    const {updatedURL} = event.data.payload;

    console.log(`A newer version of ${updatedURL} is available!`);
  }
});

// Register the service worker after event listeners have been added.
wb.register();

Mengirim daftar URL ke cache kepada pekerja layanan

Untuk beberapa aplikasi, Anda dapat mengetahui semua aset yang perlu di-cache sebelumnya pada waktu build, tetapi beberapa aplikasi melayani halaman yang benar-benar berbeda, berdasarkan URL yang pertama kali dibuka pengguna.

Untuk aplikasi dalam kategori terakhir, mungkin masuk akal untuk hanya meng-cache aset yang diperlukan pengguna untuk halaman tertentu yang mereka kunjungi. Saat menggunakan paket workbox-routing, Anda dapat mengirimkan daftar URL untuk di-cache ke router, dan URL tersebut akan di-cache sesuai dengan aturan yang ditentukan pada router itu sendiri.

Contoh ini mengirimkan daftar URL yang dimuat oleh halaman ke router setiap kali pekerja layanan baru diaktifkan. Perlu diperhatikan, Anda boleh mengirim semua URL karena hanya URL yang cocok dengan rute yang ditentukan dalam pekerja layanan yang akan di-cache:

const wb = new Workbox('/sw.js');

wb.addEventListener('activated', event => {
  // Get the current page URL + all resources the page loaded.
  const urlsToCache = [
    location.href,
    ...performance.getEntriesByType('resource').map(r => r.name),
  ];
  // Send that list of URLs to your router in the service worker.
  wb.messageSW({
    type: 'CACHE_URLS',
    payload: {urlsToCache},
  });
});

// Register the service worker after event listeners have been added.
wb.register();

Momen penting siklus proses pekerja layanan

Siklus proses pekerja layanan sangat kompleks dan mungkin sulit untuk dipahami sepenuhnya. Salah satu alasannya sangat rumit adalah aplikasi ini harus menangani semua kasus ekstrem untuk semua kemungkinan penggunaan pekerja layanan (misalnya, mendaftarkan lebih dari satu pekerja layanan, mendaftarkan pekerja layanan yang berbeda dalam frame yang berbeda, mendaftarkan pekerja layanan dengan nama berbeda, dll.).

Namun, sebagian besar developer yang mengimplementasikan pekerja layanan tidak perlu mengkhawatirkan semua kasus ekstrem ini karena penggunaannya cukup sederhana. Sebagian besar developer hanya mendaftarkan satu pekerja layanan per pemuatan halaman, dan mereka tidak mengubah nama file pekerja layanan yang di-deploy ke server.

Class Workbox menggunakan tampilan yang lebih sederhana ini untuk siklus proses pekerja layanan dengan membagi semua pendaftaran pekerja layanan menjadi dua kategori: pekerja layanan yang terdaftar milik instance dan pekerja layanan eksternal:

• Pekerja layanan terdaftar: pekerja layanan yang mulai diinstal sebagai hasil dari instance Workbox yang memanggil register() atau pekerja layanan yang sudah aktif jika memanggil register() tidak memicu peristiwa updatefound pada pendaftaran.
• Pekerja layanan eksternal: pekerja layanan yang mulai menginstal secara terpisah dari instance Workbox yang memanggil register(). Hal ini biasanya terjadi saat pengguna membuka versi baru situs Anda di tab lain. Jika peristiwa berasal dari pekerja layanan eksternal, properti isExternal peristiwa akan ditetapkan ke true.

Dengan mempertimbangkan dua jenis pekerja layanan ini, berikut adalah perincian semua momen siklus proses pekerja layanan yang penting, beserta rekomendasi developer tentang cara menanganinya:

Saat pertama kali pekerja layanan diinstal

Anda mungkin perlu memperlakukan saat pertama kali pekerja layanan menginstal secara berbeda dengan cara Anda memperlakukan semua update mendatang.

Di workbox-window, Anda dapat membedakan antara penginstalan pertama versi dan update mendatang dengan memeriksa properti isUpdate pada salah satu peristiwa berikut. Untuk penginstalan pertama, isUpdate akan menjadi false.

const wb = new Workbox('/sw.js');

wb.addEventListener('installed', event => {
  if (!event.isUpdate) {
    // First-installed code goes here...
  }
});

wb.register();

Saat versi pekerja layanan yang diupdate ditemukan

Saat pekerja layanan baru mulai diinstal, tetapi versi yang ada saat ini mengontrol halaman, properti isUpdate dari semua peristiwa berikut akan menjadi true.

Cara Anda bereaksi dalam situasi ini biasanya berbeda dengan penginstalan pertama karena Anda harus mengelola kapan dan bagaimana pengguna mendapatkan update ini.

Jika versi pekerja layanan yang tidak terduga ditemukan

Terkadang, pengguna akan membiarkan situs Anda terbuka di tab latar belakang dalam waktu yang sangat lama. Mereka bahkan mungkin membuka tab baru dan mengakses situs Anda tanpa menyadari bahwa mereka telah membuka situs Anda di tab latar belakang. Dalam kasus tersebut, Anda dapat menjalankan dua versi situs secara bersamaan, dan hal tersebut dapat menimbulkan beberapa masalah menarik bagi Anda sebagai developer.

Pertimbangkan skenario saat tab A menjalankan v1 pada situs dan tab B menjalankan v2. Saat tab B dimuat, tab tersebut akan dikontrol oleh versi pekerja layanan yang dikirim dengan v1, tetapi halaman yang ditampilkan oleh server (jika menggunakan strategi caching yang mengutamakan jaringan untuk permintaan navigasi) akan berisi semua aset v2 Anda.

Namun, hal ini umumnya bukan masalah untuk tab B, karena saat menulis kode v2, Anda mengetahui cara kerja kode v1. Namun, hal ini dapat menjadi masalah untuk tab A, karena kode v1 Anda tidak mungkin memprediksi perubahan apa yang mungkin ditimbulkan oleh kode v2 Anda.

Untuk membantu menangani situasi tersebut, workbox-window juga mengirim peristiwa siklus proses saat mendeteksi update dari pekerja layanan "eksternal", sedangkan eksternal berarti semua versi yang bukan versi yang didaftarkan instance Workbox saat ini.

Mulai Workbox v6 dan yang lebih baru, peristiwa ini setara dengan peristiwa yang didokumentasikan di atas, dengan penambahan properti isExternal: true yang ditetapkan pada setiap objek peristiwa. Jika aplikasi web Anda perlu mengimplementasikan logika tertentu untuk menangani pekerja layanan "eksternal", Anda dapat memeriksa properti tersebut di pengendali peristiwa.

Menghindari kesalahan umum

Salah satu fitur paling berguna yang disediakan Workbox adalah logging developer. Hal ini terutama berlaku untuk workbox-window.

Kami memahami bahwa mengembangkan dengan pekerja layanan sering kali membingungkan, dan jika terjadi hal yang bertentangan dengan yang Anda harapkan, Anda akan kesulitan mengetahui alasannya.

Misalnya, saat Anda membuat perubahan pada pekerja layanan dan memuat ulang halaman, Anda mungkin tidak melihat perubahan tersebut di browser. Kemungkinan besar penyebabnya adalah pekerja layanan masih menunggu untuk diaktifkan.

Namun, saat mendaftarkan pekerja layanan dengan class Workbox, Anda akan diberi tahu tentang semua perubahan status siklus proses di konsol developer, yang akan membantu proses debug penyebab hal-hal tidak seperti yang Anda harapkan.

Selain itu, kesalahan umum yang dilakukan developer saat pertama kali menggunakan pekerja layanan adalah mendaftarkan pekerja layanan dalam cakupan yang salah.

Untuk membantu mencegah hal ini terjadi, class Workbox akan memperingatkan Anda jika halaman yang mendaftarkan pekerja layanan tidak berada dalam cakupan pekerja layanan tersebut. Tindakan ini juga akan memperingatkan Anda jika pekerja layanan aktif tetapi belum mengontrol halaman:

Komunikasi jendela ke pekerja layanan

Penggunaan pekerja layanan tingkat lanjut melibatkan banyak pengiriman pesan antara pekerja layanan dan jendela. Class Workbox juga membantu hal ini dengan menyediakan metode messageSW(), yang akan melakukan postMessage() pada pekerja layanan yang terdaftar di instance dan menunggu respons.

Meskipun Anda dapat mengirim data ke pekerja layanan dalam format apa pun, format yang digunakan oleh semua paket Workbox adalah objek dengan tiga properti (dua properti terakhir bersifat opsional):

Pesan yang dikirim melalui metode messageSW() menggunakan MessageChannel sehingga penerima dapat meresponsnya. Untuk merespons pesan, Anda dapat memanggil event.ports[0].postMessage(response) di pemroses peristiwa pesan. Metode messageSW() menampilkan promise yang akan di-resolve ke response apa pun yang Anda balas.

Berikut adalah contoh pengiriman pesan dari jendela ke pekerja layanan dan mendapatkan respons. Blok kode pertama adalah pemroses pesan di pekerja layanan, dan blok kedua menggunakan class Workbox untuk mengirim pesan dan menunggu respons:

Kode di sw.js:

const SW_VERSION = '1.0.0';

addEventListener('message', event => {
  if (event.data.type === 'GET_VERSION') {
    event.ports[0].postMessage(SW_VERSION);
  }
});

Kode di main.js (berjalan di jendela):

const wb = new Workbox('/sw.js');
wb.register();

const swVersion = await wb.messageSW({type: 'GET_VERSION'});
console.log('Service Worker version:', swVersion);

Mengelola inkompatibilitas versi

Contoh di atas menunjukkan cara mengimplementasikan pemeriksaan versi pekerja layanan dari jendela. Contoh ini digunakan karena saat Anda mengirim pesan bolak-balik antara jendela dan pekerja layanan, penting untuk diperhatikan bahwa pekerja layanan mungkin tidak menjalankan versi yang sama dari situs Anda dengan kode halaman yang dijalankan. Solusi untuk menangani masalah ini berbeda-beda, bergantung pada apakah penayangan halaman Anda terlebih dahulu jaringan atau cache-first.

Mengutamakan jaringan

Saat menayangkan jaringan halaman terlebih dahulu, pengguna akan selalu mendapatkan versi terbaru HTML dari server Anda. Namun, saat pengguna pertama kali mengunjungi kembali situs Anda (setelah Anda men-deploy update), HTML yang mereka dapatkan akan menggunakan versi terbaru, tetapi pekerja layanan yang berjalan di browser mereka adalah versi yang telah diinstal sebelumnya (mungkin banyak versi lama).

Penting untuk memahami kemungkinan ini karena jika JavaScript yang dimuat oleh versi halaman saat ini mengirim pesan ke pekerja layanan versi lama, versi tersebut mungkin tidak mengetahui cara merespons (atau mungkin merespons dengan format yang tidak kompatibel).

Oleh karena itu, sebaiknya selalu buat versi pekerja layanan dan periksa versi yang kompatibel sebelum melakukan pekerjaan penting apa pun.

Misalnya, dalam kode di atas, jika versi pekerja layanan yang ditampilkan oleh panggilan messageSW() tersebut lebih lama dari versi yang diharapkan, sebaiknya tunggu hingga update ditemukan (yang akan terjadi ketika Anda memanggil register()). Pada saat itu, Anda dapat memberi tahu pengguna atau update, atau secara manual melewati fase menunggu untuk segera mengaktifkan pekerja layanan baru.

Cache terlebih dahulu

Berbeda dengan saat menayangkan halaman yang mengutamakan jaringan, saat menayangkan halaman dengan cache-first, Anda tahu bahwa halaman pada awalnya akan selalu sama dengan versi pekerja layanan (karena itulah yang menampilkannya). Oleh karena itu, messageSW() dapat langsung digunakan dengan aman.

Namun, jika versi terbaru dari pekerja layanan Anda ditemukan dan diaktifkan saat halaman memanggil register() (yaitu, Anda sengaja melewati fase menunggu), pesan mungkin akan dikirim ke halaman tersebut dengan tidak aman lagi.

Salah satu strategi untuk mengelola kemungkinan ini adalah menggunakan skema pembuatan versi yang memungkinkan Anda membedakan antara update yang dapat menyebabkan gangguan dan update yang tidak menyebabkan gangguan, dan jika terjadi update yang dapat menyebabkan gangguan, Anda akan tahu bahwa mengirim pesan kepada pekerja layanan tidak aman. Sebagai gantinya, Anda ingin memperingatkan pengguna bahwa mereka menjalankan halaman versi lama, dan menyarankan mereka memuat ulang halaman untuk mendapatkan update.

Lewati bantuan yang menunggu

Konvensi penggunaan umum untuk pengiriman pesan window ke pekerja layanan adalah mengirim pesan {type: 'SKIP_WAITING'} untuk memerintahkan pekerja layanan yang diinstal agar melewati fase menunggu dan mengaktifkan.

Mulai dari Workbox v6, metode messageSkipWaiting() dapat digunakan untuk mengirim pesan {type: 'SKIP_WAITING'} ke pekerja layanan yang menunggu dan terkait dengan pendaftaran pekerja layanan saat ini. Layanan ini diam-diam tidak akan melakukan apa pun jika tidak ada pekerja layanan yang menunggu.

workbox-window.messageSW(
  sw: ServiceWorker,
  data: object,
)