Communicate with the Experience

How do I communicate with the experience?

The SDK allows you to pass parameters, as well as send and receive custom messages to the embedded Experience so as to assist in developing more complex integrations.

This enables us to share information, such as authentication or user preferences (such as language), between the app and Experience, or to react to user interactions in either, such as notifying your app that the user requested to log in.

How do I add query parameters?

You can use it as follows:

The SDK allows you to provide custom query parameters in LauncherKit to customise the app you embed. How the app responds depends on how it was created so this is general feature available for developers.

let parameters = ["customKey": "customValue"]
let config = ExperienceConfiguration(
  parameters: parameters
)

let experience = Launcher.getExperience(config: config)
<yourView>.addSubview(experience)

// You need to ensure the experiences are laid out however you see fit.
// For instance, could use autolayout constraints, or setting 
// their frame

Please note that some parameters are reserved by the SDK.

The protected parameters are:

• h, p, and e.

• Parameters prefixed with mic

How do I know the experience is ready to communicate via messages?

Given that embedding the Experience on the page is an asynchronous process, we need to await for it to become ready before we can start sending messages, otherwise they wouldn't be received correctly.

If you don't await for the Experience to be ready, your message might be lost.

To identify that the Experience is ready, we can implement the ExperienceViewDelegate's didBecomeReady. This will be called once the experience is ready to accept incoming messages.

extension MyClass: ExperienceViewDelegate {
    
    func didBecomeReady(from controller: ExperienceView) {
        // experience is ready to accept incoming messages
    }
    
    // Other methods of the delegate
}

How do I send a message to the experience?

This is useful for updating the state of the Experience during its runtime, such as notifying about changes in the user log in status, as well as to notify about events, such as a change in the preferred user language.

A message is an object composed of the following:

• An action identifying its purpose.

• A data payload to be exchanged.

It is important to wait before experience is fully embedded before sending messages.

let experience = Launcher.getExperience()
let encodable = ["my": "payload]
experience.sendMessage(action: "my_action", payload: ["my": "payload"])

How do I receive a message from the experience?

Just as your application can send messages to the Experience, so can the Experience send you messages. Using a snippet similar to the next you'll be able to read messages sent by the Experience, and allow you to treat them as expected:

class MyClass: ExperienceViewDelegate {

    func embedExperience() -> ExperienceView {
        let experience = Launcher.getExperience()
        experience.delegate = self
        
        // We assume the caller sets the Experience in the UI
        return experience
    }
    
    func didReceiveMessage(experienceView: ExperienceView, message: MessageData) {
        switch message.action {
        case "my_action":
            let payload = message.payload
            // Do something with the payload received that relates to 
            // the action my_action
        default:
            return
        }
    }
    
    // Other methods of the delegate
}

How do I respond to a message received?

In some scenarios, you'll want to have a request/response pattern when communicating with the Experience. To do so, you will need to first receive a message to respond to, and then respond to it using a snippet similar to the following:

extension MyClass: ExperienceViewDelegate {
    func didReceiveMessage(experienceView: ExperienceView, message: MessageData) {
        switch message.action {
        case "my_action":
            experienceView.respondToRequest(message: message, payload: ["my": "payload"])
        default:
            return
        }
    }
}

How do I wait for a response?

We also offer the possibility of sending a message, and await for a response from the Experience. The following snippet demonstrates how to do so in each of the supported platforms:

let experience = Launcher.getExperience()
let encodable = ["my": "payload]
experience.sendRequest(action: "my_action", payload: payload) { result in
    switch result {
    case .success(let message):
        print(message.action)
        print(message.payload)
    case .failure(let error):
        print(error)
    }
}