Android Appsalt SDK Integration guide

This short guide aims to help you in successfully integrating SDK to your project. In this tutorial we are using Android Studio IDE, but you can integrate using any IDE of your preferences.

info

Don't forget to generate your Appsalt SDK API Key and download SDK from Developers dashboard first.

warning

Restriction for Google Play Apps. SDK cannot be integrated into applications distributed via Google Play. Minimum required Android API level is 21 (Android 5.0 / Lollipop). Also for Google Play integration you MUST talk to your account manager or someone from [email protected].

Installation

Add appsalt.aar file into your libraries directory and add these dependencies to your app level build script

Gradle (Kotlin)
Gradle (Groovy)

gradle.build.kts
dependencies {
    implementation(files("libs/appsalt.aar"))
    implementation("org.msgpack:msgpack-core:0.9.11")
    implementation("com.google.protobuf:protobuf-javalite:3.25.3")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
}

Exemplary files structure:

my-application
├── app
│   ├── libs
│   │   ├── appsalt.aar
│   ├── src
│   │   ├── main
│   │   └── AndroidManifest.xml
│   └── build.gradle.kts
├── gradle.properties
├── gradlew
...

gradle.build
dependencies {
    implementation files('libs/appsalt.aar')
    implementation 'org.msgpack:msgpack-core:0.9.11'
    implementation 'com.google.protobuf:protobuf-javalite:3.25.3'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.0'
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
}

Exemplary project files structure:

my-application
├── app
│   ├── libs
│   │   ├── appsalt.aar
│   ├── src
│   │   ├── main
│   │   └── AndroidManifest.xml
│   └── build.gradle
├── gradle.properties
├── gradlew
...

SDK setup

Our SDK requires internet connectivity to work. To allow your app to use internet connection add following permission to AndroidManifest.xml file.

AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <uses-permission android:name="android.permission.INTERNET" />

    <application ...
    </application>
</manifest>

You need to initialize SDK by calling Appsalt.initialize(context, apiKey) function by providing Android context and your api key. Best place to do that is either in Application or Activity class.

warning

It is highly recommended to initialize SDK in Application scope, especially if you are going to use settings such as Appsalt.launchOnBoot = true or Appsalt.isBackground = true.

Configure SDK settings right after initializing the SDK, but before calling the start() function.

Kotlin
Java

App.kt
package com.example.app

import android.app.Application
import com.appsalt.Appsalt

class App : Application() {

    override fun onCreate() {
        super.onCreate()
        Appsalt.initialize(this, "your-api-key")
        // SDK configuration goes here
    }
}

App.java
package com.example.app;

import android.app.Application;
import com.appsalt.Appsalt;

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        Appsalt.initialize(this, "your-api-key");
        // SDK configuration goes here
    }
}

Starting SDK

You need to get a legal consent from the user before starting SDK (SDK will not start without user consent). The simplest way to do that is to call Appsalt.requestConsent() method.

tip

If provided consent screen feels out of place, you may change its colors and style with parameterized variation of Appsalt.requestConsent(..). Check SDK API section for more information.

After consent is provided, you can call Appsalt.start(). When consent screen closes you can check if consent was given in onResume() function using Appsalt.isOptedIn value.

Kotlin
Java

MainActivity.kt
package com.example.app

import android.app.Activity
import com.appsalt.Appsalt

class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        if (Appsalt.isOptedIn) {
            Appsalt.start()
        } else {
            Appsalt.requestConsent()
        }
    }

    override fun onResume() {
        super.onResume()
        if (Appsalt.isOptedIn && !Appsalt.isRunning) {
            Appsalt.start()
        }
    }
}

MainActivity.java
package com.example.app;

import android.app.Activity;
import com.appsalt.Appsalt;

public class MainActivity extends Activity {

    @Override
    void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (Appsalt.isOptedIn()) {
            Appsalt.start();
        } else {
            Appsalt.requestConsent();
        }
    }

    @Override
    void onResume() {
        super.onResume()
        if (Appsalt.isOptedIn() && !Appsalt.isRunning()) {
            Appsalt.start();
        }
    }
}

Stopping SDK

Call Appsalt.stop() in order to stop SDK.

User should be able to opt out from using SDK at any time. When user does so within your app, you should call Appsalt.optOut() function, which will immediately stop SDK and will no longer start it unless user grants consent again.

Running in background

warning

In most cases if Appsalt.isBackground is set to false (default) SDK will only run for a short while after your application is closed, because Android system will shut it down as well.

If you want to keep SDK running in background when app is closed, you need to take some additional steps. A few additional FOREGROUND_SERVICE permission are required. Add them to your AndroidManifest.xml

AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <uses-permission android:name="android.permission.INTERNET" />

    <!-- Permissions for background functionality -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />

    <application ...
    </application>
</manifest>

Then let SDK know that you want to allow it to run in the background.

Kotlin
Java

App.kt
package com.example.app

import android.app.Application
import com.appsalt.Appsalt

class App : Application() {

    override fun onCreate() {
        super.onCreate()
        Appsalt.initialize(this, "your-api-key")
        // SDK configuration goes here
        Appsalt.isBackground = true
        // (optional) Notification customization
        Appsalt.notification = yourNotification
        Appsalt.notificationId = yourNotificationId
        // ...
    }
}

App.java
package com.example.app;

import android.app.Application;
import com.appsalt.Appsalt;

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        Appsalt.initialize(this, "your-api-key");
        // SDK configuration goes here
        Appsalt.setBackground(true);
        // (optional) Notification customization
        Appsalt.setNotification(yourNotification);
        Appsalt.setNotificationId(yourNotificationId);
        // ...
    }
}

info

Android requires to provide a notification for any process which runs in background. Appsalt SDK provides a default notification with Appsalt icon, but you can always overwrite it with your own notification by setting Appsalt.notification and Appsalt.notificationId variables. Check SDK API section for more information.

Running on device boot

In order to start SDK on device startup, set Appsalt.launchOnBoot to true. It can be used when you provide long-running service that should have SDK running alongside.

warning

Usually if you set Appsalt.launchOnBoot = true you should set Appsalt.isBackground = true as well. Check Running in background section for more information.

AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- Permissions for on boot functionality -->
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

    <application ...
    </application>
</manifest>

Kotlin
Java

App.kt
package com.example.app

import android.app.Application
import com.appsalt.Appsalt

class App : Application() {

    override fun onCreate() {
        super.onCreate()
        Appsalt.initialize(this, "your-api-key")
        // SDK configuration goes here
        Appsalt.launchOnBoot = true
        Appsalt.isBackground = true
        // ...
    }
}

App.java
package com.example.app;

import android.app.Application;
import com.appsalt.Appsalt;

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        Appsalt.initialize(this, "your-api-key");
        // SDK configuration goes here
        Appsalt.setLaunchOnBoot(true);
        Appsalt.setBackground(true);
        // ...
    }
}

If default SDK consent window doesn't suit your needs, you can create a custom consent window. Make sure to call Appsalt.optIn() whenever user gives a consent and Appsalt.optOut() whenever user declines it.

warning

Custom consent screen must be approved by our team to maintain clarity for end user.

Kotlin
Java

MainActivity.kt
package com.example.app

import android.app.Activity
import com.appsalt.Appsalt

class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...
        acceptButton.setOnClickListener(object : View.OnClickListener {
            override fun onClick(v: View?) {
                Appsalt.optIn()
                Appsalt.start()
            }
        })
        decline.setOnClickListener(object : View.OnClickListener {
            override fun onClick(v: View?) {
                Appsalt.optOut()
            }
        })
    }

    override fun onResume() {
        super.onResume()
        if (Appsalt.isOptedIn && !Appsalt.isRunning) {
            Appsalt.start()
        }
    }
}

MainActivity.java
package com.example.app;

import android.app.Activity;
import com.appsalt.Appsalt;

public class MainActivity extends Activity {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // ...
        acceptButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                Appsalt.optIn();
                Appsalt.start();
            }
        })
        decline.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                Appsalt.optOut();
            }
        })
    }

    @Override
    public void onResume() {
        super.onResume();
        if (Appsalt.isOptedIn() && !Appsalt.isRunning()) {
            Appsalt.start();
        }
    }
}

Logging

You can enable logging to logcat.

Kotlin
Java

App.kt
package com.example.app

import android.app.Application
import com.appsalt.Appsalt

class App : Application() {

    override fun onCreate() {
        super.onCreate()
        Appsalt.initialize(this, "your-api-key")
        // SDK configuration goes here
        Appsalt.enableLogging = true
    }
}

App.java
package com.example.app;

import android.app.Application;
import com.appsalt.Appsalt;

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        Appsalt.initialize(this, "your-api-key");
        // SDK configuration goes here
        Appsalt.setEnableLogging(true);
    }
}

Error monitoring

You can check what reason caused the error if SDK doesn't start. These errors are usually caused by Android system itself or vendor specific issues.

Subscribe to error events by setting Appsalt.onError: (Throwable) -> Unit. Also, Appsalt.lastError variable holds the last occurred error.

Kotlin
Java

App.kt
package com.example.app

import android.app.Application
import com.appsalt.Appsalt

class App : Application() {

    override fun onCreate() {
        super.onCreate()
        Appsalt.initialize(this, "your-api-key")
        // SDK configuration goes here
        // ...
        Appsalt.onError = { ex ->
            // handle the error
        }
        if (Appsalt.lastError != null) {
            // check if error is present
        }
    }
}

App.java
package com.example.app;

import android.app.Application;
import com.appsalt.Appsalt;

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        Appsalt.initialize(this, "your-api-key");
        // SDK configuration goes here
        // ...
        Appsalt.setOnError(t -> {
            // handle the error
            return null; // Value is ignored
        });
        if (Appsalt.getLastError() != null) {
            // check if error is present
        }
    }
}

SDK API

Full SDK API documentation

Kotlin
Java

package com.appsalt

import android.app.Notification
import android.content.Context

/**
 * First function to call for SDK. Prepares SDK for configuration and use.
 * Uses [context] and [apiKey] to prepare SDK for use.
 */
fun Appsalt.initialize(context: Context, apiKey: String)

/**
 * Sets whether to allow SDK to start itself on device boot or not.
 * Usually used together with [Appsalt.isBackground].
 */
var Appsalt.launchOnBoot: Boolean

/**
 * Sets whether to enable logcat logging
 */
 var enableLogging: Boolean

/**
 * Sets whether to allow SDK to run in background when app is no longer in focus.
 * In some cases used with [Appsalt.notification] and [Appsalt.notificationId] when there
 * is a need to use customized notification to represent your own brand.
 */
var Appsalt.isBackground: Boolean

/**
 * Sets Android notification to be used when SDK is allowed to run in background.
 */
var Appsalt.notification: Notification

/**
 * Sets Android notification id to be used when SDK is allowed to run in background.
 */
var Appsalt.notificationId: Int

/**
 * Checks whether SDK has been started.
 */
val Appsalt.isRunning: Boolean

/**
 * Checks whether user has given the consent to start SDK.
 */
val Appsalt.isOptedIn: Boolean

/**
 * Starts SDK if user has given the consent, otherwise does nothing.
 */
fun Appsalt.start()

/**
 * Stops SDK if it's running.
 */
fun Appsalt.stop()

/**
 * Withdraws user's consent and stops SDK if it was running.
 */
fun Appsalt.optOut()

/**
 * Informs SDK that user gave consent. Used with custom consent requests when
 * provided consent UI is insufficient. 
 * This does not start SDK, [Appsalt.start()] still needs to be called.
 */
fun Appsalt.optIn()

/**
 * Starts an activity displaying consent request with default settings.
 */
fun Appsalt.requestConsent()

/**
 * Starts an activity displaying consent request from user with configurable settings.
 *
 * [backgroundColor] integer representing overall activity color (argb: 0xFF000000).
 * [textColor] integer representing text color displayed on background (argb: 0xFF000000).
 * [linksColor] integer representing clickable text color displayed on background (argb: 0xFF000000).
 * [buttonTextColor] integer representing text color inside buttons (argb: 0xFF000000).
 * [buttonBackgroundResId] integer representing button background drawable ID.
 */
fun Appsalt.requestConsent(
    backgroundColor: Int,
    textColor: Int,
    linksColor: Int,
    buttonTextColor: Int,
    buttonBackgroundResId: Int,
)

/**
 * Last error which prevented SDK from running.
 * Allows to investigate vendor/device specific errors.
 */
val Appsalt.lastError: Throwable?

/**
 * Allows to set a listener to monitor exceptions that cause SDK to stop.
 */
var Appsalt.onError: (t: Throwable) -> Unit

package com.appsalt;

import android.app.Notification;
import android.content.Context;

public class Appsalt {
    /**
     * First function to call for SDK. Prepares SDK for configuration and use.
     * Uses [context] and [apiKey] to prepare SDK for use.
     */
    public static void initialize(Context context, String apiKey);

    /**
     * Sets whether to allow SDK to start itself on device boot or not.
     * Usually used together with [Appsalt.isBackground].
     */
    public static void setLaunchOnBoot(boolean value);

    /**
     * Sets whether to enable logcat logging
     */
     public static void setEnableLogging(boolean value);

    /**
     * Sets whether to allow SDK to run in background when app is no longer in focus.
     * In some cases used with [Appsalt.notification] and [Appsalt.notificationId] when there
     * is a need to use customized notification to represent your own brand.
     */
    public static void  setBackground(boolean value);

    /**
     * Sets Android notification to be used when SDK is allowed to run in background.
     */
    public static void setNotification(Notification notification);

    /**
     * Sets Android notification id to be used when SDK is allowed to run in background.
     */
    public static void setNotificationId(int id);

    /**
     * Checks whether SDK has been started.
     */
    public static boolean isRunning();

    /**
     * Checks whether user has given the consent to start SDK.
     */
    public static boolean isOptedIn();

    /**
     * Starts SDK if user has given the consent, otherwise does nothing.
     */
    public static void start();

    /**
     * Stops SDK if it's running.
     */
    public static void stop();

    /**
     * Withdraws user's consent and stops SDK if it was running.
     */
    public static void optOut();

    /**
     * Informs SDK that user gave consent. Used with custom consent requests when
     * provided consent UI is insufficient.
     * This does not start SDK, [Appsalt.start()] still needs to be called.
     */
    public static void optIn();

    /**
     * Starts an activity displaying consent request with default settings.
     */
    public static void requestConsent();

    /**
     * Starts an activity displaying consent request from user with configurable settings.
     *
     * [backgroundColor] integer representing overall activity color (argb: 0xFF000000).
     * [textColor] integer representing text color displayed on background (argb: 0xFF000000).
     * [linksColor] integer representing clickable text color displayed on background (argb: 0xFF000000).
     * [buttonTextColor] integer representing text color inside buttons (argb: 0xFF000000).
     * [buttonBackgroundResId] integer representing button background drawable ID.
     */
    public static void requestConsent(
        int backgroundColor,
        int textColor,
        int linksColor,
        int buttonTextColor,
        int buttonBackgroundResId
    );

    /**
     * Last error which prevented SDK from running.
     * Allows to investigate vendor/device specific errors.
     */
    public static Throwable getLastError()

    /**
     * Allows to set listener to monitor exceptions that cause SDK to stop.
     * Function's return value Unit is ignored, you may use null as return value
     * to avoid unnecessary kotlin.Unit dependency.
     */
    public static void setOnError(Function1<? super Throwable, Unit> listener);
}

Sample Project

To help you get started quicker, we’ve prepared a sample Android project that already includes the Appsalt SDK integration and basic setup. ➡️ Download Sample Project

Tips & Tricks

tip

You can get longer user sessions if you ask user to disable battery optimization on your application, since it will help SDK to run longer in the background.

Installation​

SDK setup​

Starting SDK​

Stopping SDK​

Withdraw the consent​

Running in background​

Running on device boot​

Custom consent window​

Logging​

Error monitoring​

SDK API​

Sample Project​

Tips & Tricks​

Installation

SDK setup

Starting SDK

Stopping SDK

Withdraw the consent

Running in background

Running on device boot

Custom consent window

Logging

Error monitoring

SDK API

Sample Project

Tips & Tricks