Universal Links

Universal Links is a feature of iOS that allows seamless linking of content that can be accessed through both a browser and within your app. Rover supports Universal Links for presenting Experiences. 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.

Prepare Your App

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.

In order for the domain assigned to your Rover account to be associated with your app, you need to add the Associated Domains feature to your App ID and add your Rover domain to the list of associated domains in the entitlement. This can be done directly from within Xcode. Open your Xcode project or workspace and select your app from the Project Navigator. Then select your app’s target and the “Capabilities” tab.

Third from the top you will find the Associated Domains capability. Enable it and add your Rover domain prefixed with applinks: to the list of associated domains.

Site Association

Before iOS will open URLs with an associated domain, it needs to verify permssion from the domain owner. It does this by checking for the presence of a special file named apple-app-site-association uploaded to the domain’s web server. Rover will create this file for you and serve it at your associated domain but you need to provide your App ID Prefix and App Store ID which is used in the file’s contents.

To learn more about site association read the Support Universal Links guide on Apple's Developer Center.

App ID Prefix

To find your App ID Prefix, sign-in to the Apple Developer Centre and click on “Certificates, Identifiers & Profiles”.

Click on “App IDs” in the sidebar, and find your App ID in the list.

Click on your App ID and you will see a value labelled “Prefix”.

App Store ID

To find your App Store ID visit the iTunes Link Maker. Select the appropriate country and change the media type to “iOS Apps”. Now type the name of your app in the search field and submit.

In the results, click on your app and you will see a “Direct Link” on the bottom of the page. Your App Store ID is the nine-digit number in between id and ?mt.

Rover Settings

Visit the iOS Settings page of the Rover Settings app. Beside the “Universal Links” heading, click the plus (+) icon and enter your App ID Prefix and App Store ID.

Save the form and verify the apple-app-site-association file is available in the .well-known directory of your Rover associated domain.

Example: https://myapp.rover.io/.well-known/apple-app-site-association.

Handling Universal Links

When a user follows a link with a domain associated with your app, iOS opens your app and calls the application(_:continue:restorationHandler:) method. The method receives an NSUserActivity object with an activityType value of NSUserActivityTypeBrowsingWeb. The activity object’s webpageURL property contains the URL that the user accessed.

The following example demonstrates how to implement this method in your app delegate, inspect the URL and present a RoverViewController if appropriate.

func application(_ app: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb, 
        let url = userActivity.webpageURL else {
        return false
    }
    
    // Verify the domain matches the one assigned to your Rover account
    if url.host == "myapp.rover.io" {
        let roverViewController = RoverViewController(experienceURL: url)
        app.present(roverViewController, animated: true)
        return true
    }
    
    return false
}