Initialize the Mapp Engage SDK (v6)

SDK Versions and Requirements

As of April 10, 2019, support for Google Cloud Messaging (GCM) has been deprecated. Ensure that you are using the correct Android Mapp SDK file compatible with Firebase Cloud Messaging (FCM). The Android GCM SDK will not work with FCM tokens.

• Gradle JDK:

  • From SDK version 6.0.22: Java 17 is required.

  • From SDK version 6.0.18-rc02: Java 11 is required.

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:

      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:

   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:

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

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

     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>

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

6. 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"/>

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

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.

   public class MyMessageService extends MappMessagingService {
   }

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

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

Next Step: Advanced Configuration

Once the basic SDK integration has been implemented and tested successfully, the next step is the advanced configuration for specific features like push notifications, analytics, and customizations. For instructions, see the Android v6 API Guide and In-App SDK Integration.