---
title: "API Reference"
slug: "method-library-for-android-sdk-v7"
updated: 2026-09-23T15:22:39Z
published: 2026-09-23T15:22:39Z
canonical: "docs.mapp.com/method-library-for-android-sdk-v7"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/v1/docs/initialization-engage-android-sdk-v7).

> [!NOTE]
> 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]
> 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

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

#### Kotlin

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

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

> [!NOTE]
> 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` |

---

## Tags

| 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]
> 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]
> 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]
> 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](/v1/docs/initialization-engage-android-sdk-v7).

### 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`.