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) Anda harus berperilaku saat diinstal di desktop atau perangkat seluler pengguna. 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 diberi nama manifest.json dan dilayani dari root (direktori tingkat atas situs Anda). Spesifikasi menyarankan ekstensi harus .webmanifest, tetapi Anda mungkin ingin menggunakan file JSON untuk membuat manifes lebih mudah 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 memberikan minimal satu dari short_name atau name dalam manifes. Jika Anda menyediakan keduanya, name akan digunakan saat aplikasi diinstal, dan short_name akan digunakan di layar utama, peluncur, atau tempat lain milik pengguna yang ruangnya terbatas.

icons

Saat pengguna menginstal PWA, Anda dapat menentukan kumpulan ikon untuk digunakan browser 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 yang dapat disamarkan, yang terkadang disebut sebagai ikon adaptif di Android, tambahkan "purpose": "any maskable" ke properti icon.

Untuk Chromium, Anda harus memberikan ikon berukuran minimal 192x192 piksel dan ikon 512x512 piksel. Jika hanya dua ukuran ikon tersebut yang diberikan, Chrome akan otomatis menskalakan ikon agar sesuai dengan perangkat. Jika Anda lebih suka menskalakan ikon Anda sendiri, dan menyesuaikannya untuk mendapatkan presisi piksel, berikan ikon dalam penambahan 48dp.

id

Properti id memungkinkan Anda menentukan ID yang digunakan untuk aplikasi secara eksplisit. Menambahkan properti id ke manifes akan menghapus dependensi pada start_url atau lokasi manifes, dan memungkinkan untuk mengupdatenya di masa mendatang. 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 tempat aplikasi Anda harus dimulai saat diluncurkan, dan mencegah aplikasi dimulai di halaman apa pun yang dibuka pengguna saat mereka menambahkan aplikasi Anda ke layar utama.

start_url Anda harus mengarahkan pengguna langsung ke aplikasi Anda, bukan halaman landing produk. Pikirkan apa yang ingin dilakukan pengguna segera setelah mereka membuka aplikasi Anda, dan tempatkan mereka 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. Misalnya, Anda dapat menyembunyikan kolom URL dan elemen antarmuka pengguna browser. Game bahkan dapat dibuat untuk diluncurkan dalam layar penuh. Properti display menggunakan 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 ini berjalan di jendelanya sendiri, terpisah dari browser, dan menyembunyikan elemen UI browser standar seperti kolom URL.
minimal-ui	Mode ini mirip dengan standalone, tetapi memberi pengguna sekumpulan elemen UI minimal untuk mengontrol navigasi, seperti tombol kembali dan muat ulang.
browser	Pengalaman browser standar.

display_override

Untuk memilih cara aplikasi web ditampilkan, tetapkan mode display dalam manifesnya seperti yang dijelaskan sebelumnya. Browser tidak diwajibkan untuk mendukung semua mode tampilan, tetapi harus mendukung rantai penggantian yang ditentukan spesifikasi ("fullscreen" → "standalone" → "minimal-ui" → "browser"). Jika tidak mendukung mode tertentu, browser akan kembali ke mode tampilan berikutnya dalam rantai. Dalam kasus yang jarang terjadi, penggantian ini dapat menyebabkan masalah. Misalnya, developer tidak dapat meminta "minimal-ui" tanpa dipaksa kembali ke mode tampilan "browser" saat "minimal-ui" tidak didukung. Perilaku saat ini juga membuat mode tampilan baru tidak dapat diperkenalkan dengan cara yang kompatibel dengan versi lama, karena tidak memiliki tempat dalam rantai penggantian.

Anda dapat menetapkan urutan penggantian Anda sendiri menggunakan properti display_override, yang dipertimbangkan browser sebelum properti display. Nilainya adalah urutan string yang dipertimbangkan dalam urutan yang tercantum, dan mode tampilan pertama yang didukung akan diterapkan. Jika tidak ada yang didukung, browser akan kembali mengevaluasi kolom display. Jika tidak ada kolom display, browser akan mengabaikan display_override.

Berikut adalah contoh cara menggunakan display_override. Detail "window-control-overlay" berada di luar cakupan 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, nilai akan kembali ke "minimal-ui", lalu ke "standalone" dari properti display. Jika tidak ada yang tersedia, browser akan 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 menyertakan semua titik masuk dan keluar ke aplikasi, dan browser menggunakannya untuk menentukan kapan pengguna telah keluar dari aplikasi.

Beberapa catatan lainnya tentang scope:

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

theme_color

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

theme_color dalam kueri media

Anda dapat menyesuaikan theme_color dalam kueri media menggunakan atribut media dari elemen warna tema meta. Misalnya, Anda dapat menentukan satu warna untuk mode terang dan warna lain untuk mode gelap dengan cara ini. Namun, Anda tidak dapat menentukan preferensi ini dalam manifes. Untuk mengetahui 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 objek pintasan aplikasi yang memberikan 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 maksimal tujuh baris teks.

screenshots

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

Di Chrome, gambar harus memenuhi kriteria berikut:

• Lebar dan tinggi harus minimal 320 piksel dan maksimal 3840 piksel.
• Dimensi maksimum tidak boleh lebih dari 2,3 kali panjang dimensi minimum.
• Semua screenshot yang cocok dengan faktor bentuk yang sesuai harus memiliki rasio aspek yang sama.
  • Mulai Chrome 109, hanya screenshot dengan form_factor yang ditetapkan ke "wide" yang akan ditampilkan di desktop.
• Mulai Chrome 109, screenshot dengan form_factor yang ditetapkan ke "wide" akan diabaikan di Android. Screenshot tanpa form_factor masih 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. Sisanya akan diabaikan.

Menambahkan manifes aplikasi web ke halaman Anda

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

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

Menguji manifes

Untuk memverifikasi bahwa manifes Anda disiapkan dengan benar, gunakan panel Manifes di panel Aplikasi Chrome DevTools.

Panel ini menyediakan versi properti manifes yang mudah dibaca, dan memungkinkan Anda memverifikasi bahwa semua gambar dimuat dengan benar.

Layar pembuka di perangkat seluler

Saat aplikasi pertama kali diluncurkan di perangkat seluler, perlu waktu beberapa saat bagi browser untuk memulai dan konten awal mulai merender. Alih-alih menampilkan layar putih yang dapat membuat pengguna mengira bahwa aplikasi tidak berfungsi, browser menampilkan layar pembuka hingga penggambaran pertama.

Chrome otomatis membuat layar pembuka dari name, background_color, dan icons yang ditentukan dalam manifes Anda. Untuk membuat transisi yang lancar dari layar pembuka ke aplikasi, buat background_color berwarna sama dengan halaman pemuatan.

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

Bacaan lebih lanjut

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