The latest Mapp Engage SDK version

This document explains how to add the Android Mapp SDK code to your application code.

SDK Versions

As of April 10, 2019, Google has deprecated support for GCM. Please ensure you have the correct Android Mapp SDK file for FCM compatibility. The Android GCM SDK will NOT work with FCM tokens.

Download the latest SDK files here: https://developers.mapp.com/#mobile-sdk

Gradle JDK

Starting from SDK version 6.0.22 JAVA 17 is required as default JDK.

Starting from SDK version 6.0.18-rc02 JAVA 11 is required as default JDK.

Source code integration

Make sure your app/build.gradle file include the applicationId attribute in defaultConfig block. Include the following dependencies to your app's gradle.build dependencies section :

app build.gradle

apply plugin: 'com.android.application'
apply plugin: 'com.google.gms.google-services'

android {
    compileSdkVersion 34 // or above
    buildToolsVersion '34.0.0' // or above
    defaultConfig {
        applicationId "com.yourapppackage.app" //make sure you have this
        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') //the latest Mapp Engage SDK version
}

Create class which extends 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", "init completed listener - Application class");
			Appoxee.instance().setPushEnabled(true);
        }
    };

    @Override
    public void onCreate() {
        super.onCreate();

        opt = new AppoxeeOptions();
        opt.sdkKey = SDK_KEY;
        opt.appID = APP_ID;
        opt.tenantID = "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);
    }

}

SDK_KEY, APP_ID are present in your CEP dashboard.

NotificationMode is an enum and you can choose one of three options:

BACKGROUND_ONLY - notification will show only when the app is closed or in idle mode.

BACKGROUND_AND_FOREGROUND - notification will show every time when a push notification comes.

SILENT_ONLY - notification never shows on the device.

If you don't choose one of these options, by default is BACKGROUND_ONLY.

AppoxeeOptions.Server is enum and you can choose one of four options:

L3

L3_US

EMC

EMC_US

CROC

TEST

Account manager will provide you info which one you should use in your application (L3, EMC or CROC). If you don't choose one of these options, by default is a TEST.
Our developers use TEST for development purpose and you shouldn't use this one.

Add application in Android manifest file

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="mapp.android.demo">

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

    <application
        android:name=".MappApp"
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        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>

</manifest>

For receiving push events like push received, push opened, push dismissed you need to create on the receiver, which extends PushDataReceiver.

In AplicationManifest within application tag you should add:

For custom layout notifications, add this code in Application class, before calling Appoxee.engage method

POST NOTIFICATIONS Runtime permission (Android 13+)

First, add in ApplicationManifest.xml required permission:

AndroidManifest.xml

Mapp Engage SDK provides proper method for requesting permission in runtime. Explain to a user why permission is needed and request permission during some logical use case. Permission can be requested from Activity or Fragment with the following method:

Notifications permission

Add a callback when appoxee finished all initialization, the callback will be called when Appoxee is up and ready, or if server hand-shaking is failed.

Another way to check the initialization finish or not is to use the following method:

return true when Android SDK is initialized.

Notification icon

Default Notification icon and color (optional). You can specify a custom default icon and a custom default color. You can choose one option of offered:

First option

Add meta-data tags in the AndroidManifest.xml file to define attributes:
com.mapp.default_notification_icon and com.mapp.default_notification_color.

Second option is to add two icons in the drawable folder(s) with the following names:

Enable additional Push Messaging service.

Create class e.g. MyMessagingService and extend it from MappMessagingService, or if you already have created that class, change its parent class from FirebaseMessagingService → MappMessagingService.

Add following into AndroidManifest.xml inside of the <application></application> tags.

AndroidManifes.xml

Then, in your extended class MyMessagingService override methods onMessageReceived and onNewToken, and add required calls like this:

Proguard rules

When application applies minifyEnabled true to a build.gradle, then the following proguard-rules must be applied so that SDK functions properly.

Mapp Mobile Customer Documentation

Initialize Android Mapp SDK for Mapp Cloud