PWA sebagai Pengendali URL

Izinkan PWA yang diinstal menangani URL untuk memberikan pengalaman yang lebih terintegrasi.

Thomas Steiner

Apa yang dimaksud dengan PWA sebagai Pengendali URL?

Bayangkan Anda sedang mengobrol dengan teman menggunakan aplikasi pesan instan seperti Messages di macOS dan Anda sedang membicarakan musik. Bayangkan juga Anda berdua telah menginstal PWA music.example.com di perangkat Anda. Jika ingin membagikan lagu favorit agar teman Anda dapat menikmatinya, Anda dapat mengirimkan deep link seperti https://music.example.com/rick-astley/never-gonna-give-you-up. Karena link ini cukup panjang, developer music.example.com mungkin telah memutuskan untuk menambahkan link pendek tambahan ke setiap lagu, misalnya, https://🎵.example.com/r-a/n-g-g-y-u.

PWA sebagai Pengendali URL memungkinkan aplikasi seperti music.example.com mendaftarkan diri sebagai pengendali URL untuk URL yang cocok dengan pola seperti https://music.example.com, https://*.music.example.com, atau https://🎵.example.com, sehingga link dari luar PWA, misalnya, dari aplikasi pesan instan atau program email, akan terbuka di PWA yang diinstal, bukan di tab browser.

PWA sebagai Pengendali URL terdiri dari dua tambahan:

  1. Anggota manifes aplikasi web "url_handlers".
  2. Format file web-app-origin-association untuk memvalidasi pengaitan URL dalam dan di luar cakupan.

Kasus penggunaan yang disarankan untuk PWA sebagai Pengendali URL

Contoh situs yang mungkin menggunakan API ini meliputi:

  • Situs streaming musik atau video sehingga link lagu atau link playlist terbuka di pengalaman pemutar aplikasi.
  • Pembaca berita atau RSS sehingga situs yang diikuti atau di-subscribe akan terbuka dalam mode pembaca aplikasi.

Cara menggunakan PWA sebagai Pengendali URL

Mengaktifkan dengan about://flags

Untuk bereksperimen dengan PWA sebagai pengendali URL secara lokal, tanpa token uji coba origin, aktifkan flag #enable-desktop-pwas-url-handling di about://flags.

Anggota manifes aplikasi web "url_handlers"

Untuk mengaitkan PWA yang diinstal dengan pola URL, pola ini harus ditentukan dalam manifes aplikasi web. Hal ini terjadi melalui anggota "url_handlers". Fungsi ini menerima array objek dengan properti origin, yang merupakan string wajib yang merupakan pola untuk mencocokkan origin. Pola ini diizinkan memiliki awalan karakter pengganti (*) untuk menyertakan beberapa subdomain (seperti https://*.example.com). URL yang cocok dengan origin ini dapat ditangani oleh aplikasi web ini. Skema ini selalu diasumsikan sebagai https://, tetapi harus disebutkan secara eksplisit.

Cuplikan manifes aplikasi web berikut menunjukkan cara contoh PWA musik dari paragraf pengantar dapat menyiapkan hal ini. Entri kedua dengan karakter pengganti ("https://*.music.example.com") memastikan bahwa aplikasi juga diaktifkan untuk https://www.music.example.com atau contoh potensial lainnya seperti https://marketing-activity.music.example.com.

{
  "url_handlers": [
    {
      "origin": "https://music.example.com"
    },
    {
      "origin": "https://*.music.example.com"
    },
    {
      "origin": "https://🎵.example.com"
    }
  ]
}

File web-app-origin-association

Karena PWA berada di origin yang berbeda (music.example.com) dari beberapa URL yang perlu ditanganinya (misalnya, https://🎵.example.com), aplikasi perlu memverifikasi kepemilikan origin lain ini. Hal ini terjadi dalam file web-app-origin-association yang dihosting di origin lain.

File ini harus berisi JSON yang valid. Struktur tingkat teratas adalah objek, dengan anggota bernama "web_apps". Anggota ini adalah array objek dan setiap objek mewakili entri untuk aplikasi web unik. Setiap objek berisi:

Kolom Deskripsi Jenis Default
"manifest" (Wajib) String URL manifes aplikasi web dari PWA terkait string T/A
"details" (Opsional) Objek yang berisi array pola URL yang disertakan dan dikecualikan object T/A

Setiap objek "details" berisi:

Kolom Deskripsi Jenis Default
"paths" (Opsional) Array string jalur yang diizinkan string[] []
"exclude_paths" (Opsional) Array string jalur yang tidak diizinkan string[] []

Contoh file web-app-origin-association untuk contoh PWA musik dari atas diberikan di bawah ini. File ini akan dihosting di origin 🎵.example.com dan membuat pengaitan dengan PWA music.example.com, yang diidentifikasi oleh URL manifes aplikasi webnya.

{
  "web_apps": [
    {
      "manifest": "https://music.example.com/manifest.json",
      "details": {
        "paths": ["/*"],
        "exclude_paths": ["/internal/*"]
      }
    }
  ]
}

Kapan URL cocok?

PWA cocok dengan URL untuk penanganan jika kedua kondisi berikut terpenuhi:

  • URL cocok dengan salah satu string origin di "url_handlers".
  • Browser dapat memvalidasi menggunakan file web-app-origin-association masing-masing bahwa setiap origin setuju untuk mengizinkan aplikasi ini menangani URL tersebut.

Mengenai penemuan file web-app-origin-association

Agar browser dapat menemukan file web-app-origin-association, developer harus menempatkan file web-app-origin-association di folder /.well-known/ di root aplikasi. Agar berfungsi, nama file harus sama persis dengan web-app-origin-association.

Demo

Untuk menguji PWA sebagai Pengendali URL, pastikan untuk menyetel flag browser seperti yang diuraikan, lalu instal PWA di https://mandymsft.github.io/pwa/. Dengan melihat manifes aplikasi webnya, Anda dapat melihat bahwa aplikasi tersebut menangani URL dengan pola URL berikut: https://mandymsft.github.io dan https://luhuangmsft.github.io. Karena yang terakhir berada di origin yang berbeda (luhuangmsft.github.io) daripada PWA, PWA di mandymsft.github.io perlu membuktikan kepemilikan, yang terjadi menggunakan file web-app-origin-association yang dihosting di https://luhuangmsft.github.io/.well-known/web-app-origin-association.

Untuk menguji apakah fitur ini benar-benar berfungsi, kirim pesan pengujian kepada diri sendiri menggunakan aplikasi pesan instan pilihan Anda atau email yang dilihat di program email yang tidak berbasis web seperti Mail di macOS. Email atau pesan teks harus berisi link https://mandymsft.github.io atau https://luhuangmsft.github.io. Keduanya akan terbuka di PWA yang diinstal.

Aplikasi pesan instan Skype Windows di samping PWA demo yang diinstal, yang dibuka dalam mode mandiri setelah mengklik link yang ditangani olehnya dalam pesan chat Skype.

Keamanan dan izin

Tim Chromium merancang dan menerapkan PWA sebagai Pengendali URL menggunakan prinsip inti yang ditentukan dalam Mengontrol Akses ke Fitur Platform Web yang Andal, termasuk kontrol, transparansi, dan ergonomi pengguna.

Kontrol pengguna

Jika lebih dari satu PWA mendaftar sebagai pengendali URL untuk pola URL tertentu, pengguna akan diminta untuk memilih PWA yang ingin mereka gunakan untuk menangani pola tersebut—jika ada. Navigasi yang dimulai di tab browser tidak ditangani oleh proposal ini, karena proposal ini secara eksplisit ditujukan untuk navigasi yang dimulai di luar browser.

Transparansi

Jika validasi pengaitan yang diperlukan tidak dapat diselesaikan dengan berhasil selama penginstalan PWA karena alasan apa pun, browser tidak akan mendaftarkan aplikasi sebagai pengendali URL aktif untuk URL yang terpengaruh. Pengendali URL, jika tidak diterapkan dengan benar, dapat digunakan untuk membajak traffic situs. Inilah alasan mekanisme pengaitan aplikasi menjadi bagian penting dari skema ini.

Aplikasi khusus platform sudah dapat menggunakan API sistem operasi untuk menghitung aplikasi yang diinstal di sistem pengguna. Misalnya, aplikasi di Windows dapat menggunakan API FindAppUriHandlersAsync untuk menghitung pengendali URL. Jika PWA mendaftar sebagai pengendali URL tingkat OS di Windows, keberadaannya akan terlihat oleh aplikasi lain.

Persistensi izin

Origin dapat mengubah kaitannya dengan PWA kapan saja. Browser akan secara rutin mencoba memvalidasi ulang pengaitan aplikasi web yang diinstal. Jika pendaftaran pengendali URL gagal divalidasi ulang karena data pengaitan telah berubah atau tidak lagi tersedia, browser akan menghapus pendaftaran.

Masukan

Tim Chromium ingin mendengar pengalaman Anda terkait PWA sebagai Pengendali URL.

Beri tahu kami tentang desain API

Apakah ada sesuatu tentang API yang tidak berfungsi seperti yang Anda harapkan? Atau apakah ada metode atau properti yang tidak ada yang Anda perlukan untuk mengimplementasikan ide Anda? Ada pertanyaan atau komentar tentang model keamanan? Laporkan masalah spesifikasi di repo GitHub yang sesuai, atau tambahkan pendapat Anda ke masalah yang ada.

Melaporkan masalah terkait penerapan

Apakah Anda menemukan bug pada penerapan Chromium? Atau apakah penerapannya berbeda dengan spesifikasi? Laporkan bug di new.crbug.com. Pastikan untuk menyertakan detail sebanyak mungkin, petunjuk untuk mereproduksi, dan masukkan UI>Browser>WebAppInstalls di kotak Components.

Menunjukkan dukungan untuk API

Apakah Anda berencana menggunakan PWA sebagai Pengendali URL? Dukungan publik Anda membantu tim Chromium memprioritaskan fitur dan menunjukkan kepada vendor browser lain betapa pentingnya mendukung fitur tersebut.

Kirim tweet ke @ChromiumDev menggunakan hashtag #URLHandlers dan beri tahu kami di mana dan bagaimana Anda menggunakannya.

Link bermanfaat

Ucapan terima kasih

PWA sebagai Pengendali URL ditentukan dan diimplementasikan oleh Lu Huang dan Mandy Chen dari tim Microsoft Edge. Dokumen ini ditinjau oleh Joe Medley.