--- title: "Initialize the SDK" slug: "initialization-engage-android-sdk" updated: 2026-03-10T08:49:21Z published: 2026-03-10T08:49:21Z canonical: "docs.mapp.com/initialization-engage-android-sdk" --- > ## 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. # Initialize the SDK ## Overview This page describes how to initialize and configure the Mapp Engage Android SDK v6 in your application. It focuses on SDK-specific integration steps, including: - SDK initialization using AppoxeeOptions - Push receiver configuration - Runtime permission handling - Advanced push service setup For general Android project setup (dependencies, Firebase configuration, and channel setup), refer to [Getting Started](/v1/docs/getting-started-android-sdks). > [!NOTE] > Note > > This page focuses on SDK initialization and related configuration examples. > > For general Android project setup (dependencies, Firebase setup, and channel configuration), see Getting Started. --- ## Procedures ### SDK Integration 1. **Prerequisites**: 1. Ensure your `app/build.gradle` file includes the `applicationId` attribute in the `defaultConfig` block. 2. Add the following dependencies to your `build.gradle`: > [!NOTE] > Note > > The following Gradle configuration is provided as an example. Adjust SDK versions, compileSdkVersion, and dependency versions to match your project requirements. ```gradle apply plugin: 'com.android.application' apply plugin: 'com.google.gms.google-services' android {    compileSdkVersion 34    buildToolsVersion '34.0.0'    defaultConfig {        applicationId "com.yourapppackage.app"        minSdkVersion 19        targetSdkVersion 34        versionCode 1        versionName "1.0"        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"    }    buildTypes {        release {            minifyEnabled false            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'        }    }    compileOptions {        sourceCompatibility JavaVersion.VERSION_17        targetCompatibility JavaVersion.VERSION_17    } } dependencies {    implementation fileTree(dir: 'libs', include: ['*.jar'])    implementation 'androidx.appcompat:appcompat:1.6.1'    implementation platform('com.google.firebase:firebase-bom:32.8.1')    implementation 'com.google.firebase:firebase-messaging'    implementation 'com.google.firebase:firebase-analytics'    implementation 'com.google.firebase:firebase-crashlytics'    implementation 'com.mapp.sdk:mapp-android:X.X.X' } ``` 2. **Extend Application Class**: Create a class extending `android.app.Application`, and add the following code snippet: ```gradle public class MappApp extends Application {    private AppoxeeOptions opt;    private Appoxee.OnInitCompletedListener initFinishedListener = new Appoxee.OnInitCompletedListener() {        @Override        public void onInitCompleted(boolean successful, Exception failReason) {            Log.i("APX", "Initialization completed.");            Appoxee.instance().setPushEnabled(true);        }    };    @Override    public void onCreate() {        super.onCreate();        opt = new AppoxeeOptions();        opt.sdkKey = "SDK_KEY"; // Replace with your SDK key from the Mapp dashboard        opt.appID = "APP_ID";   // Replace with your App ID from the Mapp dashboard        opt.tenantID = "TENANT_ID"; // Your tenant ID        opt.notificationMode = NotificationMode.BACKGROUND_AND_FOREGROUND;        opt.server = AppoxeeOptions.Server.EMC;        Appoxee.engage(this, opt);        Appoxee.instance().setReceiver(MyPushBroadcastReceiver.class);        Appoxee.instance().addInitListener(initFinishedListener);        Appoxee.setOrientation(this, ActivityInfo.SCREEN_ORIENTATION_PORTRAIT);    } } ``` **NotificationMode and Server Options** - `NotificationMode` **Enum**: - `BACKGROUND_ONLY`: Notifications appear only when the app is closed or idle. - `BACKGROUND_AND_FOREGROUND`: Notifications appear in all states. - `SILENT_ONLY`: Notifications do not appear. - Default mode: `BACKGROUND_ONLY` (if not specified). - `AppoxeeOptions.Server` **Enum**: - Options: - `L3` - `L3_US` - `EMC` - `EMC_US` - `CROC` - `TEST` - Guidance: - Use `TEST` only for development. - Choose the appropriate option (`L3`, `EMC`, or `CROC`) based on your account manager’s instructions. - Default mode: `TEST` (if not specified). 3. **Add to AndroidManifest.xml**: Include the following in the `<application>` tag of `AndroidManifest.xml`: ```xml                                                 ``` 4. To receive push events such as *push received*, *push opened*, *push dismissed*, or *silent push*, you need to create a custom receiver that extends the `PushDataReceiver` class. Below is an example implementation: - **Create the Custom Push Receiver** ```java public class MyPushBroadcastReceiver extends PushDataReceiver {    @Override    public void onPushReceived(PushData pushData) {        Log.d("APX", "Push received: " + pushData);    }    @Override    public void onPushOpened(PushData pushData) {        Log.d("APX", "Push opened: " + pushData);    }    @Override    public void onPushDismissed(PushData pushData) {        Log.d("APX", "Push dismissed: " + pushData);    }    @Override    public void onSilentPush(PushData pushData) {        Log.d("APX", "Silent push received: " + pushData);    } } ``` - **Register the Receiver in the** `AndroidManifest.xml` Within the `<application>` tag in your `AndroidManifest.xml`, add the following configuration: ```xml                                 ``` 5. **Custom Push Notifications**: Create custom notification layouts if needed: ```java CustomXmlLayoutNotificationCreator.Builder builder = new CustomXmlLayoutNotificationCreator.Builder(this); builder.setLayoutResource(R.layout.custom_notification_layout)       .setIconResourceId(R.id.appoxee_default_push_icon)       .setTextResourceId(R.id.appoxee_default_push_message)       .setTitleResourceId(R.id.appoxee_default_push_subject)       .setTimeResourceId(R.id.appoxee_default_push_hour); opt.customNotificationCreator = new CustomXmlLayoutNotificationCreator(builder); Appoxee.engage(this, opt); ``` 6. **Runtime Permissions (Android 13+)**: Request `POST_NOTIFICATIONS` permission at runtime: ```java Appoxee.instance().requestNotificationsPermission(this, results -> {    if (results.containsKey(Manifest.permission.POST_NOTIFICATIONS) &&        results.get(Manifest.permission.POST_NOTIFICATIONS) == PermissionsManager.PERMISSION_GRANTED) {        Toast.makeText(MainActivity.this, "POST NOTIFICATIONS GRANTED!", Toast.LENGTH_SHORT).show();    } }); ``` Add the permission in `AndroidManifest.xml`: ```xml ``` 7. **ProGuard Rules**: Add these rules to your `proguard-rules.pro` file: ```plaintext -keepattributes Exceptions,InnerClasses,Signature,Deprecated,SourceFile,LineNumberTable,EnclosingMethod,*Annotation* -keep public class com.appoxee.** { *; } -keep class com.google.gson.reflect.TypeToken -keep class * extends com.google.gson.reflect.TypeToken -keep public class * implements java.lang.reflect.Type -keep class * implements com.appoxee.internal.network.Networkable { *; } -keep class * implements com.appoxee.internal.commandstore.Model { *; } -keep class * implements com.appoxee.internal.network.request.NetworkRequestFactory { *; } -keep class * implements com.appoxee.internal.badge.Badger { *; } -keep class com.appoxee.internal.geo.** { *; } -keep class * extends com.appoxee.internal.command.Command { *; } ``` ### Enabling Additional Push Messaging Service > This setup is only required if you are using an additional service for sending or receiving push messages. Due to Android's limitations, only one service can be active at a time. To enable an additional Push Messaging service, follow these steps: 1. **Create a Custom Messaging Service** Create a class, for example, `MyMessageService`, and extend it from `MappMessagingService`. If you have already created this class, update its parent class from `FirebaseMessagingService` to `MappMessagingService`. ```java public class MyMessageService extends MappMessagingService { } ``` 2. **Update the** `AndroidManifest.xml` Add the following configuration inside the `<application>` tags in your `AndroidManifest.xml` file: ```xml                                 ``` 3. **Override Necessary Methods** In your `MyMessageService` class, override the `onMessageReceived` and `onNewToken` methods. Add the required logic as shown below: ```java public class MyMessageService extends MappMessagingService {    @Override    public void onMessageReceived(RemoteMessage remoteMessage) {        if (remoteMessage.getData().containsKey("p")) {            // Handle Mapp push messages            super.onMessageReceived(remoteMessage);        } else {            // Handle your own push messages        }    }    @Override    public void onNewToken(String token) {        super.onNewToken(token);        // Subscribe to your own service using the Firebase token    } } ``` > [!NOTE] > Keep in mind: > > - Ensure the `MappMessagingService` and `MyMessageService` configurations are correctly defined in the manifest file to avoid conflicts. > - Customize the `onMessageReceived` method to distinguish between Mapp push messages and your custom push messages. > - Use the `onNewToken` method to manage token registration or updates for your own services.Your content goes here ## Related - [Developer Guide](/android-v6-api-guide.md) - [In-App SDK Integration](/in-app-sdk-integration.md)