Czy aplikacja jest zainstalowana? Odpowiedź znajdziesz w interfejsie Get Installed Related Apps API.

Pete LePage

Alexey Rodionov

Interfejs Get Installed Related Apps API umożliwia pobranie listy zainstalowanych powiązanych aplikacji wraz z informacjami o nich.

Umożliwia sprawdzenie, czy progresywna aplikacja internetowa (PWA), aplikacja na Androida lub aplikacja na platformę uniwersalną systemu Windows (UWP) jest zainstalowana na bieżącym urządzeniu – zarówno z poziomu samej PWA, jak i powiązanej strony internetowej (np. witryny marketingowej produktu).

Bubblewrap to zestaw bibliotek open source i narzędzie wiersza poleceń (CLI) dla Node.js. Bubblewrap został opracowany przez zespół Google Chrome, aby pomóc deweloperom generować, tworzyć i podpisywać projekty na Androida, które uruchamiają PWA jako Trusted Web Activity (TWA).

PWABuilder to projekt open source opracowany przez Microsoft, który umożliwia deweloperom pakowanie i podpisywanie progresywnych aplikacji internetowych w celu publikowania ich w różnych sklepach, w tym Microsoft Store, Sklepie Google Play, App Store i Meta Quest Store. Wystarczy wpisać adres URL PWA, wprowadzić lub edytować metadane aplikacji i kliknąć przycisk „Wygeneruj”.

PWABuilder używa Bubblewrap do pakowania PWA na Androida i ChromeOS.

Jeśli aplikacja jest już zainstalowana, możesz dostosować wrażenia użytkowników.

Na przykład:

• Nie promuje instalacji Twojej progresywnej aplikacji internetowej, jeśli inna aplikacja jest już zainstalowana.
• przekierowywanie użytkownika z witryny marketingowej produktu bezpośrednio do aplikacji;
• skupienie niektórych funkcji, takich jak powiadomienia, w innej aplikacji, aby zapobiec powielaniu powiadomień;

Aby użyć interfejsu Get Installed Related Apps API, musisz poinformować aplikację o swojej stronie, a stronę o aplikacji. Po określeniu relacji między nimi możesz sprawdzić, czy powiązana aplikacja jest zainstalowana.

Aby zapobiec testowaniu przez witryny zbyt szerokiego zestawu własnych aplikacji, pod uwagę będą brane tylko 3 pierwsze aplikacje zadeklarowane w manifeście aplikacji internetowej.

Podobnie jak większość innych zaawansowanych interfejsów API sieci, interfejs Get Installed Related Apps jest dostępny tylko w przypadku połączenia HTTPS.

Czym jest interfejs Get Installed Related Apps API?

Wywołanie asynchronicznej metody navigator.getInstalledRelatedApps() zwraca obietnicę, która jest realizowana za pomocą tablicy obiektów zawierających szczegóły aplikacji, które:

• zainstalowana na bieżącym urządzeniu,
• zdefiniowany w polu related_applications pliku manifestu aplikacji internetowej,
• musi mieć zweryfikowaną relację ze stroną, na której wywoływana jest metoda navigator.getInstalledRelatedApps() (szczegóły znajdziesz w kolejnych sekcjach).

const installedRelatedApps = await navigator.getInstalledRelatedApps?.();

Wywołanie console.log(installedRelatedApps) zwraca wartość podobną do tej:

[
  {
    platform: "webapp",
    id: "https://example.com/?utm_source=home_screen",
    url: "https://example.com/manifest.json"
  },
  {
    platform: "play",
    id: "com.example.twa",
    url: "https://play.google.com/store/apps/details?id=com.example.twa",
    version: "0.1.0"
  }
]

Aby na przykład sprawdzić, czy na urządzeniu użytkownika są zainstalowane powiązane aplikacje, możesz użyć tego jednolinijkowego kodu:

const hasInstalledRelatedApps = !!(await navigator.getInstalledRelatedApps?.())?.length;

Jeśli znasz identyfikator pakietu, aby uzyskać numer wersji zainstalowanej powiązanej aplikacji na Androida, możesz użyć tego polecenia:

const installedRelatedAndroidAppVersion = (await navigator.getInstalledRelatedApps?.())?.find(app => app.id === 'com.example.twa')?.version;

Oznacza to, że metoda navigator.getInstalledRelatedApps() nadal będzie zwracać zainstalowane powiązane aplikacje, nawet jeśli ich wersja jest niższa niż min_version lub ich certyfikat podpisu nie pasuje do żadnego z fingerprints zadeklarowanych w polu related_applications manifestu aplikacji internetowej.

Obsługiwane typy aplikacji, które możesz sprawdzić

Sprawdzanie, czy aplikacja na Androida jest zainstalowana

Witryna może sprawdzić, czy aplikacja na Androida jest zainstalowana.

Tylko Android: Chrome 80 lub nowszy

Informowanie aplikacji na Androida o witrynie

Najpierw musisz zaktualizować aplikację na Androida, aby zdefiniować relację między witryną a aplikacją na Androida za pomocą systemu Digital Asset Links. Dzięki temu tylko Twoja witryna może sprawdzać, czy aplikacja na Androida jest zainstalowana.

W AndroidManifest.xml aplikacji na Androida dodaj wpis asset_statements:

<manifest>
  <application>
   …
    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
   …
  </application>
</manifest>

Następnie w strings.xml dodaj to oświadczenie o zasobach, zastępując site swoją domeną. Pamiętaj, aby uwzględnić znaki ucieczki.

<string name="asset_statements">
  [{
    \"relation\": [\"delegate_permission/common.handle_all_urls\"],
    \"target\": {
      \"namespace\": \"web\",
      \"site\": \"https://example.com\"
    }
  }]
</string>

Po zakończeniu instalacji zaktualizuj aplikację na urządzeniu lub opublikuj ją w Sklepie Google Play albo na innej platformie dystrybucji aplikacji na Androida.

Informowanie witryny o aplikacji na Androida

Następnie poinformuj witrynę o aplikacji na Androida, dodając do strony plik manifestu aplikacji internetowej. Plik manifestu musi zawierać właściwość related_applications, czyli tablicę z informacjami o aplikacji, w tym platform i id.

• Wartość platform musi wynosić play
• id to identyfikator pakietu na Androida.

{
  "related_applications": [{
    "platform": "play",
    "id": "com.android.chrome"
  }]
}

Sprawdzanie, czy aplikacja jest zainstalowana

Na koniec wywołaj funkcję asynchroniczną navigator.getInstalledRelatedApps(), aby sprawdzić, czy aplikacja na Androida jest zainstalowana.

Sprawdzanie, czy aplikacja na Windowsa (UWP) jest zainstalowana

Twoja witryna może sprawdzić, czy aplikacja na Windowsa (utworzona za pomocą platformy UWP) jest zainstalowana.

Tylko Windows: Chrome 85 lub nowszy, Edge 85 lub nowszy

Informowanie aplikacji na Windows o witrynie

Musisz zaktualizować aplikację na Windowsa, aby zdefiniować relację między witryną a aplikacją na Windowsa za pomocą programów obsługi URI. Dzięki temu tylko Twoja witryna może sprawdzać, czy aplikacja na Windowsa jest zainstalowana.

Dodaj rejestrację rozszerzenia Windows.appUriHandler do pliku manifestu aplikacji Package.appxmanifest. Jeśli na przykład adres Twojej witryny to example.com, w manifeście aplikacji dodaj ten wpis:

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

Pamiętaj, że do atrybutu <Package> może być konieczne dodanie uap3 przestrzeni nazw.

Następnie utwórz plik JSON (bez rozszerzenia .json) o nazwie windows-app-web-link i podaj nazwę rodziny pakietów aplikacji. Umieść ten plik w katalogu głównym serwera lub w katalogu /.well-known/. Nazwę rodziny pakietów znajdziesz w sekcji Pakowanie w projektancie pliku manifestu aplikacji.

[{
  "packageFamilyName": "MyApp_9jmtgj1pbbz6e",
  "paths": [ "*" ]
}]

Szczegółowe informacje o konfigurowaniu modułów obsługi identyfikatorów URI znajdziesz w artykule Włączanie aplikacji w witrynach za pomocą modułów obsługi identyfikatorów URI aplikacji.

Informowanie witryny o aplikacji na Windows

Następnie poinformuj swoją witrynę o aplikacji na Windowsa, dodając do strony plik manifestu aplikacji internetowej. Plik manifestu musi zawierać właściwość related_applications, czyli tablicę zawierającą szczegółowe informacje o aplikacji, w tym platform i id.

• Wartość platform musi wynosić windows
• id to nazwa rodziny pakietów aplikacji z dodaną wartością <Application> Id z pliku Package.appxmanifest.

{
  "related_applications": [{
    "platform": "windows",
    "id": "MyApp_9jmtgj1pbbz6e!App"
  }]
}

Sprawdzanie, czy aplikacja jest zainstalowana

Na koniec wywołaj funkcję asynchroniczną navigator.getInstalledRelatedApps(), aby sprawdzić, czy aplikacja na Windowsa jest zainstalowana.

Zapoznaj się z tą prezentacją.

Sprawdzanie, czy progresywna aplikacja internetowa jest już zainstalowana (w zakresie)

Twoja PWA może sprawdzić, czy jest już zainstalowana. W takim przypadku strona wysyłająca żądanie musi znajdować się w tej samej domenie i w zakresie Twojej progresywnej aplikacji internetowej, zgodnie z zakresem zdefiniowanym w pliku manifestu aplikacji internetowej.

Obsługiwane na:

Android: Chrome 84 lub nowszy

Komputer (Windows, macOS, Linux, ChromeOS): Chrome 140 lub nowszy, Edge 140 lub nowszy

Informowanie PWA o sobie

Poinformuj aplikację PWA o sobie, dodając wpis related_applications do jej pliku manifestu aplikacji internetowej.

• Wartość platform musi wynosić webapp
• url to ścieżka (może być względna) do pliku manifestu aplikacji internetowej PWA.
• id to identyfikator aplikacji internetowej zadeklarowany w polu id w manifeście aplikacji internetowej lub obliczony przez przeglądarkę (wymagany na komputerach, niepotrzebny na Androidzie).

{
  …
  "scope": "/",
  "start_url": "/?utm_source=home_screen",
  "related_applications": [{
    "platform": "webapp",
    "url": "/manifest.json",
    "id": "https://example.com/?utm_source=home_screen"
  }],
  …
}

Sprawdzanie, czy PWA jest zainstalowana

Na koniec wywołaj funkcję asynchroniczną navigator.getInstalledRelatedApps() w zakresie progresywnej aplikacji internetowej, aby sprawdzić, czy jest ona zainstalowana. Jeśli funkcja navigator.getInstalledRelatedApps() zostanie wywołana poza zakresem Twojej progresywnej aplikacji internetowej, zwróci wartość []. Więcej informacji na ten temat można znaleźć w następnej sekcji.

Sprawdzanie, czy progresywna aplikacja internetowa jest zainstalowana (poza zakresem)

Twoja witryna może sprawdzić, czy aplikacja PWA jest zainstalowana, nawet jeśli strona znajduje się poza zakresem aplikacji PWA. Na przykład strona docelowa wyświetlana z domeny /landing/ może sprawdzić, czy zainstalowana jest progresywna aplikacja internetowa wyświetlana z domeny /pwa/. Może też sprawdzić, czy strona docelowa jest wyświetlana z domeny www.example.com, a progresywna aplikacja internetowa z domeny app.example.com.

Obsługiwane na:

Tylko Android: Chrome 84 lub nowsza

Informowanie PWA o witrynie

Najpierw musisz dodać linki do zasobów cyfrowych na serwerze, z którego jest obsługiwana Twoja aplikacja PWA. Pomoże to określić relację między Twoją witryną a progresywną aplikacją internetową i zweryfikować, że tylko Twoja witryna może sprawdzać, czy aplikacja jest zainstalowana.

Dodaj plik assetlinks.json do katalogu /.well-known/ domeny, w której znajduje się PWA, np. app.example.com. W usłudze site podaj pełną ścieżkę do manifestu aplikacji internetowej, która będzie przeprowadzać weryfikację (nie do manifestu aplikacji PWA).

// Served from https://app.example.com/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.query_webapk"],
    "target": {
      "namespace": "web",
      "site": "https://www.example.com/manifest.json"
    }
  }
]

Następnie poinformuj witrynę o aplikacji PWA, dodając do strony plik manifestu aplikacji internetowej. Plik manifestu musi zawierać właściwość related_applications, czyli tablicę zawierającą szczegóły dotyczące Twojej progresywnej aplikacji internetowej, w tym platform i url.

• Wartość platform musi wynosić webapp
• url to pełna ścieżka do pliku manifestu aplikacji internetowej PWA.

{
  "related_applications": [{
    "platform": "webapp",
    "url": "https://app.example.com/manifest.json"
  }]
}

Sprawdzanie, czy PWA jest zainstalowana

Na koniec wywołaj funkcję asynchroniczną navigator.getInstalledRelatedApps(), aby sprawdzić, czy PWA jest zainstalowana.

Nadal masz pytania?

Nadal masz pytania? Sprawdź tag getInstalledRelatedApps na StackOverflow, aby zobaczyć, czy ktoś inny nie zadał podobnych pytań. Jeśli nie, zadaj tam swoje pytanie i dodaj do niego tag progressive-web-apps. Nasz zespół często monitoruje ten tag i stara się odpowiadać na Twoje pytania.

Prześlij opinię

Czy w implementacji Chrome występuje błąd? A może implementacja różni się od specyfikacji?

• Zgłoś błąd na stronie https://new.crbug.com. Podaj jak najwięcej szczegółów, opisz, jak odtworzyć błąd, i w polu Komponenty wpisz Mobile>WebAPKs.

Przydatne linki

• Publiczne wyjaśnienie interfejsu Get Installed Related Apps API
• Wersja robocza specyfikacji
• Błąd śledzenia
• Wpis na ChromeStatus.com
• Komponent Blink: Mobile>WebAPKs

Dziękujemy

Specjalne podziękowania dla Sunggooka Chue z Microsoftu za pomoc w szczegółach dotyczących testowania aplikacji Windows oraz dla Rayana Kanso za pomoc w szczegółach dotyczących Chrome.