Android Honeygain 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 Honeygain 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 hgsdk.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/hgsdk.aar"))
    implementation("org.msgpack:msgpack-core:0.9.8")
    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
│   │   ├── hgsdk.aar
│   ├── src
│   │   ├── main
│   │   └── AndroidManifest.xml
│   └── build.gradle.kts
├── gradle.properties
├── gradlew
...

gradle.build
dependencies {
    implementation files('libs/hgsdk.aar')
    implementation 'org.msgpack:msgpack-core:0.9.8'
    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
│   │   ├── hgsdk.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 HgSdk.initialize(context) function and providing Android context. 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 HgSdk.launchOnBoot = true or HgSdk.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.honeygain.hgsdk.HgSdk

class App : Application() {

    override fun onCreate() {
        super.onCreate()
        HgSdk.initialize(this)
        // SDK configuration goes here
    }
}

App.java
package com.example.app;

import android.app.Application;
import com.honeygain.hgsdk.HgSdk;

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        HgSdk.initialize(this);
        // 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 HgSdk.requestConsent() method.

tip

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

After consent is provided, you can call HgSdk.start("your-api-key") and pass your api key as an argument. When consent screen closes you can check if consent was given in onResume() function using HgSdk.isOptedIn value.

Kotlin
Java

MainActivity.kt
package com.example.app

import android.app.Activity
import com.honeygain.hgsdk.HgSdk

class MainActivity : Activity() {

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

        if (HgSdk.isOptedIn) {
            HgSdk.start("your-api-key")
        } else {
            HgSdk.requestConsent()
        }
    }

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

MainActivity.java
package com.example.app;

import android.app.Activity;
import com.honeygain.hgsdk.HgSdk;

public class MainActivity extends Activity {

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

        if (HgSdk.isOptedIn()) {
            HgSdk.start("your-api-key");
        } else {
            HgSdk.requestConsent();
        }
    }

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

Stopping SDK

Call HgSdk.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 HgSdk.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 HgSdk.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.honeygain.hgsdk.HgSdk

class App : Application() {

    override fun onCreate() {
        super.onCreate()
        HgSdk.initialize(this)
        // SDK configuration goes here
        HgSdk.isBackground = true
        // (optional) Notification customization
        HgSdk.notification = yourNotification
        HgSdk.notificationId = yourNotificationId
        // ...
    }
}

App.java
package com.example.app;

import android.app.Application;
import com.honeygain.hgsdk.HgSdk;

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        HgSdk.initialize(this);
        // SDK configuration goes here
        HgSdk.setBackground(true);
        // (optional) Notification customization
        HgSdk.setNotification(yourNotification);
        HgSdk.setNotificationId(yourNotificationId);
        // ...
    }
}

info

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

Running on device boot

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

warning

Usually if you set HgSdk.launchOnBoot = true you should set HgSdk.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.honeygain.hgsdk.HgSdk

class App : Application() {

    override fun onCreate() {
        super.onCreate()
        HgSdk.initialize(this)
        // SDK configuration goes here
        HgSdk.launchOnBoot = true
        HgSdk.isBackground = true
        // ...
    }
}

App.java
package com.example.app;

import android.app.Application;
import com.honeygain.hgsdk.HgSdk;

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        HgSdk.initialize(this);
        // SDK configuration goes here
        HgSdk.setLaunchOnBoot(true);
        HgSdk.setBackground(true);
        // ...
    }
}

If default SDK consent window doesn't suit your needs, you can create a custom consent window. Make sure to call HgSdk.optIn() whenever user gives a consent and HgSdk.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.honeygain.hgsdk.HgSdk

class MainActivity : Activity() {

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

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

MainActivity.java
package com.example.app;

import android.app.Activity;
import com.honeygain.hgsdk.HgSdk;

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) {
                HgSdk.optIn();
                HgSdk.start();
            }
        })
        decline.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                HgSdk.optOut();
            }
        })
    }

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

Logging

You can enable logging to logcat.

Kotlin
Java

App.kt
package com.example.app

import android.app.Application
import com.honeygain.hgsdk.HgSdk

class App : Application() {

    override fun onCreate() {
        super.onCreate()
        HgSdk.initialize(this)
        // SDK configuration goes here
        HgSdk.enableLogging = true
    }
}

App.java
package com.example.app;

import android.app.Application;
import com.honeygain.hgsdk.HgSdk;

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        HgSdk.initialize(this);
        // SDK configuration goes here
        HgSdk.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 HgSdk.onError: (Throwable) -> Unit. Also, HgSdk.lastError variable holds the last occurred error.

Kotlin
Java

App.kt
package com.example.app

import android.app.Application
import com.honeygain.hgsdk.HgSdk

class App : Application() {

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

App.java
package com.example.app;

import android.app.Application;
import com.honeygain.hgsdk.HgSdk;

public class App extends Application {

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

SDK API

Full SDK API documentation

Kotlin
Java

package com.honeygain.hgsdk

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

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

/**
 * Sets whether to allow SDK to start itself on device boot or not.
 * Usually used together with [HgSdk.isBackground].
 */
var HgSdk.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 [HgSdk.notification] and [HgSdk.notificationId] when there
 * is a need to use customized notification to represent your own brand.
 */
var HgSdk.isBackground: Boolean

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

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

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

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

/**
 * Starts SDK if user has given the consent, otherwise does nothing.
 * Pass [apiKey] that you received via dashboard for your app.
 */
fun HgSdk.start(apiKey: String)

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

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

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

/**
 * Starts an activity displaying consent request with default settings.
 */
fun HgSdk.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 HgSdk.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 HgSdk.lastError: Throwable?

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

package com.honeygain.hgsdk;

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

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

    /**
     * Sets whether to allow SDK to start itself on device boot or not.
     * Usually used together with [HgSdk.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 [HgSdk.notification] and [HgSdk.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.
     * Pass [apiKey] that you received via dashboard for your app.
     */
    public static void start(String apiKey);

    /**
     * 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, [HgSdk.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 Honeygain 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