Overview
This page provides a reference for the public methods available in the Mapp Engage Android SDK v7.
Most public SDK methods return an object of type Call<T> instead of returning a value directly. Understanding this pattern is essential, as nearly all interactions with the SDK are executed through this interface.
A Call<T> represents a deferred request. It allows your application to decide how and when the request should be executed, depending on your threading model and architecture.
This design ensures that:
SDK operations do not block the main thread
Results are returned in a consistent wrapper type (MappResult<T>)
Both Java and Kotlin (coroutines) usage patterns are supported
Important
Each Call<T> instance can be consumed only once. Do not invoke more than one execution method (for example, call both enqueue() and asSuspend() on the same Call instance). Attempting to consume a Call multiple times will throw an IllegalStateException.
Execution Methods
Every Call<T> exposes these execution options:
Method | Description | Usage Pattern |
|---|---|---|
enqueue(callback) | Executes the request asynchronously on a background thread and delivers the result to the provided callback | Java / Kotlin |
asSuspend() | Suspends the coroutine and returns MappResult<T> when the request completes | Kotlin coroutines |
asFlow() | Converts the request into a Flow<MappResult<T>> that emits a single result | Kotlin coroutines |
Result Handling
All execution methods deliver results via MappResult<T>. Use when (Kotlin) or instanceof (Java) to handle success and failure branches:
Type | Description |
|---|---|
MappResult.Success<T> | Contains the result value in the .value property |
MappResult.Error | Contains the error details in the .error property |
MappEngage
The main entry point for the Mapp Engage Android SDK. MappEngage is the central class through which your application interacts with all core SDK features: push notifications, in-app messaging, user and device management, and custom event tracking.
It is available as a singleton accessible via MappEngage.instance after the SDK has been initialised.
Initialisation
Method | Description | Returns |
|---|---|---|
initialize(context, config) | Initialises the SDK with the provided configuration. Must be called once before using any other SDK methods, typically in your Application class. | Unit |
Push Notifications
Method | Description | Returns |
|---|---|---|
registerForPush() | Requests a new FCM push token and registers it with the Mapp backend. | Call<Unit> |
unregisterFromPush() | Removes the push token from Mapp, effectively disabling push notifications for the current device. | Call<Unit> |
In-App Messaging
Method | Description | Returns |
|---|---|---|
requestInAppMessages() | Fetches and displays any pending in-app messages for the current device from the Mapp backend. | Call<Unit> |
User & Device Management
Method | Description | Returns |
|---|---|---|
login(userId) | Associates the current device with a user ID in the Mapp backend. Once set, the user ID is persisted and sent with all subsequent SDK requests. | Call<Unit> |
logout() | Removes the user ID association from the current device and notifies the Mapp backend. | Call<Unit> |
updateUserAttributes(attributes) | Sends one or more user-level custom attributes to the Mapp backend. Accepts a Map<String, String?>; a null value removes the attribute. | Call<Unit> |
updateDeviceAttributes(attributes) | Sends one or more device-level custom attributes to the Mapp backend. Accepts a Map<String, String?>; a null value removes the attribute. | Call<Unit> |
deleteDevice() | Deletes the current device registration from Mapp. After deletion, the device will no longer receive messages until re-registered. | Call<Unit> |
getDeviceInfo() | Returns device information from the Mapp backend. | Call<DeviceInfo> |
Custom Events
Method | Description | Returns |
|---|---|---|
trackEvent(event) | Sends a custom event to the Mapp backend for analytics or automation triggers. The event must be created using MappEvent.Builder. | Call<Unit> |
MappEngageConfig
MappEngageConfig is the configuration object used to initialise the Mapp Engage SDK. It is constructed using a Builder and passed to MappEngage.initialize().
Builder Parameters
All parameters listed below are set on the MappEngageConfig.Builder via its corresponding setter method.
Parameter | Type | Required | Description |
|---|---|---|---|
applicationCode | String | Yes | Your Mapp application code |
serverUrl | String | Yes | The base URL of the Mapp backend |
senderId | String | Yes | Your Firebase project sender ID, required for FCM push registration |
notificationSmallIcon | Int | No | Drawable resource ID for the small notification icon |
notificationLargeIcon | Int | No | Drawable resource ID for the large notification icon |
notificationAccentColor | Int | No | Accent color for notifications as a color resource or ARGB integer |
notificationChannelId | String | No | Custom notification channel ID. If not set, the SDK uses a default channel. |
logLevel | LogLevel | No | Controls SDK log verbosity. Defaults to LogLevel.NONE. |
autoTrackSessions | Boolean | No | When enabled, the SDK automatically tracks app open/close events as sessions. Defaults to false. |
MappEvent
MappEvent is the object used to represent a custom event that can be sent to the Mapp backend via MappEngage.instance.trackEvent(). It is constructed using the MappEvent.Builder.
Builder Parameters
Parameter | Type | Required | Description |
|---|---|---|---|
name | String | Yes | The name of the event |
attributes | Map<String, String> | No | Optional key-value pairs to include with the event |
DeviceInfo
DeviceInfo is the data class returned by MappEngage.instance.getDeviceInfo(). It provides information about the device's current registration status and associated metadata.
Properties
Property | Type | Description |
|---|---|---|
deviceAddress | String? | The unique device address assigned by Mapp |
userId | String? | The user ID currently associated with this device, if any |
pushEnabled | Boolean | Whether the device is currently registered to receive push notifications |
userAttributes | Map<String, String> | User-level custom attributes currently stored in Mapp for this device |
deviceAttributes | Map<String, String> | Device-level custom attributes currently stored in Mapp for this device |