Mengaktifkan aplikasi untuk situs web menggunakan handler URI aplikasi

  • Artikel

Aplikasi untuk Situs Web mengaitkan aplikasi Anda dengan situs web sehingga saat seseorang membuka tautan ke situs web Anda, aplikasi Anda diluncurkan alih-alih membuka browser. Jika aplikasi Anda tidak diinstal, situs web Anda akan terbuka di browser seperti biasa. Pengguna dapat mempercayai pengalaman ini karena hanya pemilik konten terverifikasi yang dapat mendaftar untuk tautan. Pengguna akan dapat memeriksa semua tautan web-ke-aplikasi yang terdaftar dengan membuka Pengaturan > Aplikasi Aplikasi > untuk situs web.

Untuk mengaktifkan penautan web-ke-aplikasi, Anda harus:

  • Mengidentifikasi URI yang akan ditangani aplikasi Anda dalam file manifes
  • File JSON yang menentukan hubungan antara aplikasi dan situs web Anda. dengan aplikasi Nama Keluarga Paket pada akar host yang sama dengan deklarasi manifes aplikasi.
  • Tangani aktivasi di aplikasi.

Catatan

Dimulai dengan pembaruan Windows 10 Creators, tautan yang didukung yang diklik di Lama Microsoft Edge akan meluncurkan aplikasi yang sesuai. Tautan yang didukung yang diklik di browser lain (misalnya, Microsoft Edge Chromium, Internet Explorer, dll.), akan membuat Anda tetap dalam pengalaman penjelajahan.

Aplikasi Anda perlu mengidentifikasi URI untuk situs web yang akan ditanganinya. Untuk melakukannya, tambahkan pendaftaran ekstensi Windows.appUriHandler ke file manifes aplikasi Anda Package.appxmanifest.

Misalnya, jika alamat situs web Anda adalah "msn.com" Anda akan membuat entri berikut dalam manifes aplikasi Anda:

<Applications>
  <Application ... >
      ...
      <Extensions>
         <uap3:Extension Category="windows.appUriHandler">
          <uap3:AppUriHandler>
            <uap3:Host Name="msn.com" />
          </uap3:AppUriHandler>
        </uap3:Extension>
      </Extensions>
  </Application>
</Applications>

Deklarasi di atas mendaftarkan aplikasi Anda untuk menangani tautan dari host yang ditentukan. Jika situs web Anda memiliki beberapa alamat (misalnya: m.example.com, www.example.com, dan example.com) tambahkan entri terpisah <uap3:Host Name=... /> di dalam <uap3:AppUriHandler> untuk setiap alamat.

Mengaitkan aplikasi dan situs web Anda dengan file JSON

Untuk memastikan bahwa hanya aplikasi yang dapat membuka konten di situs web Anda, sertakan nama keluarga paket aplikasi Anda dalam file JSON yang terletak di root server web, atau di direktori terkenal di domain. Ini menandakan bahwa situs web Anda memberikan persetujuan bagi aplikasi yang tercantum untuk membuka konten di situs Anda. Anda dapat menemukan nama keluarga paket di bagian Paket di perancang manifes aplikasi.

Penting

File JSON tidak boleh memiliki akhiran file .json.

Buat file JSON (tanpa ekstensi file .json) bernama windows-app-web-link dan berikan nama keluarga paket aplikasi Anda. Contohnya:

[{
  "packageFamilyName" : "Your app's package family name, e.g MyApp_9jmtgj1pbbz6e",
  "paths" : [ "*" ],
  "excludePaths" : [ "/news/*", "/blog/*" ]
 }]

Windows akan membuat koneksi https ke situs web Anda dan akan mencari file JSON yang sesuai di server web Anda.

Wildcard

Contoh file JSON di atas menunjukkan penggunaan wildcard. Wildcard memungkinkan Anda mendukung berbagai tautan dengan lebih sedikit baris kode. Penautan web-ke-aplikasi mendukung dua jenis kartubebas dalam file JSON:

Kartubebas Deskripsi
* Mewakili substring apa pun
? Mewakili satu karakter

Misalnya, yang diberikan "excludePaths" : [ "/news/*", "/blog/*" ] dalam contoh di atas, aplikasi Anda akan mendukung semua jalur yang dimulai dengan alamat situs web Anda (misalnya, msn.com), kecuali yang ada di bawah /news/ dan /blog/. msn.com/weather.html akan didukung, tetapi tidak msn.com/news/topnews.html.

Beberapa aplikasi

Jika Anda memiliki dua aplikasi yang ingin Anda tautkan ke situs web Anda, cantumkan kedua nama keluarga paket aplikasi di file JSON windows-app-web-link Anda. Kedua aplikasi dapat didukung. Pengguna akan disajikan dengan pilihan yang merupakan tautan default jika keduanya diinstal. Jika mereka ingin mengubah tautan default nanti, mereka dapat mengubahnya di Pengaturan > Aplikasi untuk Situs Web. Pengembang juga dapat mengubah file JSON kapan saja dan melihat perubahan sedini hari yang sama tetapi tidak lebih dari delapan hari setelah pembaruan.

[{
  "packageFamilyName": "Your apps's package family name, e.g MyApp_9jmtgj1pbbz6e",
  "paths": [ "*" ],
  "excludePaths" : [ "/news/*", "/blog/*" ]
 },
 {
  "packageFamilyName": "Your second app's package family name, for example, MyApp2_8jmtgj2pbbz6e",
  "paths": [ "/example/*", "/links/*" ]
 }]

Untuk memberikan pengalaman terbaik bagi pengguna Anda, gunakan jalur pengecualian untuk memastikan bahwa konten online saja dikecualikan dari jalur yang didukung dalam file JSON Anda.

Jalur pengecualian dicentang terlebih dahulu dan jika ada kecocokan, halaman yang sesuai akan dibuka dengan browser alih-alih aplikasi yang ditunjuk. Dalam contoh di atas, '/news/*' menyertakan halaman apa pun di bawah jalur tersebut sementara '/news*' (tidak ada jejak garis miring 'berita') mencakup jalur apa pun di bawah 'news*' seperti 'newslocal/', 'newsinternational/', dan sebagainya.

Menangani tautan pada Aktivasi untuk menautkan ke konten

Navigasi ke App.xaml.cs di solusi Visual Studio aplikasi Anda dan di OnActivated() tambahkan penanganan untuk konten yang ditautkan. Dalam contoh berikut, halaman yang dibuka di aplikasi bergantung pada jalur URI:

protected override void OnActivated(IActivatedEventArgs e)
{
    Frame rootFrame = Window.Current.Content as Frame;
    if (rootFrame == null)
    {
        ...
    }

    // Check ActivationKind, Parse URI, and Navigate user to content
    Type deepLinkPageType = typeof(MainPage);
    if (e.Kind == ActivationKind.Protocol)
    {
        var protocolArgs = (ProtocolActivatedEventArgs)e;        
        switch (protocolArgs.Uri.AbsolutePath)
        {
            case "/":
                break;
            case "/index.html":
                break;
            case "/sports.html":
                deepLinkPageType = typeof(SportsPage);
                break;
            case "/technology.html":
                deepLinkPageType = typeof(TechnologyPage);
                break;
            case "/business.html":
                deepLinkPageType = typeof(BusinessPage);
                break;
            case "/science.html":
                deepLinkPageType = typeof(SciencePage);
                break;
        }
    }

    if (rootFrame.Content == null)
    {
        // Default navigation
        rootFrame.Navigate(deepLinkPageType, e);
    }

    // Ensure the current window is active
    Window.Current.Activate();
}

Penting Pastikan untuk mengganti logika akhir if (rootFrame.Content == null) dengan rootFrame.Navigate(deepLinkPageType, e); seperti yang ditunjukkan pada contoh di atas.

Uji: Alat validasi lokal

Anda dapat menguji konfigurasi aplikasi dan situs web Anda dengan menjalankan alat pemverifikasi pendaftaran host aplikasi yang tersedia di:

%windir%\system32\AppHostRegistrationVerifier.exe

Uji konfigurasi aplikasi dan situs web Anda dengan menjalankan alat ini dengan parameter berikut:

AppHostRegistrationVerifier.exenama host packagefamilyname filepath

  • Nama host: Situs web Anda (misalnya, microsoft.com)
  • Nama Keluarga Paket (PFN): PFN aplikasi Anda
  • Jalur file: File JSON untuk validasi lokal (misalnya, C:\SomeFolder\windows-app-web-link)

Jika alat tidak mengembalikan apa pun, validasi akan berfungsi pada file tersebut saat diunggah. Jika ada kode kesalahan, kode tersebut tidak akan berfungsi.

Anda dapat mengaktifkan kunci registri berikut untuk memaksa pencocokan jalur untuk aplikasi yang dimuat di samping sebagai bagian dari validasi lokal:

HKCU\Software\Classes\LocalSettings\Software\Microsoft\Windows\CurrentVersion\ AppModel\SystemAppData\YourApp\AppUriHandlers

Nama kunci: ForceValidation Nilai: 1

Uji: Validasi web

Tutup aplikasi Anda untuk memverifikasi bahwa aplikasi diaktifkan saat Anda mengklik tautan. Kemudian, salin alamat salah satu jalur yang didukung di situs web Anda. Misalnya, jika alamat situs web Anda adalah "msn.com", dan salah satu jalur dukungan adalah "path1", Anda akan menggunakan http://msn.com/path1

Verifikasi bahwa aplikasi Anda ditutup. Tekan Tombol Windows + R untuk membuka kotak dialog Jalankan dan tempelkan tautan di jendela. Aplikasi Anda harus diluncurkan alih-alih browser web.

Selain itu, Anda dapat menguji aplikasi dengan meluncurkannya dari aplikasi lain menggunakan API LaunchUriAsync . Anda juga dapat menggunakan API ini untuk menguji ponsel.

Jika Anda ingin mengikuti logika aktivasi protokol, atur titik henti di penanganan aktivitas Aktif .

Tips AppUriHandlers:

  • Pastikan untuk hanya menentukan tautan yang dapat ditangani aplikasi Anda.
  • Cantumkan semua host yang akan Anda dukung. Perhatikan bahwa www.example.com dan example.com adalah host yang berbeda.
  • Pengguna dapat memilih aplikasi mana yang lebih mereka sukai untuk menangani situs web di Pengaturan.
  • File JSON Anda harus diunggah ke server https.
  • Jika Anda perlu mengubah jalur yang ingin didukung, Anda dapat menerbitkan ulang file JSON tanpa menerbitkan ulang aplikasi Anda. Pengguna akan melihat perubahan dalam 1-8 hari.
  • Semua aplikasi sideload dengan AppUriHandlers akan memiliki tautan yang divalidasi untuk host saat diinstal. Anda tidak perlu mengunggah file JSON untuk menguji fitur tersebut.
  • Fitur ini berfungsi setiap kali aplikasi Anda adalah aplikasi UWP yang diluncurkan dengan LaunchUriAsync atau aplikasi desktop Windows yang diluncurkan dengan ShellExecuteEx. Jika URL sesuai dengan handler URI Aplikasi terdaftar, aplikasi akan diluncurkan alih-alih browser.

Lihat juga

Contoh web-to-App proyekwindows.protocol registration Menangani sampel Peluncuran AsosiasiAktivasi URI menggambarkan cara menggunakan API LaunchUriAsync().