Menambahkan manifes aplikasi web

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

Dukungan Browser

• 39
• 79
• x
• x

Sumber

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.

Catatan: Sistem operasi biasanya memerlukan judul untuk setiap jendela aplikasi. Judul ini ditampilkan di berbagai platform pengalihan jendela seperti alt+tab, mode ringkasan, dan daftar jendela rak. Untuk PWA yang berjalan dalam mode mandiri, Chromium akan menambahkan short_name (atau, jika tidak tersedia, name) ke awal <title> dokumen HTML untuk mencegah serangan samaran ketika aplikasi mandiri mungkin mencoba salah dipahami, misalnya, untuk dialog sistem operasi. Untuk membantu menjaga keamanan aplikasi Anda, jangan ulangi nama aplikasi di <title> untuk mode mandiri.

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.

Catatan: Browser berbasis Chromium juga mendukung ikon SVG yang dapat diskalakan secara arbitrer tanpa terlihat pecah dan yang mendukung fitur lanjutan seperti responsivitas terhadap prefers-color-scheme. Namun, ikon ini tetap dalam status seperti pada saat penginstalan, bukan diupdate secara langsung. Agar dapat menggunakan ikon SVG dengan aman, selalu tentukan ikon raster sebagai penggantian untuk browser yang tidak mendukung ikon SVG.

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. UI mandiri.
minimal-ui	Mode ini mirip dengan standalone, tetapi memberi pengguna set elemen UI minimal untuk mengontrol navigasi, seperti tombol kembali dan muat ulang. UI minimal.
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.

Perhatian: Jika pengguna mengklik link di aplikasi Anda yang membuka scope, link akan terbuka dan dirender dalam jendela PWA yang ada. Jika Anda ingin link terbuka di tab browser, tambahkan target="_blank" ke tag <a>. Di Android, link dengan target="_blank" akan terbuka di Tab Khusus Chrome.

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 atribut scope.
• 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.

Contoh jendela PWA dengan theme_color kustom.

theme_color dalam kueri media

Dukungan Browser

• 93
• 93
• 106
• 15

Sumber

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, 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. Sisanya akan diabaikan.

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

UI penginstalan yang lebih lengkap di desktop dan seluler.

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">

Permintaan untuk manifes dibuat tanpa kredensial, meskipun berada di domain yang sama. Jika manifes memerlukan kredensial, Anda harus menyertakan crossorigin="use-credentials" di tag manifes.

Menguji manifes

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

Uji manifes Anda di 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.