Initialize the SDK

  • 2 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 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.

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.