Handling Custom Actions

The Rover SDK supports a custom type for actions alongside the Open URL, Present URL, and Close action types. This can be used to implement the behavior for custom buttons in your own code.

The SDK provides an API for you to register a callback to be notified of a custom action being activated (typically by a user's tap).

Usage

Implementing a Custom Action will require coordinating the setup of the actions in your Rover experiences and callback handler in your app.

A typical way to do this is to set some metadata properties fields on the same layer as the action. This can include identifying which behavior to invoke. For example, a property called behavior could added and then set to something like switchToLibraryTab, openReviewPrompt, or perhaps even startPurchase.

Note that all data context (including that from Web API data sources and URL query parameters) is made available to your callback, but additional non-dynamic fields can just be directly added to the node's metadata at design-time.

Registering a Callback

Call the Rover.shared.addCustomActionCallback for iOS or Rover.shared?.registerCustomActionCallback for Android, to register a callback to handle any activated (tapped) actions. The following example shows the approach to delegating behavior on the basis of the node's properties.

Swift:

Rover.shared.registerCustomActionCallback { (actionEvent: CustomActionActivationEvent) in
    switch actionEvent.nodeProperties["behavior"] {
        case "openWebsite":
            UIApplication.shared.open(URL(string: "https://rover.io/")!)
        case "printLogMessage":
            os_log(.default, "Hello from Rover!")
        default:
            os_log(.error, "🤷‍♂️")
    }
}

Kotlin:

Rover.shared?.registerCustomActionCallback { customActionActivation ->
    when(customActionActivation.nodeProperties["behavior"]) {
        "openWebsite" -> {
            val intent = Intent(Intent.ACTION_VIEW, Uri.parse("https://rover.io/"))
            customActionActivation.activity?.startActivity(intent)
        }
        "printLogMessage" -> {
            Log.i("MyApp", "Hello from Rover!")
        }
        else -> {
            Log.e("MyApp", "🤷‍♂️")
        }
    }
}

Callback Parameter

On both platforms, your callback is given a single parameter, a value type. Here are the properties:

• nodeId: the id of the Rover layer with the Action modifier user tapped.
• nodeName: the name of the Rover layer with the Action modifier user tapped.
• nodeProperties: the assigned properties of the Rover layer with the Action modifier user tapped.
• nodeTags: the assigned tags of the Rover layer with the Action modifier user tapped.
• screenId: the id of the Rover screen with the Action modifier user tapped.
• screenName: the name of the Rover screen with the Action modifier user tapped.
• screenProperties: the assigned properties of the Rover screen with the Action modifier user tapped.
• screenTags: the assigned tags of the Rover screen with the Action modifier user tapped.
• experienceId: the id of the Rover experience itself.
• experienceName: the name of the Rover experience itself.
• campaignId: the id of the campaign associated with this experience. This is typically used for analytics purposes.
• data: JSON data from a Web API data source. Not applicable to classic experiences.
• urlParameters: URL query parameters included with the URL that launched the experience. Not applicable to classic experiences.
• userInfo: a copy of the user info for convenience.

And, to enable custom UI behaviour, the following additional properties are available on on iOS and Android respectively:

• viewController (iOS): a reference to the view controller presenting the experience, which can be used to present new view controllers, or be dismissed.
• activity (Android): a reference to the activity presenting the experience, which can be used to start new activities, or be finished.