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.Możesz to zrobić zarówno z poziomu samej PWA, jak i z poziomu powiązanej strony internetowej (np. witryny marketingowej produktu).

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ń;

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 na przykład:

[
  {
    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;

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.

Obsługiwane w:

• 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 Windows (UWP) jest zainstalowana

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

Obsługiwane w:

• 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 w:

• 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 w:

• 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 progresywna aplikacja internetowa. 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 przeprowadzi 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"
    }
  }
]

Informowanie witryny o aplikacji PWA

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 miał 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 sprawach związanych z testowaniem aplikacji na Windowsa oraz dla Rayana Kanso za pomoc w sprawach związanych z Chrome.