Universal Links

You may want your app to open Rover experiences through universal links, which allow seamless linking of web URLs on your domain to content within your app (sometimes referred to as App Links). These are useful for links used in multiple channels of external communication outside of your app, such as email or social, that need to elegantly fall back to a web-only expeirence in the event of the link being opened by a user outside of an environment where they have your app installed.

An example of a universal Experience URL might look like

https://myapp.rover.io/my-great-experience

. When a user opens this URL on a mobile device it will present the Experience directly in your app. If the user doesn’t have your app installed it will fall-back to viewing the web-based version of the Experience in the browser.

About Universal Links

Android apps can register themselves to handle URIs launched on the device that match a given pattern. This is analagous to an iOS feature called Universal Links that allows seamless linking of content that can be accessed through both a browser and within your app. Rover supports Universal Links for Experiences.

An example of a universal Experience URL might look like:

https://example.rover.io/my-great-experience

When a user opens this URL on a mobile device it will present the Experience directly in your app. If the user doesn’t have your app installed it will fall-back to viewing the web-based version of the Experience in the browser.

Universal links are HTTP(s) links that are hosted by Rover, offering similar functionality as deep links (but only displaying Rover Experiences), but unlike deep links they can fall back to a web-powered version of your Experience when viewed on a device without your app installed.

Integrating Universal Links

Similar to the URL scheme used by the Deep Links, each Rover account has a unique domain that is used to construct Rover universal links. You can find the domain assigned to your Rover account in the Rover Settings app next to the URL scheme.

Settings App

As is standard on Android, you will need an Activity to handle the incoming links. The following serves as a simple boilerplate example of how to handle the links.

Intent Filter

Add the intent filter for universal links to your Activity manifest entry, given that your app universal link domain name is, for example, example.rover.io:

<activity android:name="…">
    …
    <!-- for http universal links/app links -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="http" android:host="example.rover.io" />
    </intent-filter>
</activity>

And then, for https:

<activity android:name="…">
    …
    <!-- for https universal links/app links -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="https" android:host="example.rover.io" />
    </intent-filter>
</activity>

Android App Links Setup

In order to avoid Android prompting users to choose between your app and the web browser when trying to open a universal link, we need to set up Android App Links. Once we have done so, Android’s autoVerify feature that we enabled above in your manifest will validate that your app owns the universal link domain.

Get SHA-256 Certificate Fingerprint

Locate your signing key that you use to sign your production APK, and then you can use the Java keytool program to extract the fingerprint:

$ keytool -list -v -keystore signing-key.keystore

Rover Settings

Visit the Android Settings page of the Rover Settings app. Beside the “Universal Links” heading, click the plus (+) icon and enter your App Identifier and the SHA-256 fingerprint of the certificate you use to sign your production APKs.

Enter Settings

Save the form and verify the assetlinks.json file is available in the .well-known directory of your Rover associated domain.

Example: https://myapp.rover.io/.well-known/assetlinks.json.

Verification

App Links auto-verification, which is what enables Android automatically opening your app for a universal link without prompting the user to choose between it or their web browser, can be a bit tricky to set up right.

Make sure that android:autoVerify="true" XML attribute has been added to at least one of the http or https intent filters. When it is enabled for one it is enabled for all. However, if any of the app links intent filter hosts fails to verify, then App Links will fail for any such hosts defined in your manifest, including any that you have set up outside of Rover.

Troubleshoot any issues by filtering your logcat output for verifi [sic] (and be sure not to be filtered to just your app’s own process) while doing a fresh install of the app. This should capture all of the relevant log messages from Android’s verifier services.

Handling and Routing the Links

The activity receiving the intent requires some logic in order to start the RoverActivity, if you have your own routing infrastructure you may certainly make use of it.

override fun onCreate(savedInstanceState: Bundle?) {
/* ... other onCreate() logic ... */

val uri : Uri = intent.data ?: return

// Universal links are handled similarly:
if(uri.scheme ?: "" in listOf("http", "https") && uri.host == getString(R.string.associated_domain)) {
    startActivity(RoverActivity.makeIntent(packageContext = this, experienceUrl = uri, campaignId = queryCampaignId))
}