Android SDK Integration

Quick Steps Guidelines

Step 1: Select a Platform

Navigate to Netmera Panel > Developers > Netmera Onboarding and select Android.

Step 2: Create A Firebase Cloud Messaging Configuration

Create a project in the Firebase Developers Console.

Download and upload the New Private Key file to Netmera Onboarding Step 2.

Step 3: Select A Target SDK

Choose the appropriate SDK version for your application.

Step 4 and 5: Integrate and Initialize Netmera SDK

Add necessary configurations to your build.gradle.

Initialize Netmera in the onCreate() of your android.app.Application.

Android 13 Push Notification Permissions

Ensure Android 13 push notification permissions are requested.

Android SDK integration completed 👏

Onboarding Checklist: iOS and Android

Please find the Onboarding Checklist for iOS and Android below. Follow the titles in the checklist to ensure you have completed each essential step in your onboarding process with Netmera.

44KB

Netmera Mobile Technical Onboarding Checklist.xlsx

Step 1: Select a Platform

1. Navigate to Netmera Panel > Developers > Netmera Onboarding and choose Android.

1. Click on Android > Start to proceed.

Step 2: Create a Firebase Configuration

Netmera uses Firebase Cloud Messaging (FCM) to deliver push messages to the Android devices. Therefore, you should create and configure a project on Firebase Developers Console.

• At the end of the Firebase configuration, you will have a New Private Key folder of your project. That folder must be uploaded to Developers > Netmera Onboarding > Android > Step 2: Create A Firebase Configuration > FCM Service Account Key section on Netmera Panel.

Firebase Cloud Messaging Configuration Full Guide

Please upload the JSON file you downloaded from Firebase Cloud Messaging to the Project > app directory.

Generate New Private Key

About the Admin SDK Configuration Snippet:

There are 4 different options available on this screen. The choice of which option to select is not important as the code just indicates the language in which it will be generated. We add this code to Netmera, and there is no action required from customers to add or choose anything. Users can simply download the file by clicking the 'Generate New Private Key' button without making any selections on this page.

Upload FCM Service Account Key on Netmera Panel

Step 3: Select a Target SDK

Select the SDK for your application development framework as Native Android SDK.

Step 4: Integrate Netmera SDK

Warning About API Key: Do not use the API key from your test panel when setting up or deploying your production app. Each panel has its own unique API key. Even if you log in with a different account, this encrypted key stays the same. Using the wrong key can result in data being sent to the incorrect environment, causing potential issues or errors in your application.

The Netmera Android SDK is conveniently available through a Maven repository. To integrate it into your project, you only need to add the following configurations to your build.gradle file. AndroidManifest and other resource configurations are handled automatically by the Android Gradle build tool. Complete the following below to integrate Netmera SDK. The steps vary according to your use of Gradle 8 or below.

Projects After Gradle 8: Kotlin / Groovy

Kotlin

Project Gradle

plugins {
    alias(libs.plugins.androidApplication) apply false
    alias(libs.plugins.jetbrainsKotlinAndroid) apply false
    alias(libs.plugins.google.services) apply false
    alias(libs.plugins.androidLibrary) apply false
}

Note: Check your libs.versions.toml file:

• This file is usually located within the gradle folder in the root directory of your project.

• Review how the relevant plugin is defined.

Build Gradle

plugins {
    alias(libs.plugins.androidApplication)
    alias(libs.plugins.jetbrainsKotlinAndroid)
    alias(libs.plugins.google.services)
}
dependencies {
    implementation(libs.netmera.core)
    implementation(libs.netmera.fcm)
    implementation(libs.netmera.hms)
}

Settings Gradle

dependencyResolutionManagement {
    repositories {
        google() 
        maven { // copy the url below and add it to maven
          url = uri("https://release.netmera.com/release/android")
        }
    }
}

In this step, only copy the url "https://release.netmera.com/release/android" and add it to maven.

Libs Version

[versions]
netmeraCore = "4.0.0"
netmeraFcm = "4.0.0"
netmeraHms = "4.0.0"
googleServices = "4.4.2"
[libraries]
netmera-core = { group = "com.netmera", name = "nmcore", version.ref = "netmeraCore" }
netmera-fcm = { group = "com.netmera", name = "nmfcm", version.ref = "netmeraFcm" }
netmera-hms = { group = "com.netmera", name = "nmhms", version.ref = "netmeraHms" }
[plugins]
google-services = { id = "com.google.gms.google-services", version.ref = "googleServices" }

Groovy

Project Gradle

plugins {
    alias(libs.plugins.androidApplication) apply false
    alias(libs.plugins.jetbrainsKotlinAndroid) apply false
    alias(libs.plugins.google.services) apply false
    alias(libs.plugins.androidLibrary) apply false
}

Note: Check your libs.versions.toml file:

• This file is usually located within the gradle folder in the root directory of your project.

• Review how the relevant plugin is defined.

Build Gradle

plugins {
    alias(libs.plugins.androidApplication)
    alias(libs.plugins.jetbrainsKotlinAndroid)
    alias(libs.plugins.google.services)
}
dependencies {
    Implementation libs.netmera.core
    Implementation libs.netmera.fcm
    Implementation libs.netmera.hms
}

Settings Gradle

dependencyResolutionManagement {
...
    repositories {
...
        google()
        // copy the url below and add it to maven
        maven { url "https://release.netmera.com/release/android" } 
        }
}

In this step, only copy the url "https://release.netmera.com/release/android" and add it to maven.

Libs Version

[versions]
netmeraCore = "4.0.0"
netmeraFcm = "4.0.0"
netmeraHms = "4.0.0"
googleServices = “4.4.2”
[libraries]
netmera-core = { group = "com.netmera", name = "nmcore", version.ref = "netmeraCore" }
netmera-fcm = { group = "com.netmera", name = "nmfcm", version.ref = "netmeraFcm" }
netmera-hms = { group = "com.netmera", name = "nmhms", version.ref = "netmeraHms" }
[plugins]
google-services = { id = "com.google.gms.google-services", version.ref = "googleServices" }

Projects Before Gradle 8

Project Gradle

In this step, only copy the url specified below and add it to maven.

buildscript {
    repositories {
         google()
         maven {url 'https://developer.huawei.com/repo/'} // copy the url and add it to maven
    }
    dependencies {

    classpath 'com.android.tools.build:gradle:4.2.2'
    classpath 'com.google.gms:google-services:4.3.10'
    classpath 'com.huawei.agconnect:agcp:1.6.3.300'
    }
}

allprojects {
    repositories {
        google()
        maven {url 'https://developer.huawei.com/repo/'} // copy the url and add it to maven
        maven { url "https://release.netmera.com/release/android" } // copy the url and add it to maven
    }
}

App Gradle

You should add Netmera dependency to your dependencies section in your: build.gradle(:app)

dependencies {

    implementation 'com.netmera:nmcore:4.0.0'
    implementation 'com.netmera:nmfcm:4.0.0'
    implementation 'com.netmera:nmhms:4.0.0'

    // If you only need to support Google services, use the following versions:
    // implementation 'com.netmera:nmcore:4.0.0'
    // implementation 'com.netmera:nmfcm:4.0.0'

    // For applications that only want to support Huawei devices, use these dependencies:
    // implementation 'com.netmera:nmcore:4.0.0'
    // implementation 'com.netmera:nmhms:4.0.0'
}

// Must be added at the bottom of the app's build.gradle
apply plugin: 'com.google.gms.google-services'
apply plugin: 'com.huawei.agconnect'

Step 5. Initialize Netmera SDK

Initializing Netmera SDK After Android SDK Version 4.0.0

If you are using SDK version 4.0.0 or later, or performing an SDK update, do not include the following lines of code from previous SDK versions. If these lines are already present in your code, please remove them:

// Removed components in SDK 4.0.0
NMInitializer.initializeComponents(this)
AppInitializer.getInstance(this).initializeComponent(NMFCMProviderInitializer::class.java)
AppInitializer.getInstance(this).initializeComponent(NMHMSProviderInitializer::class.java)

1. Add initialization code in onCreate() method:

To ensure proper initialization, add the code below within the onCreate() method of your class that extends android.app.Application

If your project does not currently have a class that extends Application:

1. Create an Application Class

   • If your project does not currently have a class that extends Application, create one.

2. Update AndroidManifest File:

   • Add the newly created or existing Application class to your AndroidManifest.xml file using the android:name attribute within the <application> tag. Then, add initialization code below.

Kotlin

override fun onCreate() {
    super.onCreate()
// Must be called on the Main Thread
    registerActivityLifecycleCallbacks(NMActivityLifecycleCallbacks(this))

    val configBuilder = NetmeraConfiguration.Builder()
        .apiKey(apiKey)
        .firebaseSenderId(PropertiesUtil.gcmSenderId)
        .huaweiSenderId(PropertiesUtil.hmsSenderId)  // Init example if you are going to call Huawei services
        .logging(true)  // Allows Netmera logs to appear in logcat
        .addProvider(NMFCMProvider())
        .addProvider(NMHMSProvider())
    Netmera.init(configBuilder.build(this))
}

Java

@Override
public void onCreate() {
    super.onCreate();
    // Must be called on the Main Thread
    registerActivityLifecycleCallbacks(new NMActivityLifecycleCallbacks(this));

    NetmeraConfiguration.Builder configBuilder = new NetmeraConfiguration.Builder();
    configBuilder.apiKey(apiKey)
                 .firebaseSenderId(PropertiesUtil.gcmSenderId)
                 .huaweiSenderId(PropertiesUtil.hmsSenderId)  // Init example if you are going to call Huawei services
                 .logging(true);  // Allows Netmera logs to appear in logcat
                 .addProvider(new NMFCMProvider())
                 .addProvider(new NMHMSProvider())
    Netmera.init(configBuilder.build(this));
}

Initializing Netmera SDK Before Android SDK Version 4.0.0

Add initialization code in onCreate() method:

To ensure proper initialization, add the code below within the onCreate() method of your class that extends android.app.Application. If your project does not currently have a class that extends Application, create one. Add the newly created or existing Application class to your AndroidManifest.xml file using the android:name attribute within the <application> tag. Then, add initialization code below.

Kotlin:

override fun onCreate() {
    super.onCreate()

    val configBuilder = NetmeraConfiguration.Builder()
        .apiKey(apiKey)
        .firebaseSenderId(PropertiesUtil.gcmSenderId)
        .huaweiSenderId(PropertiesUtil.hmsSenderId)  // Init example if you are going to call Huawei services
        .logging(true)  // Allows Netmera logs to appear in logcat
    Netmera.init(configBuilder.build(this))
}

Java:

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

    NetmeraConfiguration.Builder configBuilder = new NetmeraConfiguration.Builder();
    configBuilder.apiKey(apiKey)
                 .firebaseSenderId(PropertiesUtil.gcmSenderId)
                 .huaweiSenderId(PropertiesUtil.hmsSenderId)  // Init example if you are going to call Huawei services
                 .logging(true);  // Allows Netmera logs to appear in logcat

    Netmera.init(configBuilder.build(this));
}

Warning: Init Method Must Be Added in the Main Thread

Ensure that init methods are added in the main thread. Adding them in the background may lead to unexpected behavior and potential issues.

Autostart Troubleshooting:

Once these enhancements are implemented, you only need to call our initialization method and create NetmeraConfigurations. The SDK will then automatically handle everything else. This automation works because we use Android's AutoStartup framework, which runs before the initialization method is invoked.

However, if AutoStartup is disabled in your application, you can manually integrate Netmera using the example code block provided below. There’s no need to use Initializer classes unless AutoStartup is turned off.

Kotlin:

fun onCreate() {
super.onCreate()
	NMInitializer.initializeComponents(this)
        AppInitializer.getInstance(this).initializeComponent(NMFCMProviderInitializer::class.java)
        AppInitializer.getInstance(this)
            .initializeComponent(NMHMSProviderInitializer::class.java) //==> Init example if you are going to call Huawei services;
        val configBuilder: NetmeraConfiguration.Builder = Builder()
        configBuilder.baseUrl(baseUrl).apiKey(apiKey)
            .firebaseSenderId(PropertiesUtil.gcmSenderId)
            .huaweiSenderId(PropertiesUtil.hmsSenderId) //==> Init example if you are going to call Huawei services;
            .logging(true) //==>  Allows netmera logs to appear in logcat
            .disableSerializeRule(false)  //it should be only set to false or it should not be set at all
            .nmInAppMessageActionCallbacks(NGInAppMessageActionCallbacks())
            .nmPushActionCallbacks(NGPushActionCallbacks())
            .nmWebWidgetCallbacks(NGWebWidgetCallbacks())
        Netmera.init(configBuilder.build(this))
}

Java:

@Override public void onCreate() {
    super.onCreate();
NMInitializer.initializeComponents(this);
AppInitializer.getInstance(this).initializeComponent(NMFCMProviderInitializer.class);
AppInitializer.getInstance(this).initializeComponent(NMHMSProviderInitializer.class);  //==> Init example if you are going to call Huawei services;
NetmeraConfiguration.Builder configBuilder = new NetmeraConfiguration.Builder();
configBuilder.baseUrl(baseUrl).apiKey(apiKey)
    .firebaseSenderId(PropertiesUtil.gcmSenderId)
    .huaweiSenderId(PropertiesUtil.hmsSenderId) //==> Init example if you are going to call Huawei services;
    .logging(true)  //==>  Allows netmera logs to appear in logcat
    .disableSerializeRule(false)
    .nmInAppMessageActionCallbacks(new NGInAppMessageActionCallbacks())
    .nmPushActionCallbacks(new NGPushActionCallbacks())
    .nmWebWidgetCallbacks(new NGWebWidgetCallbacks());
Netmera.init(configBuilder.build(this));

}

Implementation Note: Configuring baseUrl for On-Premise Applications

• For On-Premise Applications: If your application is on-premise, include the following code to configure the base URL and API key:

  configBuilder.baseUrl(baseUrl).apiKey(apiKey);

• For Non-On-Premise Applications: If your application is not on-premise, only the API key needs to be configured:

  configBuilder.apiKey(apiKey);

Optional: Initialization Callback

Adding callbacks to the initialization method is optional. In Android Core Update version 3.11.3, onSuccess and onFailure callbacks were introduced for the Init method. Below is an example of how to implement this: For more detailed information, you can visit the following page >Push Callbacks

Kotlin

Netmera.init(
    configBuilder.build(this), 
    object : NMInitSessionListener {
        override fun onSuccess() {
            Log.i("NetmeraApp", "Session init completed")
        }

        override fun onFailure(error: String?) {
            Log.e(
                "NetmeraApp",
                "Error occurred when trying to init session with Netmera. Error::$error"
            )
        }
    }
)

Java

Netmera.init(
    configBuilder.build(this),
    new NMInitSessionListener() {
        @Override
        public void onSuccess() {
            Log.i("NetmeraApp", "Session init completed");
        }

        @Override
        public void onFailure(String error) {
            Log.e(
                "NetmeraApp",
                "Error occurred when trying to init session with Netmera. Error::" + error
            );
        }
    }
);

Optional: Enable Logging

You can also enable logging by adding the following code in the onCreate() method of your class that extends android.app.Application.This will enable logging, allowing you to monitor and debug the SDK's operations more effectively.

Set .logging (false) while on prod:

When preparing your app for release to the store, ensure that .logging is disabled (set to false) in the production environment.

Kotlin

.logging(true)

Java

Netmera.logging(true);

Step 6. Android 13 Push Notification Permissions

For apps targeting API Level 33 (Android 13) and above, you can now request push notification permissions directly from users. This is controlled by the Android operating system.

• For Apps Targeting API Level 33 and Above: You need to explicitly request push notification permissions from users. This is done through your app's code.

• For Apps Targeting API Level 32 and Below: On devices running Android 13 or higher, the system will automatically prompt users for push notification permissions when the app creates notification channels. This happens when you initialize the Netmera SDK at the application level.

• On Android 12 and Earlier: The system treats push notification permissions as granted by default, so no additional action is needed.

This means that for most apps, especially those targeting older API levels, the permission request will be handled automatically when the app starts.

Push Permission Methods in Netmera SDK

For applications targeting API 33, here's how you can use Netmera SDK when requesting push permission. At this stage, there are two important methods in Netmera SDK.

Kotlin

Netmera.requestNotificationPermissions(this)

This method must be added in the main activity below super.Oncreate(savedInstanceState). It triggers the necessary methods to send a request for permissions to the system at any time.

Java

Netmera.requestNotificationPermissions(this);

This method must be added in the main activity below super.Oncreate(savedInstanceState). It triggers the necessary methods to send a request for permissions to the system at any time.

Push Enable/Disable:

1. The users triggers the requestNotificationPermissions() method, the user grants permission (push enable request is sent).

After the customer receives a denial, they send the same request again (it is recommended by Google not to resend it immediately after receiving a denial), and the SDK opens the Notification settings that are specific to that application on the operating system. The user grants notification permission from the settings and returns to the application (push enable request is sent).

1. The users triggers the requestNotificationPermissions() method, the user denies permission (push disable request is sent).

After the customer receives a denial, they send the same request again (it is recommended by Google not to resend it immediately after receiving a denial), and the SDK opens the Notification settings that are specific to that application on the operating system. The user cancels (presses the back button) (push disable request is sent).

This method allows checking whether the necessary permissions for the application have been obtained. If the required permissions have been obtained from the user by the system, the method will return true, otherwise, it will return false.

Kotlin

fun areNotificationsEnabled(): Boolean

Java

public static boolean areNotificationsEnabled()

Optional: Email Preferences

In version 3.9.18, a feature related to Email Preferences has been introduced. By invoking the following method, you can request email permission from users.

Kotlin

fun setEmailPermission(isAllowed: Boolean) 

Java

public static void setEmailPermission(boolean isAllowed);

To clarify, if you execute the following code:

Kotlin

Netmera.setEmailPermission(false)

Java

Netmera.setEmailPermission(false);

It means that email permission is revoked on your end.

Conversely, if you execute:

Kotlin

Netmera.setEmailPermission(true)

Java

Netmera.setEmailPermission(true);

It signifies that permission for sending emails is granted.

Optional: Firebase Messaging Service Class

If you are incorporating Netmera's push notifications alongside another Firebase Cloud Messaging (FCM) integration, here's what you need to do:

1. In your Firebase Messaging Service class, consider calling Netmera's onNetmeraPushMessageReceived method in your own onMessageReceived method.

2. When your FCM token is renewed, remember to call the onNetmeraNewToken method to ensure the new token is forwarded to Netmera. You can do this by calling Netmera.onNetmeraNewToken(token).

By following these steps, you can seamlessly integrate Netmera's push notifications into your existing FCM setup.

Kotlin

class PushMessaging : FirebaseMessagingService() {

    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        super.onMessageReceived(remoteMessage)

        if (Netmera.isNetmeraRemoteMessage(remoteMessage)) {
            Netmera.onNetmeraPushMessageReceived(remoteMessage)
        } else {
            // another operations
        }
    }

    override fun onNewToken(token: String) {
        super.onNewToken(token)
        Netmera.onNetmeraNewToken(token)
    }
}

Java

public class PushMessaging extends FirebaseMessagingService {

  @Override
  public void onMessageReceived(RemoteMessage remoteMessage) {
       super.onMessageReceived(remoteMessage);

       if (Netmera.isNetmeraRemoteMessage(remoteMessage)) {

          Netmera.onNetmeraPushMessageReceived(remoteMessage);

        } else {
            //another operations
        }
   }


 @Override
    public void onNewToken(String token) {
        super.onNewToken(token);

           Netmera.onNetmeraNewToken(token);
    }
}

Important Note for Obfuscation:

If you are obfuscating your code, you don't need to add any specific rules for Netmera. Netmera's functionality remains intact even with code obfuscation.

Push Callbacks

Netmera provides the following push callbacks:

• Push Register, Push Receive, Push Open, Push Dismiss, Push Button Click

If you would like to use push callbacks in Netmera, please visit our documentation Push Callbacks.

Android SDK integration completed 👍

Android SDK integration has been successfully completed, and your devices are now ready to receive the following types of push notifications sent via the Netmera Dashboard:

1. Standard Push Notifications

2. Interactive Push Notifications

3. Widgets ( Enable/Disable Widget and In App Messages)

4. Push Notifications with Deeplinks (Android Deeplink)

Onboarding Checklist: iOS and Android

Please find the Onboarding Checklist for iOS and Android below. Follow the titles in the checklist to ensure you have completed each essential step in your onboarding process with Netmera.

44KB

Netmera Mobile Technical Onboarding Checklist.xlsx

Warning During App Store Submission:

During your application's store submission, you may encounter the com.google.android.gms.permission.AD_ID alert. In this case, after proceeding with 'yes,' on the subsequent page, the 'analytics' option should also be selected. After this selection, there is no need for any additional additions to the manifest; merging the manifest is sufficient.