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 eSputnik 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 (minSdk = 26).
• Compiler: Java 1.8 compiler is required for the integration.

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

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.RetenoApplication;
import com.reteno.core.RetenoImpl;

public class CustomApplication extends Application {

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

📘

ANR during initialization

Initialization runs in Application.onCreate(). Use a current SDK version — the heavy initialization work is moved to background threads there.

Older versions initialized synchronously on the main thread, which could cause ANRs at app start. If you observe an ANR pointing at SDK initialization, update the SDK — see Android SDK Release Notes.

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

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

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.

• 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

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.