Initialize the SDK

Updated
  • 3 minute(s) read
Prev Next

Overview

This guide explains how to initialize the Mapp Engage Android SDK v7 for Android applications.

It covers:

  • Initializing the SDK

  • Configuring required options

  • Monitoring SDK readiness

  • Checking readiness programmatically

Prerequisite:

The Mapp Engage Android SDK must already be installed in your project before initialization.

Note

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

Initialize the SDK

Initialize the SDK in your custom Application class.

Call Appoxee.engage() inside Application.onCreate() and pass the Application context.

Important

Do not initialize the SDK in an Activity. Initialization must occur in the Application lifecycle to ensure proper device registration and background handling.

Firebase Messaging Service

The SDK registers its internal MappMessagingService automatically. No additional service configuration is required for standard push handling.

Only configure a custom FirebaseMessagingService if you need to handle push messages from another provider or implement custom logic.

Java

AppoxeeOptions options = new AppoxeeOptions(
	AppoxeeOptions.Server.L3, 
	"SDK_KEY", 
	"TENANT_ID", 
	"APP_ID"
);
options.setNotificationMode(NotificationMode.BACKGROUND_AND_FOREGROUND);
Appoxee.engage(this, options);

Kotlin

val options: AppoxeeOptions = AppoxeeOptions(
     server = AppoxeeOptions.Server.L3,
     sdkKey = "SDK_KEY",
     tenantId = "TENANT_ID",
     appId = "APP_ID",
).also {
     it.notificationMode = NotificationMode.BACKGROUND_AND_FOREGROUND
}

Appoxee.engage(this, options)

Available NotificationMode Enums

Configure how the SDK displays push notifications using the NotificationMode enum:

  • BACKGROUND_ONLY — Push notifications are shown only when the app is in the background. This is the default mode.

  • BACKGROUND_AND_FOREGROUND — Push notifications are shown regardless of whether the app is in the foreground or background.

  • SILENT_ONLY — Notification UI is suppressed entirely. Push events are still received and processed by the SDK in the background.

Note

Silent pushes are a distinct push type configured in the Mapp Web Panel and are not controlled by NotificationMode. They are always received and processed by the SDK, regardless of the notification mode set.

Available Server Enums

You can configure the server via the following enum values:

  • Server.L3

  • Server.L3_US

  • Server.EMC

  • Server.EMC_US

  • Server.CROC

Use the server value provided for your environment by your Mapp Engage setup.

SDK Logging

The SDK writes its output to Logcat. Use the logType option to control whether that output is produced. Available since SDK 7.1.3.

Java

options.setLogType(AppoxeeOptions.LogLevel.RELEASE);

Kotlin

it.logType = AppoxeeOptions.LogLevel.RELEASE

The following values are available:

  • LogLevel.DEBUG — The SDK logs only when your application is built as debuggable. This is the default, and it normally applies to your debug build type.

  • LogLevel.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. Debug, info, warning, and error output are always active together.

Set logType before you call Appoxee.engage(). The SDK configures its logger during initialization, and later changes have no effect.

The value is stored together with your other options. If you call Appoxee.engage() without options, the SDK restores the stored value. Changing only logType does not reset the device registration.

Warning

LogLevel.RELEASE produces SDK log output in your production builds. Use it for troubleshooting only, and set logType back to LogLevel.DEBUG before you publish your app.

Custom Notification Icons (Optional)

You can configure custom notification icons via meta-data entries in your AndroidManifest.xml:

<meta-data
    android:name="com.engage.mapp_notification_small_icon"
    android:resource="@drawable/your_notification_small_icon" />
<meta-data
    android:name="com.engage.mapp_notification_large_icon"
    android:resource="@drawable/your_notification_large_icon" />
<meta-data
    android:name="com.engage.mapp_notification_small_icon_color"
    android:resource="@color/your_accent_color" />

If not configured, the SDK will use the default application icon.

Monitor SDK Readiness

To track when the SDK is fully initialized and ready to use, register an observer using the AppoxeeObserver interface.

Register and unregister the observer according to your component lifecycle (for example, in onCreate() and onDestroy()).

Java

//Implement AppoxeeObserver interface on the activity or fragment.
public class MainActivity extends AppCompatActivity implements AppoxeeObserver{
	//...
}

//register activity (or fragment) in some early lifecycle event (e.g. onCreate() or similar)
Appoxee.instance().subscribe(this);

// after that implement methods of a subscribed interface
@Override
public void onReadyStatusChanged(boolean status, @NonNull MappResult<DevicePayload> mappResult) {
    // when status is true, SDK is ready to use
	// it is safe to call Appoxee.instance().*** methods.
}

// call unsubscribe in the equivalent lifecycle event (e.g. onDestroy() ) to the one where you have registered 
Appoxee.instance().unsubscribe(this);

Kotlin

//Implement AppoxeeObserver interface on the activity or fragment.
class MainActivity : AppCompatActivity(), AppoxeeObserver{
	//...
}

//register activity (or fragment) in some early lifecycle event (e.g. onCreate() or similar)
Appoxee.instance().subscribe(this)

// after that implement methods of a subscribed interface
override fun onReadyStatusChanged(status: Boolean, mappResult: MappResult<DevicePayload>) {
    // when status is true, SDK is ready to use
	// it is safe to call Appoxee.instance().*** methods.
}

// call unsubscribe in the equivalent lifecycle event (e.g. onDestroy() ) to the one where you have registered 
Appoxee.instance().unsubscribe(this)

Important: Always call unsubscribe() in the appropriate lifecycle method to prevent memory leaks.

Check SDK Readiness Programmatically

You can check whether the SDK is ready before calling SDK methods:

Java

boolean isReady = Appoxee.instance().isReady();

Kotlin

val isReady = Appoxee.instance().isReady()

Additional Notes

  • Ensure that the SDK is initialized only once.

  • The SDK must be ready before invoking dependent features such as push registration, event tracking, inbox retrieval, or in-app messaging.

  • Use the readiness callback (onReadyStatusChanged) or isReady() to guard feature execution when needed.