Logging in-app message data
Learn how to log in-app message (IAM) data through the Braze SDK.
Prerequisites
Before you can use this feature, you’ll need to integrate the Web Braze SDK.
Logging message data
Logging in-app message impressions and clicks is performed automatically when you use the showInAppMessage
or automaticallyShowInAppMessage
method.
If you do not use either method and opt to manually display the message using your own UI code, use the following methods to log analytics:
1
2
3
4
5
6
7
8
// Registers that a user has viewed an in-app message with the Braze server.
braze.logInAppMessageImpression(inAppMessage);
// Registers that a user has clicked on the specified in-app message with the Braze server.
braze.logInAppMessageClick(inAppMessage);
// Registers that a user has clicked a specified in-app message button with the Braze server.
braze.logInAppMessageButtonClick(button, inAppMessage);
// Registers that a user has clicked on a link in an HTML in-app message with the Braze server.
braze.logInAppMessageHtmlClick(inAppMessage, buttonId?, url?)
Prerequisites
Before you can use this feature, you’ll need to integrate the Flutter Braze SDK.
Logging message data
To log analytics using your BrazeInAppMessage
, pass the instance into the desired analytics function:
logInAppMessageClicked
logInAppMessageImpression
logInAppMessageButtonClicked
(along with the button index)
For example:
1
2
3
4
5
6
// Log a click
braze.logInAppMessageClicked(inAppMessage);
// Log an impression
braze.logInAppMessageImpression(inAppMessage);
// Log button index `0` being clicked
braze.logInAppMessageButtonClicked(inAppMessage, 0);
Accessing message data
To access in-app message data in your Flutter app, the BrazePlugin
supports sending in-app message data using Dart Streams.
The BrazeInAppMessage
object supports a subset of fields available in the native model objects, including uri
, message
, header
, buttons
, extras
, and more.
Step 1: Listen for in-app message data in the Dart layer
To receive to the in-app message data in the Dart layer, use the code below to create a StreamSubscription
and call braze.subscribeToInAppMessages()
. Remember to cancel()
the stream subscription when it is no longer needed.
1
2
3
4
5
6
7
8
9
// Create stream subscription
StreamSubscription inAppMessageStreamSubscription;
inAppMessageStreamSubscription = braze.subscribeToInAppMessages((BrazeInAppMessage inAppMessage) {
// Handle in-app messages
}
// Cancel stream subscription
inAppMessageStreamSubscription.cancel();
For an example, see main.dart in our sample app.
Step 2: Forward in-app message data from the native layer
To receive the data in the Dart layer from step 1, add the following code to forward the in-app message data from the native layers.
The in-app message data is automatically forwarded from the Android layer.
-
Implement the
BrazeInAppMessageUIDelegate
delegate as described in our iOS article on core in-app message delegate. -
Update your
willPresent
delegate implementation to callBrazePlugin.process(inAppMessage)
.
- Ensure you have enabled the in-app message UI and set the
inAppMessagePresenter
to your custom presenter.1 2
let inAppMessageUI = CustomInAppMessagePresenter() braze.inAppMessagePresenter = inAppMessageUI
- Create your custom presenter class and call
BrazePlugin.process(inAppMessage)
withinpresent(message:)
.1 2 3 4 5 6 7 8 9
class CustomInAppMessagePresenter: BrazeInAppMessageUI { override func present(message: Braze.InAppMessage) { // Pass in-app message data to the Dart layer. BrazePlugin.processInAppMessage(message) // If you want the default UI to display the in-app message. super.present(message: message) } }
Step 3: Replaying the callback for in-app messages (optional)
To store any in-app messages triggered before the callback is available and replay them after it is set, add the following entry to the customConfigs
map when initializing the BrazePlugin
:
1
BrazePlugin braze = new BrazePlugin(customConfigs: {replayCallbacksConfigKey: true});
Prerequisites
Before you can use this feature, you’ll need to integrate the React Native Braze SDK.
Methods for logging
You can use these methods by passing your BrazeInAppMessage
instance to log analytics and perform actions:
Method | Description |
---|---|
logInAppMessageClicked(inAppMessage) |
Logs a click for the provided in-app message data. |
logInAppMessageImpression(inAppMessage) |
Logs an impression for the provided in-app message data. |
logInAppMessageButtonClicked(inAppMessage, buttonId) |
Logs a button click for the provided in-app message data and button ID. |
hideCurrentInAppMessage() |
Dismisses the currently displayed in-app message. |
performInAppMessageAction(inAppMessage) |
Performs the action for an in-app message. |
performInAppMessageButtonAction(inAppMessage, buttonId) |
Performs the action for an in-app message button. |
Handling message data
In most cases, you can use the Braze.addListener
method to register event listeners to handle data coming from in-app messages.
Additionally, you can access the in-app message data in the JavaScript layer by calling the Braze.subscribeToInAppMessage
method to have the SDKs publish an inAppMessageReceived
event when an in-app message is triggered. Pass a callback to this method to execute your own code when the in-app message is triggered and received by the listener.
To customize how message data is handled, refer to the following implementation examples:
To enhance the default behavior, or if you don’t have access to customize the native iOS or Android code, we recommend that you disable the default UI while still receiving in-app message events from Braze. To disable the default UI, pass false
to the Braze.subscribeToInAppMessage
method and use the in-app message data to construct your own message in JavaScript. Note that you will need to manually log analytics on your messages if you choose to disable the default UI.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import Braze from "@braze/react-native-sdk";
// Option 1: Listen for the event directly via `Braze.addListener`.
//
// You may use this method to accomplish the same thing if you don't
// wish to make any changes to the default Braze UI.
Braze.addListener(Braze.Events.IN_APP_MESSAGE_RECEIVED, (event) => {
console.log(event.inAppMessage);
});
// Option 2: Call `subscribeToInAppMessage`.
//
// Pass in `false` to disable the automatic display of in-app messages.
Braze.subscribeToInAppMessage(false, (event) => {
console.log(event.inAppMessage);
// Use `event.inAppMessage` to construct your own custom message UI.
});
To include more advanced logic to determine whether or not to show an in-app message using the built-in UI, implement in-app messages through the native layer.
Since this is an advanced customization option, note that overriding the default Braze implementation will also nullify the logic to emit in-app message events to your JavaScript listeners. If you wish to still use Braze.subscribeToInAppMessage
or Braze.addListener
as described in Accessing in-app message data, you will need to handle publishing the events yourself.
Implement the IInAppMessageManagerListener
as described in our Android article on Custom Manager Listener. In your beforeInAppMessageDisplayed
implementation, you can access the inAppMessage
data, send it to the JavaScript layer, and decide to show or not show the native message based on the return value.
For more on these values, see our Android documentation.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// In-app messaging
@Override
public InAppMessageOperation beforeInAppMessageDisplayed(IInAppMessage inAppMessage) {
WritableMap parameters = new WritableNativeMap();
parameters.putString("inAppMessage", inAppMessage.forJsonPut().toString());
getReactNativeHost()
.getReactInstanceManager()
.getCurrentReactContext()
.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
.emit("inAppMessageReceived", parameters);
// Note: return InAppMessageOperation.DISCARD if you would like
// to prevent the Braze SDK from displaying the message natively.
return InAppMessageOperation.DISPLAY_NOW;
}
Overriding the default UI delegate
By default, BrazeInAppMessageUI
is created and assigned when you initialize the braze
instance. BrazeInAppMessageUI
is an implementation of the BrazeInAppMessagePresenter
protocol and comes with a delegate
property that can be used to customize the handling of in-app messages that have been received.
-
Implement the
BrazeInAppMessageUIDelegate
delegate as described in our iOS article here. -
In the
inAppMessage(_:displayChoiceForMessage:)
delegate method, you can access theinAppMessage
data, send it to the JavaScript layer, and decide to show or not show the native message based on the return value.
For more details on these values, see our iOS documentation.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
- (enum BRZInAppMessageUIDisplayChoice)inAppMessage:(BrazeInAppMessageUI *)ui
displayChoiceForMessage:(BRZInAppMessageRaw *)message {
// Convert the message to a JavaScript representation.
NSData *inAppMessageData = [message json];
NSString *inAppMessageString = [[NSString alloc] initWithData:inAppMessageData encoding:NSUTF8StringEncoding];
NSDictionary *arguments = @{
@"inAppMessage" : inAppMessageString
};
// Send to JavaScript.
[self sendEventWithName:@"inAppMessageReceived" body:arguments];
// Note: Return `BRZInAppMessageUIDisplayChoiceDiscard` if you would like
// to prevent the Braze SDK from displaying the message natively.
return BRZInAppMessageUIDisplayChoiceNow;
}
To use this delegate, assign it to brazeInAppMessagePresenter.delegate
after initializing the braze
instance.
BrazeUI
can only be imported in Objective-C or Swift. If you are using Objective-C++, you will need to handle this in a separate file.
1
2
3
4
5
6
7
8
@import BrazeUI;
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
BRZConfiguration *configuration = [[BRZConfiguration alloc] initWithApiKey:apiKey endpoint:endpoint];
Braze *braze = [BrazeReactBridge initBraze:configuration];
((BrazeInAppMessageUI *)braze.inAppMessagePresenter).delegate = [[CustomDelegate alloc] init];
AppDelegate.braze = braze;
}
Overriding the default native UI
If you wish to fully customize the presentation of your in-app messages at the native iOS layer, conform to the BrazeInAppMessagePresenter
protocol and assign your custom presenter following the sample below:
1
2
3
4
BRZConfiguration *configuration = [[BRZConfiguration alloc] initWithApiKey:apiKey endpoint:endpoint];
Braze *braze = [BrazeReactBridge initBraze:configuration];
braze.inAppMessagePresenter = [[MyCustomPresenter alloc] init];
AppDelegate.braze = braze;
Prerequisites
Before you can use this feature, you’ll need to integrate the Android Braze SDK.
Logging message data
You will need to make sure certain functions are called to handle the analytics for your campaign.
Displayed messages
When a message is displayed or seen, log an impression:
1
LogInAppMessageImpression(in_app_message.id, brazetask)
Clicked messages
Once a user clicks on the message, log a click and then process in_app_message.click_action
:
1
LogInAppMessageClick(in_app_message.id, brazetask)
Clicked buttons
If the user clicks on a button, log the button click and then process inappmessage.buttons[selected].click_action
:
1
LogInAppMessageButtonClick(inappmessage.id, inappmessage.buttons[selected].id, brazetask)
After processing a message
After processing an in-app message, you should clear the field:
1
m.BrazeTask.BrazeInAppMessage = invalid
Subscribing to in-app messages
You may register Unity game objects to be notified of incoming in-app messages. We recommend setting game object listeners from the Braze configuration editor. In the configuration editor, listeners must be set separately for Android and iOS.
If you need to configure your game object listener at runtime, use AppboyBinding.ConfigureListener()
and specify BrazeUnityMessageType.IN_APP_MESSAGE
.
Parsing messages
Incoming string
messages received in your in-app message game object callback can be parsed into our pre-supplied model objects for convenience.
Use InAppMessageFactory.BuildInAppMessage()
to parse your in-app message. The resulting object will either be an instance of IInAppMessage.cs
or IInAppMessageImmersive.cs
depending on its type.
1
2
3
4
5
6
7
8
9
10
// Automatically logs a button click, if present.
void InAppMessageReceivedCallback(string message) {
IInAppMessage inApp = InAppMessageFactory.BuildInAppMessage(message);
if (inApp is IInAppMessageImmersive) {
IInAppMessageImmersive inAppImmersive = inApp as IInAppMessageImmersive;
if (inAppImmersive.Buttons != null && inAppImmersive.Buttons.Count > 0) {
inAppImmersive.LogButtonClicked(inAppImmersive.Buttons[0].ButtonID);
}
}
}
Logging message data
Clicks and impressions must be manually logged for in-app messages not displayed directly by Braze.
Use LogClicked()
and LogImpression()
on IInAppMessage
to log clicks and impressions on your message.
Use LogButtonClicked(int buttonID)
on IInAppMessageImmersive
to log button clicks. Note that buttons are represented as lists ofInAppMessageButton
instances, each of which contains a ButtonID
.