La tua app è installata? L'API Get Installed Related Apps ti dirà quali sono.

Pete LePage
Alexey Rodionov
Alexey Rodionov
X GitHub LinkedIn

L'API Get Installed Related Apps consente di ottenere l'elenco delle app correlate installate insieme ai relativi dettagli.

Consente di verificare se l'app web progressiva (PWA), l'app per Android o l'app Universal Windows Platform (UWP) è installata sul dispositivo corrente, sia dalla PWA stessa sia da una pagina web correlata (ad es. un sito web di marketing del prodotto).

Bubblewrap è un insieme open source di librerie e uno strumento a riga di comando (CLI) per Node.js. Bubblewrap è sviluppato dal team di Google Chrome per aiutare gli sviluppatori a generare, creare e firmare un progetto Android che avvii la tua PWA come Attività web attendibile (TWA).

PWABuilder è un progetto open source sviluppato da Microsoft che consente agli sviluppatori di creare pacchetti e firmare le proprie PWA per la pubblicazione su vari store, tra cui Microsoft Store, Google Play Store, App Store e Meta Quest Store, inserendo l'URL di una PWA, inserendo/modificando i metadati dell'app e facendo clic sul pulsante Genera.

PWABuilder utilizza Bubblewrap per creare pacchetti di PWA per Android e ChromeOS.

Se l'app è già installata, puoi personalizzare l'esperienza utente.

Ad esempio:

  • Non promuovere l'installazione della tua PWA se l'altra app è già installata.
  • Reindirizzamento dell'utente da un sito web di marketing del prodotto direttamente alla tua app.
  • Centralizzare alcune funzionalità, come le notifiche, nell'altra app per evitare notifiche duplicate.

Per utilizzare l'API Get Installed Related Apps, devi comunicare alla tua app la tua pagina e alla tua pagina la tua app. Una volta definita la relazione tra le due, puoi verificare se l'app correlata è installata.

Per impedire ai siti di testare un insieme eccessivamente ampio di proprie app, verranno prese in considerazione solo le prime tre app dichiarate nel file manifest dell'app web.

Come la maggior parte delle altre potenti API web, l'API Get Installed Related Apps è disponibile solo se pubblicata tramite HTTPS.

Che cos'è l'API Get Installed Related Apps?

La chiamata al metodo asincrono navigator.getInstalledRelatedApps() restituisce una promessa che viene risolta con un array di oggetti contenenti dettagli sulle app che:

  • installata sul dispositivo attuale,
  • definito nel campo related_applications del file manifest dell'app web,
  • avere una relazione verificata con una pagina in cui viene chiamato il metodo navigator.getInstalledRelatedApps() (per maggiori dettagli, consulta le sezioni successive).
const installedRelatedApps = await navigator.getInstalledRelatedApps?.();

La chiamata console.log(installedRelatedApps) restituisce un risultato simile a questo:

[
  {
    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"
  }
]

Ad esempio, per verificare se sono installate app correlate sul dispositivo dell'utente, puoi utilizzare il seguente comando di una sola riga:

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

Se conosci l'ID pacchetto, per ottenere il numero di versione dell'app Android correlata installata, puoi utilizzare il seguente comando:

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

Ciò significa che il metodo navigator.getInstalledRelatedApps() restituirà comunque le app correlate installate anche se la loro versione è precedente alla min_version o se il certificato di firma non corrisponde a nessun fingerprints dichiarato nel campo related_applications del manifest dell'app web.

Tipi di app supportati che puoi controllare

Tipo di app Controllabile da
App per Android Solo Android:
Chrome 80 o versioni successive
App Universal Windows Platform (UWP) Solo Windows:
Chrome 85 o versioni successive
Edge 85 o versioni successive
App web progressiva (PWA) installata nello stesso ambito sulla stessa origine Android:
Chrome 84 o versioni successive
Computer (Windows, macOS, Linux, ChromeOS):
Chrome 140 o versioni successive
Edge 140 o versioni successive
App web progressiva (PWA)
installata in un ambito diverso sulla stessa origine o su un'origine diversa 		Solo Android:
Chrome 84 o versioni successive

Controllare se l'app per Android è installata

Il tuo sito web può verificare se la tua app per Android è installata.

Solo Android: Chrome 80 o versioni successive

Comunicare alla tua app per Android informazioni sul tuo sito web

Innanzitutto, devi aggiornare la tua app per Android per definire la relazione tra il tuo sito web e l'applicazione Android utilizzando il sistema Digital Asset Links. In questo modo, solo il tuo sito web può verificare se la tua app per Android è installata.

Nel AndroidManifest.xml dell'app per Android, aggiungi una voce asset_statements:

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

Poi, in strings.xml, aggiungi la seguente dichiarazione delle risorse, aggiornando site con il tuo dominio. Assicurati di includere i caratteri di escape.

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

Una volta completata, installa l'app aggiornata sul dispositivo o pubblicala sul Google Play Store o su una delle altre piattaforme di distribuzione di app per Android.

Informare il tuo sito web della tua app per Android

Successivamente, comunica al tuo sito web la tua app per Android aggiungendo un manifest dell'app web alla tua pagina. Il manifest deve includere la proprietà related_applications, un array che fornisce i dettagli della tua app, inclusi platform e id.

  • platform deve essere play
  • id è l'ID pacchetto Android
{
  "related_applications": [{
    "platform": "play",
    "id": "com.android.chrome"
  }]
}

Controllare se l'app è installata

Infine, chiama la funzione asincrona navigator.getInstalledRelatedApps() per verificare se la tua app per Android è installata.

Controllare se l'app Windows (UWP) è installata

Il tuo sito web può verificare se la tua app per Windows (creata utilizzando UWP) è installata.

Solo Windows: Chrome 85 o versioni successive, Edge 85 o versioni successive

Comunicare alla tua app per Windows il tuo sito web

Devi aggiornare la tua app Windows per definire la relazione tra il tuo sito web e l'applicazione Windows utilizzando i gestori URI. In questo modo, solo il tuo sito web può verificare se l'app per Windows è installata.

Aggiungi la registrazione dell'estensione Windows.appUriHandler al file manifest della tua app Package.appxmanifest. Ad esempio, se l'indirizzo del tuo sito web è example.com, aggiungi la seguente voce nel manifest dell'app:

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

Tieni presente che potresti dover aggiungere lo spazio dei nomi uap3 all'attributo <Package>.

Poi, crea un file JSON (senza l'estensione .json) denominato windows-app-web-link e fornisci il nome della famiglia di pacchetti dell'app. Posiziona il file nella radice del server o nella directory /.well-known/. Puoi trovare il nome della famiglia di pacchetti nella sezione Packaging del Progettista manifest dell'app.

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

Per informazioni dettagliate sulla configurazione dei gestori di URI, consulta la sezione Abilitare le app per i siti web utilizzando i gestori di URI delle app.

Comunicare al tuo sito web la tua app per Windows

Successivamente, comunica al tuo sito web la tua app per Windows aggiungendo un manifest dell'app web alla tua pagina. Il manifest deve includere la proprietà related_applications, un array che fornisce i dettagli della tua app, inclusi platform e id.

  • platform deve essere windows
  • id è il nome della famiglia di pacchetti della tua app, a cui viene aggiunto il valore <Application> Id nel file Package.appxmanifest.
{
  "related_applications": [{
    "platform": "windows",
    "id": "MyApp_9jmtgj1pbbz6e!App"
  }]
}

Controllare se l'app è installata

Infine, chiama la funzione asincrona navigator.getInstalledRelatedApps() per verificare se l'app Windows è installata.

Guarda questa demo.

Controllare se la PWA è già installata (nell'ambito)

La tua PWA può verificare se è già installata. In questo caso, la pagina che effettua la richiesta deve trovarsi nello stesso dominio e nell'ambito della tua PWA, come definito dall'ambito nel manifest dell'app web.

Supportato su:

Android: Chrome 84 o versioni successive

Computer (Windows, macOS, Linux, ChromeOS): Chrome 140 o versioni successive, Edge 140 o versioni successive

Fornire informazioni sulla PWA

Comunica alla tua PWA le sue caratteristiche aggiungendo una voce related_applications nel manifest dell'app web della PWA.

  • platform deve essere webapp
  • url è il percorso (può essere relativo) al manifest dell'app web della tua PWA
  • id è l'ID app web dichiarato nel campo id del manifest dell'app web o calcolato dal browser (obbligatorio per il computer, non necessario per Android)
{
  …
  "scope": "/",
  "start_url": "/?utm_source=home_screen",
  "related_applications": [{
    "platform": "webapp",
    "url": "/manifest.json",
    "id": "https://example.com/?utm_source=home_screen"
  }],
  …
}

Controllare se la PWA è installata

Infine, chiama la funzione asincrona navigator.getInstalledRelatedApps() dall'ambito della tua PWA per verificare se è installata. Se navigator.getInstalledRelatedApps() viene chiamato al di fuori dell'ambito della tua PWA, restituirà []. Consulta la sezione seguente per ulteriori dettagli.

Controllare se la tua app web progressiva è installata (fuori ambito)

Il tuo sito web può verificare se la PWA è installata, anche se la pagina non rientra nell'ambito della PWA. Ad esempio, una pagina di destinazione pubblicata da /landing/ può verificare se la PWA pubblicata da /pwa/ è installata oppure se la pagina di destinazione è pubblicata da www.example.com e la PWA da app.example.com.

Supportato su:

Solo Android: Chrome 84 o versioni successive

Comunicare alla PWA informazioni sul tuo sito web

Innanzitutto, devi aggiungere i link Digital Asset Links al server da cui viene pubblicata la tua PWA. In questo modo, viene definita la relazione tra il tuo sito web e la tua PWA e viene verificato che solo il tuo sito web possa controllare se la PWA è installata.

Aggiungi un file assetlinks.json alla directory /.well-known/ del dominio in cui si trova la PWA, ad esempio app.example.com. Nella proprietà site, fornisci il percorso completo al manifest dell'app web che eseguirà il controllo (non il manifest dell'app web della tua 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"
    }
  }
]

Successivamente, comunica al tuo sito web la tua app PWA aggiungendo un manifest dell'app web alla tua pagina. Il manifest deve includere la proprietà related_applications, un array che fornisce i dettagli sulla tua PWA, inclusi platform e url.

  • platform deve essere webapp
  • url è il percorso completo al manifest dell'app web della tua PWA
{
  "related_applications": [{
    "platform": "webapp",
    "url": "https://app.example.com/manifest.json"
  }]
}

Controllare se la PWA è installata

Infine, chiama la funzione asincrona navigator.getInstalledRelatedApps() per verificare se la tua PWA è installata.

Hai altre domande?

Hai altre domande? Controlla il tag getInstalledRelatedApps su Stack Overflow per vedere se qualcun altro ha posto domande simili. In caso contrario, poni la tua domanda lì e assicurati di contrassegnarla con il tag progressive-web-apps. Il nostro team monitora spesso questo tag e cerca di rispondere alle tue domande.

Feedback

Hai trovato un bug nell'implementazione di Chrome? L'implementazione è diversa dalla specifica?

  • Segnala un bug all'indirizzo https://new.crbug.com. Includi il maggior numero possibile di dettagli, fornisci istruzioni per riprodurre il bug e inserisci Mobile>WebAPKs nella casella Componenti.

Link utili

Grazie

Un ringraziamento speciale a Sunggook Chue di Microsoft per l'aiuto con i dettagli per il test delle app Windows e a Rayan Kanso per l'aiuto con i dettagli di Chrome.