Can’t make the #ChromeDevSummit this year? Catch all the content (and more!) on the livestream, or join your peers for a CDS Extended event at a hosted location nearby. To learn more, check out the Chrome Dev Summit 2019 website.

Check If Your Native App Is Installed With getInstalledRelatedApps()

What is the getInstalledRelatedApps() API?

A web app using getInstalledRelatedApps() to determine if it's 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. We originally announced this feature in April 2017, when it first went to an origin trial. After that origin trial ended, we took stock of the feedback and spent some time iterating on this design.

Read explainer

Suggested use cases

There may be cases where there isn’t feature parity between your web and native apps. With getInstalledRelatedApps(), you can check if the other version is installed, and switch to it, using the functionality there. For example, one of the most common scenarios we’ve heard, and the key reason behind this method is to reduce duplicate notifications. Using getInstalledRelatedApps() allows you check to see if the user has the native app installed, then disable the notification functionality in the web app.

Installable web apps can help prevent confusion between the web and native versions by checking to see if the native version is already installed and either not prompting to install the PWA, or providing different prompts.

Current status

Step Status
1. Create explainer Complete
2. Create initial draft of specification In Progress
3. Gather feedback & iterate on design In Progress
4. Origin trial Complete
5. Launch In beta

Join the origin trial

Starting in Chrome 73, the getInstalledRelatedApps() API is available as an origin trial for Android. Origin trials allow you to try out new features and give feedback on usability, practicality, and effectiveness to us, and the web standards community. For more information, see the Origin Trials Guide for Web Developers.

Check out the getInstalledRelatedApps() API Demo and getInstalledRelatedApps() API Demo source

Register for the origin trial

  1. Request a token for your origin.
  2. Add the token to your pages. There are two ways to provide this token on any pages in your origin:
    • Add an origin-trial <meta> tag to the head of any page. For example, this may look something like: <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
    • If you can configure your server, you can also provide the token on pages using an Origin-Trial HTTP header. The resulting response header should look something like: Origin-Trial: TOKEN_GOES_HERE

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 your two apps. 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

In your web app manifest, add a related_applications property that contains a list of the apps that you want to detect. The related_applications property is an array of objects that contain the platform on which the app is hosted and the unique identifier for your app on that platform.

{
  ...
  "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 must be play. On other devices, platform will be different.

Define the relationship to your web app

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

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);
  });
});

Feedback

We need your help to ensure that the getInstalledRelatedApps() API works in a way that meets your needs and that we’re not missing any key scenarios.

We’re also interested to hear how you plan to use the getInstalledRelatedApps() API:

  • Have an idea for a use case or an idea where you'd use it?
  • Do you plan to use this?
  • Like it, and want to show your support?

Share your thoughts on the getInstalledRelatedApps() API WICG Discourse discussion.

Was this page helpful?
Yes
What was the best thing about this page?
It helped me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had the information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had accurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was easy to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
No
What was the worst thing about this page?
It didn't help me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was missing information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had inaccurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was hard to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.

Helpful Links

rss_feed Subscribe to our RSS or Atom feed and get the latest updates in your favorite feed reader!