Deep Links

A common way of presenting Rover experiences in your app is via “deep link”. After configuring your app to support deep linking to Rover experiences, you can then direct users to experiences via push notifications, news feed tiles and other areas of your application.


Registering a Scheme

Registering a custom URL scheme will associate all URLs using that scheme with your app. When a user taps a URL 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 URL 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 URL scheme, iOS will open your app (if needed) and call the application(_:open:options:) method on your app delegate. The URL the user tapped is passed as a parameter.

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

You will need to designate a unique URL structure to be used for presenting Rover experiences. The simplest approach is to use a specific URL 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 URL 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 events it broadcasts. See the events section 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 URL 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 URL Structures

If the recommened URL structure does not meet your needs you can setup any arbitrary URL 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 URLs 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
    }
    
    //...
}