Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
250 lines (194 sloc) 9.72 KB
title subhead authors description date updated tags hero alt origin_trial
Is your native app installed? `getInstalledRelatedApps()` will tell you!
The `getInstalledRelatedApps()` method allows your web app to check whether your native app is installed on a user's device, and vice versa.
petelepage
As the capability gap between web and native gets smaller, it gets easier to offer the same experience for both web and native users. This may lead to cases where users have both web and native versions of the same app installed on the same device. Apps should be able to detect this situation. The getInstalledRelatedApps() API is a new web platform API that allows your web app to check to see if your native app is installed on the users device, and vice versa.
2018-12-20
2019-10-15
post
capabilities
fugu
origin-trial
hero.jpg
mobile device with app panel open

{% Aside %} We're currently working on this API as part of the new capabilities project. Starting in Chrome 73, the API is available as an origin trial on Android. This post will be updated as the API evolves. {% endAside %}

What is the getInstalledRelatedApps() API? {: #what }

A web app using getInstalledRelatedApps() to determine if its related native app is already installed.

As the capability gap between web and native gets smaller, it gets easier to offer the same experience for both web and native users. This may lead to cases where users have both web and native versions of the same app installed on the same device. Apps should be able to detect this situation.

The getInstalledRelatedApps() method allows your web app to check if your native app is installed on a user's device, and vice versa. With getInstalledRelatedApps(), you can disable some functionality of one app if it should be provided by the other app instead.

If getInstalledRelatedApps() looks familiar, it is. The Chrome team originally announced this feature in April 2017, when it first went to an origin trial. After the origin trial ended, they took stock of the feedback and spent some time iterating the design.

Suggested use cases {: #use-cases }

  • Checking for the other version of an app and switching to it
  • Disabling notifications in the web app when the native app is installed
  • Not prompting users to install the web app if the native app is installed

Current status {: #status }

Step Status
1. Create explainer Complete
2. Create initial draft of specification Complete
3. Gather feedback and iterate on design In progress
4. Origin trial In progress
5. Launch Not started

Join the origin trial {: #origin-trial }

Starting in Chrome 73, the getInstalledRelatedApps() API is available as an origin trial for Android.

{% include 'content/origin-trials.njk' %}

Check out the getInstalledRelatedApps() API demo and getInstalledRelatedApps() API demo source.

Register for the origin trial {: #ot }

{% include 'content/origin-trial-register.njk' %}

Alternatives to the origin trial

If you want to experiment with the API locally, without an origin trial, enable the #enable-experimental-web-platform-features flag in chrome://flags.

See it in action

  1. Using Chrome 79 or later on Android, open the getInstalledRelatedApps() demo.
  2. Install the demo app from the Play store and refresh the demo page. You should now see the app listed.

How to use getInstalledRelatedApps() {: #use }

To use getInstalledRelatedApps(), you must first create a relationship between between the web and native versions of your app. This relationship prevents other apps from using the API to detect if your app is installed and prevents sites from collecting information about the apps you have installed on your device.

Define the relationship to your native app {: #relationship-web }

In your web app manifest, add a related_applications property. The related_applications property is an array containing an object for each app that you want to detect. Each app object includes:

  • The platform on which the app is hosted
  • The unique identifier for your app on that platform
  • The URL where your app is hosted (optional)

For example:

{
  
  "related_applications": [{
    "platform": "play",
    "id": "<package-name>",
    "url": "https://example.com",
  }],
  
}

The url property is optional, and the API works fine without it. On Android, the platform value must be play. On other devices, the platform value will be different.

Define the relationship to your web app {: #relationship-native }

Each platform has its own method of verifying a relationship. On Android, the Digital Asset Links system defines the association between a website and an application. On other platforms, the way you define the relationship will differ slightly.

In AndroidManifest.xml, add an asset statement that links back to your web app:

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

Then, in strings.xml, add the following asset statement, updating site with your domain. Be sure to include the escaping characters.

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

Test for the presence of your native app {: #test-native }

Once you've updated your native app and added the appropriate fields to the web app manifest, add code to check for the presence of your native app to your web app. Calling navigator.getInstalledRelatedApps() returns a promise that resolves with an array of your apps that are installed on the user's device.

navigator.getInstalledRelatedApps()
.then((relatedApps) => {
  relatedApps.forEach((app) => {
    console.log(app.id, app.platform, app.url);
  });
});

{% Aside %} Like most other powerful web APIs, the getInstalledRelatedApps() API is only available when served over HTTPS. {% endAside %}

Feedback {: #feedback }

The Web Platform Incubator Community Group (WICG) and the Chrome team want to hear about your experiences with the getInstalledRelatedApps() API.

Tell us about the API design

Is there something about the API that doesn't work as expected? Or are there missing methods or properties that you need to implement your idea?

Report a problem with the implementation

Did you find a bug with Chrome's implementation? Or is the implementation different from the spec?

  • File a bug at https://new.crbug.com. Include as much detail as you can, provide simple instructions for reproducing the bug, and enter Mobile>WebAPKs in the Components box. Glitch works great for sharing quick and easy repros.

Show support for the API

Are you planning to use the getInstalledRelatedApps() API? Your public support helps the Chrome team to prioritize features and shows other browser vendors how critical it is to support them.

  • Share how you plan to use the API on the WICG Discourse thread.
  • Send a Tweet to @ChromiumDev with the #getInstalledRelatedApps hashtag and let us know where and how you're using it.

Helpful links {: #helpful }

You can’t perform that action at this time.