Deep Links

Typically you’ll want to open Rover experiences through deep links and universal links (sometimes referred to as App Links). This is useful for integrating with a push notification automation solution or a CMS, and in the case of universal links, external communications such as email.

Deep links are for URIs that bear a custom schema specific to your app, e.g.:

example://experience?experienceID=…

Registering a Scheme

Registering a custom URI scheme will associate all URIs using that scheme with your app. When a user taps a URI using your scheme in an email, for example, iOS will launch your app.

For your app to suport deep linking to Rover experiences you will need to define a custom URI scheme. If you are implemeting deep links for the first time, see Apple’s guide: Defining a Custom URL Scheme for Your App.

Implement a Handler

When a user taps a link with your custom URI scheme, iOS will open your app (if needed) and call the application(_:open:options:) method on your app delegate. The URI the user tapped is passed as a parameter.

This method is called for every custom URI your app supports. You will need to parse the contents of the URI and present a Rover experience if appropriate.

You will need to designate a unique URI structure to be used for presenting Rover experiences. The simplest approach is to use a specific URI path and include the id of the experience as a query parameter.

myapp://experience?id=<EXPERIENCE_ID>

The following example demonstrates how to parse the contents of the URI in your application(_:open:options:) method and present a Rover experience if appropriate.

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    if url.host == "experience" {
        guard let queryItems = URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems else {
            return false
        }
        
        guard let experienceID = queryItems.first(where: { $0.name == "id" })?.value else {
            return false
        }
    
        let viewController = RoverViewController(experienceID: experienceID)
        app.present(viewController, animated: true)
        return true
    }
    
    //...
}

Campaign Attribution

Often you will want to present an experience as the result of a specific marketing campaign. The RoverViewController can be associated with an arbitrary campaign ID when it is instantiated. When a campaign ID is passed to the initializer, the RoverViewController will include it in all notifications it broadcasts. See the Analytics guide for details on how to capture Rover events in your analytics tracking.

To attribute an experience launching from a deep link with a campaign ID, include an additional campaignID parameter in the deep link.

myapp://experience?id=<EXPERIENCE_ID>&campaignID=<CAMPAIGN_ID>

Update your URI handling code to parse the optional campaignID and pass it to the RoverViewController initializer.

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    if url.host == "experience" {
        guard let queryItems = URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems else {
            return false
        }
        
        guard let experienceID = queryItems.first(where: { $0.name == "id" })?.value else {
            return false
        }
    
        // Parse the optional `campaignID` query parameter
        let campaignID = queryItems.first(where: { $0.name == "campaignID" })?.value
        let viewController = RoverViewController(experienceID: experienceID, campaignID: campaignID)
        
        app.present(viewController, animated: true)
        return true
    }
    
    //...
}

Alternative URI Structures

If the recommended URI structure does not meet your needs you can setup any arbitrary URI to launch a Rover experience as long as you can extract the experience ID from it. For example you could use a path based approach which includes the experience ID and optional campaign ID as path components instead of query string parameters.

myapp://experience/<EXPERIENCE_ID>/<CAMPAIGN_ID>

The below example demonstrates how to route URIs in this format to a Rover experience.

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    if let host = url.host, host.starts(with: "experience") {
        let components = host.components(separatedBy: "/")
        guard components.indices.contains(1) else {
            return false
        }
    
        let experienceID = components[1]
        let campaignID = components.indices.contains(2) ? components[2] : nil
        let viewController = RoverViewController(experienceID: experienceID, campaignID: campaignID)
    
        app.present(viewController, animated: true)
        return true
    }
    
    //...
}