20

In-app event listeners

When people receive an in-app message, you’ll listen for events to handle the message’s lifecycle—like dismissing the event or taking a custom action.

Handle responses to messages (event listeners)

You can set up event listeners to handle your audience’s response to your messages. For example, you might run different code in your app when your audience taps a button in your message or when they dismiss the message without tapping a button.

You can listen for four different events:

• messageShown: a message is “sent” and appears to a user
• messageDismissed: the user closes the message (by tapping an element that uses the close action)
• errorWithMessage: the message itself produces an error—this probably prevents the message from appearing to the user
• messageActionTaken: the user performs an action in the message.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

CustomerIOBuilder(
   applicationContext = this,
   cdpApiKey = configuration.cdpApiKey
).apply {
   addCustomerIOModule(ModuleMessagingInApp())
   build()
}

ModuleMessagingInApp(config = MessagingInAppModuleConfig.Builder()
   .setEventListener(object : InAppEventListener {
      override fun messageShown(message: InAppMessage) {
        trackInAppEvent("messageShown", message)
    }

    override fun messageDismissed(message: InAppMessage) {
        trackInAppEvent("messageDismissed", message)
    }

    override fun errorWithMessage(message: InAppMessage) {
        trackInAppEvent("errorWithMessage", message)
    }

    override fun messageActionTaken(
        message: InAppMessage,
        actionValue: String,
        actionName: String
    ) {
        trackInAppEvent(
            "messageActionTaken",
            message,
            hashMapOf("action-value" to actionValue, "action-name" to actionName)
        )
    }
   })
   .build()
)

private fun trackInAppEvent(
   eventName: String,
   message: InAppMessage,
   arguments: Map<String, String>?
) {
   CustomerIO.instance().track(
      "in-app message action",
      HashMap<String, String>().apply {
         arguments?.let { putAll(it) }
         put("event-name", eventName)
         put("message-id", message.messageId)
         put("delivery-id", message.deliveryId ?: "NULL")
      }
   )
}

Handling custom actions

When you set up an in-app message, you can determine the “action” to take when someone taps a button, taps your message, etc. In most cases, you’ll want to deep link to a screen, etc. But, in some cases, you might want to execute some custom action or code—like requesting that a user opts into push notifications or enables a particular setting.

In these cases, you’ll want to use the messageActionTaken event listener and listen for custom action names or values to execute code. While you’ll have to write custom code to handle custom actions, the SDK helps you listen for in-app message events including your custom action, so you know when to execute your custom code.

1. When you add an action to an in-app message in Customer.io, select Custom Action and set your Action’s Name and value. The Name corresponds to the actionName, and the value represents the actionValue in your event listener.

   

   
2. Register an event listener for MessageActionTaken, and listen for the actionName or actionValue you set up in the previous step.

    Use names and values exactly as entered

   We don’t modify your action’s name or value, so you’ll need to match the case of names or values exactly as entered in your Custom Action.

3. When someone receives a message and invokes the action (tapping a button, tapping a message, etc), your app will perform the custom action.

Dismiss in-app message

You can dismiss the currently display in-app message with the following method. This can be particularly useful to dismiss in-app messages when your audience clicks or taps custom actions.

    CustomerIO.instance().inAppMessaging().dismissMessage()