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 becomes easier to offer the same experience for both web and native users. This may lead to cases where users have both the web and native versions 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. With the getInstalledRelatedApps API, 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 some cases where there isn’t feature parity between the web and native apps. With the getInstalledRelatedApps API, you can check if the other version is installed, and switch to the other app, using the functionality there. For example, one of the most common scenarios we’ve heard, and the key reason behind this API is to help reduce duplicate notifications. Using the getInstalledRelatedApps API, 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 In Progress
5. Launch Not started

See it in action

  1. Using Chrome 73 or later on Android, open the getInstalledRelatedApps demo. Note, this site uses an origin trial token to enable the API.
  2. Install the demo app from the Play store and refresh the demo page. You should now see the app listed.

How to use the getInstalledRelatedApps API

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.

Establish a relationship between your apps

In order to use the getInstalledRelatedApps, you must first create a relationship between your two apps. This relationship is critical and 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 is used to define 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, you can add the code to check for the presence of your native app to you web app. Calling navigator.getInstalledRelatedApps() returns a Promise that resolves with an array of your apps that are installed on the users 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!