API Reference

Overview

This page documents the public API of the Mapp Engage Android SDK v7. The entry point is the Appoxee interface, which is available as a singleton once the SDK has been initialized.

For installation and initialization, see Initialize the SDK.

Note
The Android SDK APIs and package names use the Appoxee namespace. This is expected and refers to the Mapp Engage Android SDK.

The Call Pattern

Most SDK methods do not return a value directly. They return a Call<T>, which represents a request that has not been executed yet. Your application decides how and when to run it, which keeps the SDK independent of your threading model.

Execution Methods

Every Call<T> offers three ways to execute the request:

Method	Description	Usage
`execute()`	Runs the request on the calling thread and returns `MappResult<T>`. Blocks until the request completes.	Java, from a background thread only
`enqueue(callback)`	Runs the request in the background and delivers `MappResult<T>` to a `MappCallback<T>` on the main thread.	Java and Kotlin, call from the main thread
`asSuspend()`	Suspends the coroutine and returns `MappResult<T>` when the request completes.	Kotlin coroutines

Warning
A Call<T> can be executed only once. execute() and asSuspend() throw a CallConsumedException on a second attempt. enqueue() does not throw. It delivers a MappResult error that carries the same exception. To repeat a request, request a new Call from the SDK method.

Result Handling

All three execution methods deliver a MappResult<T>:

Member	Returns	Description
`isSuccess()`	`Boolean`	Whether the request succeeded
`getData()`	`T?`	The result value, or `null` on failure
`getError()`	`Throwable?`	The error, or `null` on success

Examples

Java

Appoxee.instance().getAlias().enqueue(result -> {
    if (result.isSuccess()) {
        String alias = result.getData();
    } else {
        Throwable error = result.getError();
    }
});

Kotlin

val result = Appoxee.instance().getAlias().asSuspend()

if (result.isSuccess()) {
    val alias = result.getData()
} else {
    val error = result.getError()
}

Note
Method signatures on this page are written in Kotlin. Parameters shown with a default value are optional in Kotlin only. In Java, pass every parameter explicitly.

Initialization

These members are static on Appoxee.

Method	Description	Returns
`engage(context, options)`	Initializes the SDK. Must be called from the main thread, otherwise it throws an `IllegalAccessException`. Pass `options` on first initialization. On later calls you can omit them, and the SDK restores the stored configuration.	`Unit`
`instance()`	Returns the SDK singleton. Throws a `NullPointerException` if `engage()` has not been called.	`Appoxee`
`isReady()`	Whether initialization has completed and the SDK is ready to use. This is an instance method.	`Boolean`

Device and Identity

Method	Description	Returns
`getDevice()`	Returns the registration data of the current device.	`Call<DevicePayload?>`
`setAlias(alias, resendCustomAttributes = false)`	Sets a custom alias for the registered device. When `resendCustomAttributes` is `true` and the alias has changed since the last stored value, all cached custom attributes are sent to the backend again.	`Call<String?>` with the DMC user ID
`getAlias()`	Returns the alias of the registered device.	`Call<String?>`
`logout(pushEnabled)`	Logs the user out and resets the alias. `pushEnabled` sets whether the device keeps receiving push messages afterwards.	`Call<Boolean>`

Push Notifications

Method	Description	Returns
`enablePush(enabled, token = null)`	Opts the device in or out of push messages. Pass `token` only if you have disabled `MappMessagingService` and handle Firebase messages in your own service.	`Call<Boolean>`
`isPushEnabled()`	Whether the device is currently opted in.	`Call<Boolean>`
`getFirebaseToken()`	Returns the Firebase client token the device is subscribed with.	`Call<String?>`
`updateFirebaseToken(token)`	Updates the Firebase token of the registered device. The opt-in state stays unchanged.	`Call<Boolean>`
`handlePushMessage(remoteMessage)`	Hands a Firebase message to the SDK for processing. Use this when your own service receives push messages instead of `MappMessagingService`.	`Unit`
`isPushMessageFromMapp(remoteMessage)`	Whether a Firebase message originates from Mapp.	`Boolean`
`closeNotification(notificationId)`	Dismisses the notification with the given ID.	`Unit`
`setPushBroadcast(clazz)`	Registers a `LocalPushBroadcast` subclass. The SDK then delivers push lifecycle events to it so your app can react to them.	`Unit`

In-App Messages and Inbox

Method	Description	Returns
`triggerInApp(context, eventName)`	Fetches in-app messages for the given event and displays them as a dialog or a full-screen page. `context` must be an `Activity`.	`Call<Boolean>`
`fetchInboxMessages()`	Returns all active inbox messages.	`Call<InboxMessagesResponse?>`
`fetchInboxMessage(templateId)`	Returns the inbox message with the given template ID.	`Call<InboxMessage?>`
`fetchLatestInboxMessage()`	Returns the most recent inbox message.	`Call<InboxMessage?>`
`updateInboxMessageStatus(message, status)`	Sets the status of an inbox message to `READ`, `UNREAD`, or `DELETED`.	`Call<Boolean>`
`showInboxMessage(context, message)`	Displays an inbox message as a banner, dialog, or full-screen page. Native templates use the type configured on the message. Web templates are always shown as a dialog. `context` must be an `Activity`.	`Unit`

Method	Description	Returns
`addTags(tags)`	Adds a set of tags to the device.	`Call<Boolean>`
`removeTags(tags)`	Removes a set of tags from the device.	`Call<Boolean>`
`getTags()`	Returns the tags of the device from the local cache. This does not query the backend.	`Call<List<String>>`

Custom Attributes

Method	Description	Returns
`addCustomAttributes(attributes)`	Adds custom attributes to the device. Takes a `Map<String, Any?>`.	`Call<Boolean>`
`getCustomAttributes(attributes)`	Takes a set of attribute keys and returns those that exist on the device.	`Call<Map<String, Any?>>`
`removeCustomAttributes(attributes)`	Clears the given attributes from the local cache and the backend.	`Call<Boolean>`

Note
removeCustomAttributes() does not delete the attribute keys on the backend. The keys remain and their values are set to an empty string.

Geofencing

Method	Description	Returns
`startGeofencing(enterDelaySeconds = 0)`	Starts geofence tracking. With `0`, the SDK triggers an enter event. With a higher value, it triggers a dwell event after that many seconds.	`Call<T>` where `T` extends `GeoStatus`
`stopGeofencing()`	Stops geofence tracking.	`Call<T>` where `T` extends `GeoStatus`
`isGeofencingActive()`	Whether geofence tracking is currently active.	`Call<Boolean>`

Geofencing errors are reported as a GeofenceException, which carries the related GeoStatus.

SDK Status Updates

Register an observer to be notified when the SDK becomes ready. A new subscriber immediately receives the current status.

Method	Description	Returns
`subscribe(observer)`	Registers an `AppoxeeObserver` for SDK status updates.	`Unit`
`unsubscribe(observer)`	Removes a registered observer.	`Unit`

AppoxeeObserver defines a single method, onReadyStatusChanged(status, result), where result is a MappResult<DevicePayload>.

Warning
Always call unsubscribe() in the matching lifecycle method to prevent memory leaks.

AppoxeeOptions

AppoxeeOptions is the configuration object passed to Appoxee.engage(). The four constructor parameters are required.

Parameter	Type	Description
`server`	`Server`	The Mapp Engage environment your channel runs on
`sdkKey`	`String`	SDK key of your Mapp Engage channel
`appId`	`String`	App ID of your Mapp Engage channel
`tenantId`	`String`	Your tenant ID, passed as a string

Two further properties can be set on the instance before you call engage():

Property	Type	Default	Description
`notificationMode`	`NotificationMode`	`BACKGROUND_ONLY`	When the SDK displays push notifications
`logType`	`LogLevel`	`DEBUG`	Whether the SDK writes log output. Available since 7.1.3.

Server

Use the value that matches your Mapp Engage environment: L3, L3_US, EMC, EMC_US, or CROC.

LogLevel

DEBUG — The SDK logs only when your application is built as debuggable. This is the default.
RELEASE — The SDK logs in debuggable and in release builds.

Note
Despite its name, LogLevel does not filter messages by severity. It switches SDK logging on or off as a whole. See Initialize the SDK.

NotificationMode

BACKGROUND_ONLY — Notifications appear only while the app is in the background. This is the default.
BACKGROUND_AND_FOREGROUND — Notifications appear in both states.
SILENT_ONLY — No notification UI is shown. Push events are still received and processed.

Data Types

DevicePayload

Returned by getDevice() and delivered with SDK status updates.

Property	Type	Description
`dmcUserId`	`String?`	Unique user ID assigned by Mapp
`udidHashed`	`String?`	Hashed device identifier
`pushToken`	`String?`	Token used while the device is opted in
`pushTokenBk`	`String?`	Token retained while the device is opted out
`alias`	`String?`	Alias currently set for the device

InboxMessage

Property	Type	Description
`templateId`	`Long`	Template ID of the message
`subject`, `summary`, `content`	`String`	Message text in increasing level of detail
`iconUrl`	`String`	URL of the message icon
`sentDate`, `expireDate`, `firstSentTs`	`Long?`	Timestamps for delivery and expiry
`status`	`MessageStatus`	`READ`, `UNREAD`, or `DELETED`
`isNativeInApp`	`Boolean`	Whether the message uses a native template rather than a web template
`extras`	`Map<String, String>`	Custom key-value pairs sent with the message
`eventId`, `eventKey`	`String`	Identifiers of the event that triggered the message

InboxMessagesResponse wraps a list of these messages together with the eventId of the request.

MappPush

Delivered to the callbacks of a LocalPushBroadcast. It carries id, title, content, actionUri, type, category, language, userId, customerId, a list of actionButtons, the silent-push fields silentType, silentData, and contentAvailable, and any extraFields sent with the message. Each ActionButton has a uri and an action.

LocalPushBroadcast

Extend this class and register it with setPushBroadcast() to react to push lifecycle events. It defines the callbacks onReceived(), onOpened(), onSilent(), onDismissed(), onButtonClick(), and onRichPush(), each receiving a MappPush.