Android SDK Integration

Quick Steps Guidelines

Step 1: Select a Platform

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

Step 2: Create A Firebase Cloud Messaging Configuration

Set up Firebase Cloud Messaging (FCM) with proper API keys and project settings.

Step 3: Select A Target SDK

Choose the appropriate SDK for your application.

Step 4 and 5: Integrate and Initialize Netmera SDK

Add Netmera SDK dependencies and initialize in MainActivity.

Step 6: Android 13 Push Notification Permissions

Request push notification permissions for API Level 33+.

Onboarding Checklist: 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 Developers > Netmera Onboarding.

2. Select Android and click Start to proceed.

Step 2: Create a Firebase Configuration

Netmera uses Firebase Cloud Messaging (FCM) for delivering push notifications.

1. Go to the Firebase Developers Console and create a new project.

2. Generate a new Private Key (JSON file) for your project.

1. Upload the JSON file you downloaded from Firebase Cloud Messaging to the Project > app-level root directory.

1. Choose one of the four options: Node.js, Java, Python, and Go. The choice of option does not require any action. Simply click the 'Generate New Private Key' button to download the file. No further selections are needed.

1. Upload this file in Netmera Panel > Developers > Netmera Onboarding > Android > Step 2: Create A Firebase Configuration > FCM Service Account Key.

Step 3: Select a Target SDK

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

Step 4: Integrate Netmera SDK

Important Notes on SDK API Key:

• Do not use the API key from a test panel in production.

• Each panel has a unique API key, and using the wrong one can result in data misdirection or errors.

To obtain your SDK API Key:

1. Go to the Netmera Panel.

2. Navigate to Developer > API > SDK API Key.

3. Copy your SDK API Key from this section.

Standard Gradle

If your project is using Standard Gradle:

• Add the following snippets to integrate the Netmera SDK into your project.

Project's build.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/'} // only include for HMS copy the url and add it to maven
    }
    dependencies {

    classpath 'com.android.tools.build:gradle:{your_project_android_tools_version}'
    classpath 'com.google.gms:google-services:{your_google_services_version}'
    classpath 'com.huawei.agconnect:agcp:{your_agcp_version}' // only include for HMS 
    }
}

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

App's build.gradle

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

Check Android SDK Versions to find the SDK versions listed as '4.x.x' below.

dependencies {

    implementation 'com.netmera:nmcore:4.x.x'
    implementation 'com.netmera:nmfcm:4.x.x'
    implementation 'com.netmera:nmhms:4.x.x'

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

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

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

Gradle Version Catalogs

If your project is using Gradle Version Catalogs:

• Add the following snippets to integrate the Netmera SDK into your project.

Kotlin

Project's build.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
}

If you want to integrate Huawei Mobile Services (HMS), add the following configuration to your build.gradle file before plugins. Following part is only for Huawei integration.

// This part is only for Huawei integration
buildscript {
    val agpVersion = "YOUR_PROJECT_AGP_VERSION"
    repositories {
        maven {
            url = uri("https://developer.huawei.com/repo/")
        }
    }
    dependencies {
        classpath("com.huawei.agconnect:agcp:your_agcp_version")
    }
}

plugins {
    ...
}

For more information, visit the following link: Huawei AppGallery Connect Guide.

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.

App's build.gradle

plugins {
    alias(libs.plugins.androidApplication)
    alias(libs.plugins.jetbrainsKotlinAndroid)
    alias(libs.plugins.google.services)
    id("com.huawei.agconnect") // only include for HMS
}
dependencies {
    implementation(libs.netmera.core)
    implementation(libs.netmera.fcm)
    implementation(libs.netmera.hms) // only include for HMS
}

settings.gradle

dependencyResolutionManagement {
    repositories {
        google() 
        maven { 
          url = uri("https://release.netmera.com/release/android")
        }
        maven {
          url = uri("https://developer.huawei.com/repo/") // only include for HMS
        }
    }
}

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

libs.version.toml

Check Android SDK Versions to find the SDK versions listed as '4.x.x' below.

[versions]
netmeraCore = "4.x.x"
netmeraFcm = "4.x.x"
netmeraHms = "4.x.x"
googleServices = "your_google_services_version"
[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" } // only include for HMS
[plugins]
google-services = { id = "com.google.gms.google-services", version.ref = "googleServices" }

Groovy

Project's build.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
}

If you want to integrate Huawei Mobile Services (HMS), add the following configuration to your build.gradle file before plugins. Following part is only for Huawei integration.

// This part is only for Huawei integration
buildscript {
    val agpVersion = "YOUR_PROJECT_AGP_VERSION" //
    repositories {
        maven { url 'https://developer.huawei.com/repo/' }
    }
    dependencies {
        classpath "com.huawei.agconnect:agcp:your_agcp_version"
    }
}

plugins {
    ...
}

For more information, visit the following link: Huawei AppGallery Connect Guide.

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.

App's build.gradle

plugins {
    alias(libs.plugins.androidApplication)
    alias(libs.plugins.jetbrainsKotlinAndroid)
    alias(libs.plugins.google.services)
    id("com.huawei.agconnect") // only include for HMS
}
dependencies {
    Implementation libs.netmera.core
    Implementation libs.netmera.fcm
    Implementation libs.netmera.hms // only include for HMS
}

settings.gradle

dependencyResolutionManagement {
    repositories {
        google()
        maven {
            url "https://release.netmera.com/release/android"
        }
        maven {
            url "https://developer.huawei.com/repo/"
        }
    }
}

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

libs.version.toml

Check Android SDK Versions to find the SDK versions listed as '4.x.x' below.

[versions]
netmeraCore = "4.x.x"
netmeraFcm = "4.x.x"
netmeraHms = "4.x.x" // only include for HMS
googleServices = “your_google_services_version”
[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" } // only include for HMS
[plugins]
google-services = { id = "com.google.gms.google-services", version.ref = "googleServices" }

Step 5: Initialize Netmera SDK

Initializing Netmera SDK Android v4.0.0+

1. Add the following initialization code inside the onCreate() method of your Application class.

If Application Class is Not Already Present:

1. Create an Application Class

If your project doesn't yet have an Application class, create one and include the initialization code as shown below.

1. Update AndroidManifest.xml

In the AndroidManifest.xml, add your Application class by specifying android:name in the <application> tag.

Kotlin

registerActivityLifecycleCallbacks method must be called in the Main Threat.

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)  // only include for HMS
        .logging(true)  // enables logging in logcat
        .addProvider(NMFCMProvider())
        .addProvider(NMHMSProvider()) // only include for HMS
    Netmera.init(configBuilder.build(this))
}

Java

registerActivityLifecycleCallbacks method must be called in the Main Threat.

@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)  // only include for HMS
                 .logging(true);  // enable logging in logcat
                 .addProvider(new NMFCMProvider())
                 .addProvider(new NMHMSProvider());  // only include for HMS
    Netmera.init(configBuilder.build(this));
}

Removed Components in Android SDK v4.0.0+

If you are using Netmera Android SDK version 4.0.0 or later, or performing an SDK update,

• Do not include the following lines of code from previous SDK versions when initializing Netmera SDK.

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

Initializing Netmera SDK Before Android SDK Version 4.0.0

Add initialization code in onCreate() method:

1. Add the code below within the onCreate() method of your class that extends android.app.Application.

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

3. Add the newly created or existing Application class to your AndroidManifest.xml file using the android:name attribute within the <application> tag.

4. Add initialization code below.

Kotlin

override fun onCreate() {
    super.onCreate()

    val configBuilder = NetmeraConfiguration.Builder()
        .apiKey(apiKey)
        .firebaseSenderId(PropertiesUtil.gcmSenderId)
        .huaweiSenderId(PropertiesUtil.hmsSenderId)  // only include for HMS
        .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) // only include for HMS
                 .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:

After implementing the necessary enhancements above:

1. Call the Initialization Method Use the provided initialization method to set up Netmera in your application.

2. Create NetmeraConfiguration Configure the SDK by creating and passing the required NetmeraConfiguration object.

Once these steps are completed, the Netmera SDK will automatically handle the rest. This automation is possible because Netmera leverages Android's AutoStartup framework. This framework ensures that certain processes are executed before the initialization method is invoked, streamlining the SDK's setup and operation.

If the AutoStartup Feature is Disabled in Your Application:

You can continue using the Netmera SDK by calling the following code block above the init method:

Kotlin

fun onCreate() {
    super.onCreate()
    NMInitializer.initializeComponents(this)
    AppInitializer.getInstance(this).initializeComponent(NMFCMProviderInitializer::class.java)
    AppInitializer.getInstance(this).initializeComponent(NMHMSProviderInitializer::class.java) // only include for HMS       
    ...
    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); // only include for HMS   
    ...
    Netmera.init(configBuilder.build(this));
}

Configuring baseUrl for On-Premise Applications

• For On-Premise Applications: Include the following code to configure the base URL and API key:

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

• For Non-On-Premise Applications: Only the API key needs to be configured:

  configBuilder.apiKey(apiKey);

Optional: Initialization Callback

To implement the initialization callback:

1. Add the following code to handle success and failure:

For detailed information, you can visit >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

To enable logging for debugging, add the following code in the onCreate() method of your Application class:

1. Enable logging:

Kotlin

.logging(true)

Java

Netmera.logging(true);

1. Disable logging for production:

When preparing your app for release, set .logging(false)

Kotlin

.logging(false)

Java

Netmera.logging(false);

Set .logging (false) while on prod:

Before releasing your app to the store, make sure that .logging is disabled (set to false) in the production environment.

Step 6: Android 13 Push Notification Permissions

Android 13 introduced significant changes to how push notification permissions are handled.

• Increased User Control: Apps targeting API Level 33 and above now have more control over when and how they request push notification permissions. This allows for a more user-friendly and context-aware permission request experience.

• Automatic Permission Requests for Older Apps: For apps targeting API Level 32 and below running on Android 13, the system automatically prompts the user for push notification permission when the app creates its first notification channel.

Impact on Netmera SDK Users:

The Netmera SDK initializes and creates notification channels during the app's startup. Consequently:

• On Android 13: For apps targeting API Level 32 and below, this initialization process will trigger the automatic system prompt for push notification permission.

• On Android 12 and below: The system generally assumes push notification permission has already been granted.

If you initialize the Netmera SDK at app startup (which is recommended), the system will automatically request push notification permissions on Android 13 devices for apps targeting API Level 32 and below. For devices running Android 12 or earlier, the system assumes permission is already granted.

Push Permission Methods in Netmera SDK

For applications targeting API 33, Netmera SDK offers two key methods for requesting push permission:

1. Requesting Push Permission (API Level 33 and Above):

• Method: Netmera.requestNotificationPermissions(this)

• Add this method in the onCreate() method of your MainActivity, below super.onCreate(savedInstanceState) to request push notification permissions from the user.

Kotlin

Netmera.requestNotificationPermissions(this)

Java

Netmera.requestNotificationPermissions(this);

1. Checking Notification Status:

• Method: fun areNotificationsEnabled(): Boolean

• This method allows checking whether the necessary permissions for the application have been obtained. It returns true if notifications are enabled, otherwise false.

Kotlin

fun areNotificationsEnabled(): Boolean

Java

public static boolean areNotificationsEnabled()

Push Enable/Disable User Flow:

1. Granting Permission:

   • The user triggers requestNotificationPermissions(), and if they grant permission, a push enable request is sent.

2. Handling Denial:

   • If the user denies permission, avoid resending the request immediately (as recommended by Google). Instead, the SDK opens the app's notification settings. The user can grant permission from the settings and return to the app, where a push enable request is sent.

3. Denying Permission:

   • If the user triggers requestNotificationPermissions() and denies permission, a push disable request is sent.

4. Reattempt After Denial:

   • If denied, avoid immediate re-request. The SDK will open the app's notification settings. If the user cancels (presses the back button), a push disable request is sent.

Optional: Email Permission Preferences

In version 3.9.18, the Email Preferences feature allows you to request email permission from users. Use the following method to manage email permission:

Kotlin

fun setEmailPermission(isAllowed: Boolean) 

Java

public static void setEmailPermission(boolean isAllowed);

Revoking Email Permission:

• To revoke email permission, execute the following code:

Kotlin

Netmera.setEmailPermission(false)

Java

Netmera.setEmailPermission(false);

Granting Email Permission:

• To grant email permission, execute:

Kotlin

Netmera.setEmailPermission(true)

Java

Netmera.setEmailPermission(true);

Optional: Firebase Messaging Service Class

To integrate Netmera’s push notifications alongside Firebase Cloud Messaging (FCM), follow these steps:

1. Override onMessageReceived

In your Firebase Messaging Service class, call Netmera's onNetmeraPushMessageReceived method inside your own onMessageReceived method.

1. Handle FCM Token Renewal

When the FCM token is renewed, call the Netmera.onNetmeraNewToken(token) method below to forward the new token to Netmera. Use the following code to do so:

Kotlin

class PushMessaging : FirebaseMessagingService() {
    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        super.onMessageReceived(remoteMessage)

        if (Netmera.isNetmeraRemoteMessage(remoteMessage)) {
            Netmera.onNetmeraPushMessageReceived(remoteMessage)
        } else {
            // Other 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 {
            // Other operations
        }
    }

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

Important Note for Obfuscation:

No special obfuscation rules are needed for Netmera. Its functionality remains unaffected, even with code obfuscation enabled.

Push Callbacks

Netmera provides the following push callbacks for better push notification management:

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

For detailed implementation, please refer to the full documentation > Push Callbacks

Android SDK Integration Complete 🎉

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

• Standard Push Notifications

• Interactive Push Notifications

• Widgets

• Push Notifications with Deeplinks

Warning During App Store Submission:

When submitting your application to the App Store, you might encounter the com.google.android.gms.permission.AD_ID alert. Here’s how to handle it:

1. Choose 'Yes' when prompted.

2. On the subsequent page, make sure the 'analytics' option is selected.

3. After this, no further additions to the manifest are required; simply merging the manifest will suffice.