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.

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

Prerequisites:

Ensure your app/build.gradle file includes the applicationId attribute in the defaultConfig block.

Add the following dependencies to your build.gradle:

Note
The following Gradle configuration is provided as an example. Adjust SDK versions, compileSdkVersion, and dependency versions to match your project requirements.

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'
}

Extend Application Class: Create a class extending android.app.Application, and add the following code snippet:

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).

Add to AndroidManifest.xml: Include the following in the <application> tag of AndroidManifest.xml:

<application
    android:name=".MappApp"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme">
    <activity android:name=".MainActivity">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
</application>

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

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:

<receiver
    android:name=".MyPushBroadcastReceiver"
    android:enabled="true"
    android:exported="false">
    <intent-filter>
        <action android:name="com.appoxee.PUSH_OPENED" />
        <action android:name="com.appoxee.PUSH_RECEIVED" />
        <action android:name="com.appoxee.PUSH_DISMISSED" />

		<category android:name="${applicationId}" />
    </intent-filter>
</receiver>

Custom Push Notifications: Create custom notification layouts if needed:

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);

Runtime Permissions (Android 13+): Request POST_NOTIFICATIONS permission at runtime:

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:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

ProGuard Rules: Add these rules to your proguard-rules.pro file:

-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:

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.
```
public class MyMessageService extends MappMessagingService {
}
```

Update the AndroidManifest.xml

Add the following configuration inside the <application> tags in your AndroidManifest.xml file:

<service android:name="com.appoxee.push.fcm.MappMessagingService"
    android:exported="true"
    tools:node="remove">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
<service android:name=".MyMessageService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Override Necessary Methods

In your MyMessageService class, override the onMessageReceived and onNewToken methods. Add the required logic as shown below:

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
    }
}

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