Manifes aplikasi web adalah file JSON yang memberi tahu browser tentang perilaku Progressive Web App (PWA) Anda saat diinstal di perangkat desktop atau seluler pengguna. Setidaknya, file manifes standar menyertakan:
- Nama aplikasi
- Ikon yang harus digunakan aplikasi
- URL yang harus dibuka saat aplikasi diluncurkan
Membuat file manifes
File manifes dapat memiliki nama apa pun, tetapi biasanya bernama manifest.json
dan
disalurkan dari root (direktori level teratas situs Anda). Spesifikasi ini
menyarankan bahwa ekstensi harus berupa .webmanifest
, tetapi Anda dapat menggunakan file JSON
agar manifes Anda lebih jelas untuk dibaca.
Manifes umumnya 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. Jika
Anda menyediakan keduanya, name
akan digunakan saat aplikasi diinstal, dan short_name
akan digunakan di layar utama, peluncur, atau tempat lain dengan ruang
terbatas.
icons
Saat pengguna menginstal PWA, Anda dapat menentukan serangkaian ikon untuk browser agar digunakan di layar utama, peluncur aplikasi, pengalih tugas, layar pembuka, dan di tempat lainnya.
Properti icons
adalah array objek gambar. Setiap objek harus
menyertakan src
, properti sizes
, dan type
gambar. Untuk menggunakan
ikon maskable, yang terkadang disebut sebagai ikon
adaptif di Android, tambahkan "purpose": "any maskable"
ke properti icon
.
Untuk Chromium, Anda harus menyediakan setidaknya ikon berukuran 192x192 piksel dan ikon 512x512 piksel. Jika hanya dua ukuran ikon tersebut yang disediakan, Chrome akan otomatis menskalakan ikon agar sesuai dengan perangkat. Jika Anda memilih untuk menskalakan ikon sendiri dan menyesuaikannya untuk kesempurnaan piksel, berikan ikon dengan kelipatan 48 dp.
id
Properti id
memungkinkan Anda menentukan secara eksplisit ID yang digunakan untuk
aplikasi Anda. Menambahkan properti id
ke manifes akan menghapus dependensi pada start_url
atau lokasi manifes, dan memungkinkan pembaruannya di masa mendatang. Untuk informasi selengkapnya, lihat
Mengidentifikasi PWA secara unik dengan properti ID manifes aplikasi web.
start_url
start_url
adalah properti yang wajib ada. Atribut 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 ke layar utama.
start_url
harus mengarahkan pengguna langsung ke aplikasi Anda, bukan halaman landing produk. Pikirkan tentang 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 diluncurkan dalam layar penuh. Properti display
menggunakan salah satu nilai berikut:
Properti | Perilaku |
---|---|
fullscreen |
Membuka aplikasi web tanpa UI browser apa pun 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 elemen UI browser standar seperti kolom URL. |
minimal-ui |
Mode ini mirip dengan standalone , tetapi memberi pengguna set 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 perlu mendukung semua mode
tampilan, tetapi diperlukan untuk 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 tersebut. 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 mode tersebut tidak memiliki tempat di rantai penggantian.
Anda dapat menetapkan urutan penggantian sendiri menggunakan properti display_override
,
yang dipertimbangkan browser sebelum properti display
. Nilainya adalah
urutan string yang dipertimbangkan dalam urutan yang tercantum, dan mode tampilan
yang didukung pertama akan diterapkan. Jika tidak ada yang didukung, browser akan kembali
untuk 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, opsi ini 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 mencakup semua titik masuk dan keluar ke aplikasi, dan browser menggunakannya untuk menentukan kapan pengguna keluar dari aplikasi.
Beberapa catatan lain tentang scope
:
- Jika Anda tidak menyertakan
scope
dalam manifes,scope
tersirat default adalah URL awal, tetapi nama file, kueri, dan fragmennya dihapus. - Atribut
scope
dapat berupa jalur relatif (../
), atau jalur tingkat lebih tinggi (/
) yang akan memungkinkan peningkatan cakupan navigasi di aplikasi web Anda. start_url
harus berada dalam cakupan.start_url
relatif terhadap jalur yang ditentukan dalam atributscope
.start_url
yang dimulai dengan/
akan selalu menjadi root asal.
theme_color
theme_color
menetapkan warna toolbar, dan dapat ditampilkan dalam
pratinjau aplikasi di pengalih tugas. theme_color
harus cocok dengan
warna tema meta
yang ditentukan di head 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/manifest#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 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 dalam skenario penggunaan umum. Setiap objek harus menyertakan src
, properti sizes
, dan type
gambar. Properti form_factor
bersifat opsional.
Anda dapat menetapkannya ke "wide"
untuk screenshot yang hanya berlaku untuk
layar lebar atau "narrow"
untuk screenshot sempit saja.
Di Chrome, gambar harus memenuhi kriteria berikut:
- Lebar dan tinggi setidaknya harus 320 px dan maksimal 3.840 px.
- 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 disetel ke"wide"
yang ditampilkan di desktop.
- Mulai Chrome 109, hanya screenshot dengan
- Mulai Chrome 109, screenshot dengan
form_factor
yang ditetapkan ke"wide"
akan diabaikan di Android. Screenshot tanpaform_factor
masih ditampilkan untuk kompatibilitas mundur.
Chrome di desktop menampilkan minimal satu dan maksimal delapan screenshot yang memenuhi kriteria ini. Sisanya 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
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 sudah disiapkan dengan benar, gunakan panel Manifest di panel Application pada Chrome DevTools.
Panel ini menyediakan versi berbagai properti manifes yang dapat dibaca manusia dan memungkinkan Anda memverifikasi bahwa semua gambar dimuat dengan benar.
Layar pembuka di perangkat seluler
Saat aplikasi Anda pertama kali diluncurkan di perangkat seluler, perlu waktu beberapa saat agar browser memulai dan konten awal untuk memulai rendering. Alih-alih menampilkan layar putih yang mungkin membuat pengguna berpikir bahwa aplikasi tersebut tidak berfungsi, browser menampilkan layar pembuka hingga paint 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
menggunakan
warna yang sama dengan halaman pemuatan.
Chrome memilih ikon yang paling sesuai dengan resolusi perangkat untuk layar pembuka. Menyediakan ikon berukuran 192 piksel dan 512 piksel 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 MN.