Android SDK Integration Guide

The Reteno Android SDK is a lightweight library designed for mobile teams to integrate customer engagement and analytics solutions into their Android applications. It provides a simple interface to interact with the Reteno API.

Watch our comprehensive setup guide:

GitHub repo

Table of Contents

1. Overview & Requirements
2. Step 1: Project Configuration
3. Step 2: Dependencies
4. Step 3: Initialization
5. Step 4: Accessing the SDK
6. Step 5: Push notifications

Overview & Requirements

• Language Support: Native Android applications written in Java or Kotlin.
• OS Support: Android 8.0 or later (API 26). The artifacts declare minSdkVersion 21, so an application with a lower minimum still builds and installs — the SDK features stay off below API 26. See Android Old Versions Support.
• Compiler: Java 1.8 compiler is required for the integration.

Raising your application's target API doesn't call for a different SDK version: the SDK declares no foreground service, so the Android 15 foreground-service changes don't reach it.

Step 1: Project Configuration

Enable AndroidX

In your project's gradle.properties file, ensure AndroidX is enabled:

android.useAndroidX=true

Compiler options

In your application-level build.gradle, set Java 1.8 (or later) compatibility:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}

Step 2: Dependencies

Repository Setup

Add the mavenCentral() repository to your project-level settings.gradle file:

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

SDK and Firebase Dependencies

Add the following to your application-level build.gradle:

dependencies {
    implementation 'com.reteno:fcm:(latest_version_here)'
    implementation "com.google.firebase:firebase-messaging:23.1.0"
    implementation "com.google.firebase:firebase-messaging-ktx:23.1.0"
}

R8 and ProGuard

The SDK ships its own consumer rules, so no additional keep rules are required. Validate your minified release build when enabling R8.

Step 3: Initialization

To get started, initialize the SDK in your custom Application class using your SDK_ACCESS_KEY. You can obtain access key, using this guide

package [com.YOUR_PACKAGE];

import android.app.Application
import com.reteno.core.Reteno
import com.reteno.core.RetenoConfig
        
class CustomApplication: Application() {
    override fun onCreate() {
        super.onCreate()
        Reteno.initWithConfig(
            RetenoConfig.Builder()
                .accessKey("your_access_key_here")
                .build()
        )
    }
}

package [com.YOUR_PACKAGE];

import android.app.Application;

import androidx.annotation.NonNull;

import com.reteno.core.Reteno;
import com.reteno.core.RetenoConfig;

public class CustomApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        Reteno.initWithConfig(
                new RetenoConfig.Builder()
                        .accessKey("your_access_key_here")
                        .build()
        );
    }
}

Manifest Registration: Ensure your manifest uses the custom Application class:

<application
    android:name=".CustomApplication"
    ... >
</application>

📘

Initialization and ANR

The SDK is initialized in Application.onCreate(), which runs on the main thread. Use an up-to-date SDK version — the heavy parts of initialization are moved to background threads there, so the call returns quickly.

Older versions performed more of this work synchronously on the main thread, which could produce an ANR during app start-up. If you see ANR reports pointing at the SDK initialization, update the SDK to the current version — see SDK Release Notes.

Advanced Configuration

The RetenoConfig.Builder allows for deep customization during initialization:

• accessKey(String): Your API access key.

• pauseInAppMessages(Boolean): Controls the paused state for in-app messaging.

• customDeviceIdProvider(DeviceIdProvider): Allows providing a custom ID if identification comes from an external source or with a delay.

• lifecycleTrackingOptions(LifecycleTrackingOptions): Configures automatic app lifecycle event tracking.

• pausePushInAppMessages(Boolean): Stops or resumes receiving in-app messages delivered via push.

• defaultNotificationChannelConfig: Customizes the notification channel.

• sessionDuration(Long): Session length in milliseconds. The default is 3 hours (3 * 60 * 60 * 1000). Available from Android SDK 2.9.3.

• setDebug(Boolean): Whether to use debug mode. Read more on how to use debug mode

RetenoConfig.Builder()
    .pauseInAppMessages(false)
    .customDeviceIdProvider(createProvider())
    .lifecycleTrackingOptions(LifecycleTrackingOptions.ALL)
    .accessKey("your_access_key")
    .pausePushInAppMessages(true)
    .defaultNotificationChannelConfig { 
        it.setName("Custom name")
        it.setDescription("Custom description")
    }
    .build()

new RetenoConfig.Builder()
        .pauseInAppMessages(false)
        .customDeviceIdProvider(createProvider())
        .lifecycleTrackingOptions(LifecycleTrackingOptions.ALL)
        .accessKey("your_access_key")
        .pausePushInAppMessages(true)
        .defaultNotificationChannelConfig((builder) -> { 
           builder.setName("Custom name")
           builder.setDescription("Custom description")
           return Unit.INSTANCE;
        }
        .build();

Step 4: Accessing the SDK

Access the SDK via the Singleton instance:

Kotlin: val reteno = Reteno.instance

Java: Reteno reteno = Reteno.getInstance();

Step 5: Push notifications

Notification icon and color

Optional. Set a default icon and color for all Reteno notifications in AndroidManifest.xml. The icon has to be a monochrome white image on a transparent background, which is what Android expects of a notification icon.

<meta-data
            android:name="@string/notification_icon"
            android:resource="@drawable/ic_notification" />

<meta-data
            android:name="@string/notification_icon_color"
            android:resource="@color/red_dark" />

Since Android 12 the user can change the color scheme of the whole device through Material You, so the icon color can look different on recent devices.

Request push notification permissions

For basic permission handling, use the built-in SDK helper that simplifies permission request:

lifecycleScope.launch {
    val isGranted = RetenoNotifications.requestNotificationPermission()
    // Handle the result (true/false)
}

For more advanced set up, if the app requires to manually request push notifications, you must call updatePushPermissionStatus() once the user grants permission to notify the SDK.

Reteno.instance.updatePushPermissionStatus()

Reteno.getInstance().updatePushPermissionStatus();

Check out push notification documentation details on how to set up and process incoming notifications, custom data, and user interactions.