Menambahkan manifes aplikasi web

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

Manifes aplikasi web adalah file JSON yang memberi tahu browser bagaimana Progressive Web App (PWA) harus berperilaku saat diinstal di desktop pengguna atau perangkat seluler. Setidaknya, file manifes standar mencakup:

• Nama aplikasi
• Ikon yang harus digunakan aplikasi
• URL yang harus dibuka saat aplikasi diluncurkan

Membuat file manifes

File manifes dapat bernama apa saja, tetapi biasanya bernama manifest.json dan disalurkan dari {i>root <i}(direktori tingkat atas situs web Anda). Spesifikasi menyarankan ekstensi seharusnya .webmanifest, tetapi Anda mungkin ingin menggunakan JSON file untuk membuat manifes Anda lebih jelas dibaca.

Manifes standar terlihat seperti ini:

{
  "short_name": "Weather",
  "name": "Weather: Do I need an umbrella?",
  "icons": [
    {
      "src": "/images/icons-vector.svg",
      "type": "image/svg+xml",
      "sizes": "512x512"
    },
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "id": "/?source=pwa",
  "start_url": "/?source=pwa",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6",
  "shortcuts": [
    {
      "name": "How's the weather today?",
      "short_name": "Today",
      "description": "View weather information for today",
      "url": "/today?source=pwa",
      "icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
    },
    {
      "name": "How's the weather tomorrow?",
      "short_name": "Tomorrow",
      "description": "View weather information for tomorrow",
      "url": "/tomorrow?source=pwa",
      "icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
    }
  ],
  "description": "Weather forecast information",
  "screenshots": [
    {
      "src": "/images/screenshot1.png",
      "type": "image/png",
      "sizes": "540x720",
      "form_factor": "narrow"
    },
    {
      "src": "/images/screenshot2.jpg",
      "type": "image/jpg",
      "sizes": "720x540",
      "form_factor": "wide"
    }
  ]
}

Properti manifes utama

short_name dan name

Anda harus menyediakan setidaknya satu dari short_name atau name dalam manifes Anda. Jika Anda memberikan keduanya, name digunakan saat aplikasi diinstal, dan short_name adalah digunakan di layar utama pengguna, peluncur, atau tempat lain di mana ruang secara terbatas.

icons

Saat pengguna menginstal PWA, Anda dapat menentukan serangkaian ikon untuk browser untuk digunakan di layar utama, peluncur aplikasi, pengalih tugas, layar pembuka, dan di tempat lain.

Properti icons adalah array objek gambar. Setiap objek harus menyertakan src, properti sizes, dan type gambar. Untuk menggunakan ikon maskable, terkadang disebut sebagai aplikasi ikon di Android, tambahkan "purpose": "any maskable" ke properti icon.

Untuk Chromium, Anda harus memberikan setidaknya ikon 192x192 piksel dan Ikon 512x512 piksel. Jika hanya dua ukuran ikon tersebut yang disediakan, Chrome secara otomatis menskalakan ikon agar sesuai dengan perangkat. Jika Anda lebih suka meningkatkan ikon sendiri, dan menyesuaikannya untuk kesempurnaan piksel, menyediakan ikon secara bertahap sebesar 48 dp.

id

Properti id memungkinkan Anda secara eksplisit menentukan ID yang digunakan untuk aplikasi. Menambahkan properti id ke manifes akan menghapus dependensi pada start_url atau lokasi manifes, dan memungkinkan pembaruan mereka di masa depan. Untuk informasi selengkapnya, lihat Mengidentifikasi PWA secara unik dengan properti ID manifes aplikasi web.

start_url

start_url adalah properti wajib. Ini memberi tahu browser di mana aplikasi harus dimulai saat diluncurkan, dan mencegah aplikasi dimulai di laman mana pun tempat pengguna berada ketika mereka menambahkan aplikasi ke layar utama.

start_url harus mengarahkan pengguna langsung ke aplikasi Anda, bukan produk halaman landing Anda. Pikirkan tentang apa yang akan dilakukan pengguna segera setelah mereka buka aplikasi Anda, lalu tempatkan di sana.

background_color

Properti background_color digunakan di layar pembuka saat aplikasi diluncurkan di perangkat seluler untuk pertama kalinya.

display

Anda dapat menyesuaikan UI browser yang ditampilkan saat aplikasi diluncurkan. Sebagai misalnya, Anda dapat menyembunyikan elemen bilah alamat dan antarmuka pengguna {i>browser<i}. Game bahkan dapat diluncurkan dalam layar penuh. Properti display mengambil salah satu nilai berikut:

Properti	Perilaku
fullscreen	Membuka aplikasi web tanpa UI browser dan menggunakan semua area tampilan yang tersedia.
standalone	Membuka aplikasi web agar terlihat dan terasa seperti aplikasi mandiri. Aplikasi berjalan di jendelanya sendiri, terpisah dari browser, dan menyembunyikan data elemen UI browser lain, seperti kolom URL.
minimal-ui	Mode ini mirip dengan standalone, tetapi memberikan pengguna dengan serangkaian elemen UI minimal untuk mengontrol navigasi, seperti tombol kembali dan muat ulang.
browser	Pengalaman browser standar.

display_override

Untuk memilih cara aplikasi web Anda ditampilkan, setel mode display dalam manifesnya sebagai dijelaskan sebelumnya. Browser tidak diperlukan untuk mendukung semua tampilan yang berbeda, tetapi diperlukan untuk mendukung rantai penggantian yang ditentukan spesifikasi ("fullscreen" → "standalone" → "minimal-ui" → "browser"). Jika mereka tidak mendukung mode tertentu, mereka akan kembali ke mode tampilan berikutnya dalam rantai tersebut. Di beberapa dalam kasus yang jarang terjadi, penggantian ini dapat menyebabkan masalah. Misalnya, developer tidak bisa meminta "minimal-ui" tanpa dipaksa kembali ke layar "browser" mode saat "minimal-ui" tidak didukung. Perilaku saat ini juga membuat tidak mungkin memperkenalkan mode tampilan baru dengan cara yang kompatibel dengan versi sebelumnya, karena mereka tidak punya tempat di rantai penggantian.

Anda dapat menetapkan urutan penggantian Anda sendiri menggunakan properti display_override, yang dipertimbangkan browser sebelum properti display. Nilainya adalah urutan {i>string<i} yang dipertimbangkan dalam urutan yang terdaftar, dan yang pertama yang didukung akan diterapkan. Jika tidak ada yang didukung, browser akan kembali untuk mengevaluasi kolom display. Jika tidak ada kolom display, browser mengabaikan display_override.

Berikut adalah contoh cara menggunakan display_override. Detail dari "window-control-overlay" berada di luar cakupan untuk halaman ini.

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

Saat memuat aplikasi ini, browser akan mencoba menggunakan "window-control-overlay" terlebih dahulu. Jika tidak tersedia, sistem akan kembali ke "minimal-ui", lalu ke "standalone" dari properti display. Jika tidak satu pun dari opsi tersebut tersedia, browser kemudian kembali ke rantai penggantian standar.

scope

scope aplikasi Anda adalah kumpulan URL yang dianggap browser sebagai bagian dari aplikasi Anda. scope mengontrol struktur URL yang mencakup semua proses masuk dan keluar mengarah ke aplikasi, dan browser menggunakannya untuk menentukan kapan pengguna telah keluar aplikasi.

Beberapa catatan lain tentang scope:

• Jika Anda tidak menyertakan scope dalam manifes, nilai default tersirat scope adalah URL mulai, tetapi dengan nama file, kueri, dan fragmennya telah dihapus.
• Atribut scope dapat berupa jalur relatif (../), atau level yang lebih tinggi jalur (/) yang memungkinkan peningkatan cakupan navigasi di aplikasi web Anda.
• start_url harus berada dalam cakupan.
• start_url relatif terhadap jalur yang ditentukan di atribut scope.
• start_url yang dimulai dengan / akan selalu menjadi root asal.

theme_color

theme_color menetapkan warna toolbar, dan dapat tercermin dalam pratinjau aplikasi di pengalih tugas. theme_color harus cocok dengan Warna tema meta ditentukan di head dokumen Anda.

theme_color dalam kueri media

Anda dapat menyesuaikan theme_color dalam kueri media menggunakan atribut media Elemen warna tema meta. Misalnya, Anda dapat menentukan satu warna untuk mode terang dan satu lagi untuk mode gelap dengan cara ini. Namun, Anda tidak dapat menentukan preferensi dalam manifes Anda. Untuk informasi selengkapnya, lihat masalah GitHub w3c/manifes#975.

<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="black">

shortcuts

Properti shortcuts adalah array pintasan aplikasi objek yang menyediakan akses cepat ke tugas utama dalam aplikasi Anda. Setiap anggota adalah kamus yang berisi setidaknya name dan url.

description

Properti description menjelaskan tujuan aplikasi Anda.

Di Chrome, panjang deskripsi maksimum adalah 300 karakter di semua platform. Jika deskripsi lebih panjang dari itu, browser akan memotongnya dengan karakter elipsis. Di Android, deskripsi juga harus menggunakan maksimum tujuh baris teks.

screenshots

Properti screenshots adalah array objek gambar yang mewakili aplikasi Anda skenario penggunaan umum. Setiap objek harus menyertakan src, sizes dan type gambar. Properti form_factor bersifat opsional. Anda dapat menetapkannya ke "wide" untuk screenshot yang berlaku bagi layar lebar hanya atau "narrow" untuk screenshot sempit saja.

Di Chrome, gambar harus memenuhi kriteria berikut:

• Lebar dan tinggi minimal 320 px dan maksimal 3.840 px.
• Dimensi maksimum tidak boleh lebih dari 2,3 kali panjang dimensi minimum dimensi kustom.
• Semua screenshot yang cocok dengan faktor bentuk yang sesuai harus memiliki rasio aspek.
  • Dari Chrome 109, hanya screenshot dengan form_factor yang disetel ke "wide" ditampilkan di desktop.
• Dari Chrome 109, screenshot dengan form_factor yang disetel ke "wide" akan diabaikan di Android. Screenshot tanpa form_factor tetap ditampilkan untuk kompatibilitas mundur.

Chrome di desktop menampilkan minimal satu dan maksimal delapan screenshot yang memenuhi kriteria ini. Bagian lainnya akan diabaikan.

Chrome di Android menampilkan minimal satu dan maksimal lima screenshot yang memenuhi kriteria ini. Bagian lainnya akan diabaikan.

Menambahkan manifes aplikasi web ke halaman

Setelah membuat manifes, tambahkan tag <link> ke semua halaman Progressive Web App. Contoh:

<link rel="manifest" href="/manifest.json">

Menguji manifes Anda

Untuk memverifikasi bahwa manifes Anda disiapkan dengan benar, gunakan panel Manifest di Panel Application di Chrome DevTools.

Panel ini menyediakan versi manifes yang dapat dibaca manusia dan memungkinkan Anda memverifikasi bahwa semua gambar dimuat mereka dapat terus berjalan dengan baik.

Layar pembuka di perangkat seluler

Saat aplikasi Anda pertama kali diluncurkan di perangkat seluler, perlu waktu beberapa saat untuk browser dan konten awal untuk memulai rendering. Daripada menampilkan layar putih yang mungkin membuat pengguna mengira aplikasi tidak bekerja, {i>browser<i} menampilkan layar {i>splash<i} hingga cat pertama.

Chrome akan otomatis membuat layar pembuka dari name, background_color, dan icons yang ditentukan dalam manifes Anda. Untuk membuat bertransisi dari layar pembuka ke aplikasi, membuat Anda background_color warna yang sama dengan halaman pemuatan.

Chrome memilih ikon yang paling cocok dengan resolusi perangkat untuk layar pembuka. Menyediakan ikon 192px dan 512px cukup untuk sebagian besar kasus, tetapi Anda dapat menyediakan ikon tambahan untuk pencocokan yang lebih baik.

Bacaan lebih lanjut

Untuk mempelajari tentang properti lain yang bisa Anda tambahkan ke manifes aplikasi web, lihat dokumentasi Manifes Aplikasi Web MDN.