Android

Hackle Android SDK supports Android API 24 and above (7.0 Nougat).

• Starting from Hackle Android SDK version 4.0.0, the minimum supported version has been changed to Android API 24.

• Starting from Hackle Android SDK version 3.0.0, the minimum supported version has been changed to Android API 21.

• The minimum supported version for Hackle Android SDK 2.x is Android API 16 and above.

Add Dependency

repositories {
  mavenCentral()
}

Add the dependency to your build.gradle file.

dependencies {
  implementation 'io.hackle:hackle-android-sdk:2.66.1'
}

ProGuard

If you use ProGuard, obfuscation rules are automatically included in the aar artifact. Otherwise, you must include the rules below.

-keep class io.hackle.android.** { *; }
-keep class io.hackle.sdk.** { *; }

Third-party Dependencies

The Hackle Android SDK has the following third-party dependencies.

Library	Description
com.squareup.okhttp3:okhttp:3.12.2	HTTP/HTTPS client
com.google.code.gson:gson:2.8.6	JSON serialization/deserialization
com.google.android.gms:play-services-base:17.3.0	Google Play Services common module

SDK Initialization

You must initialize HackleApp before using the SDK.

• An SDK Key is required to initialize HackleApp.

• HackleApp is the class that provides methods for using SDK features.

• You can find the SDK Key in SDK Integration Info on the Hackle Dashboard.

Initialization runs asynchronously, fetching the necessary information from the Hackle server and storing it in the SDK.

If you call A/B Test or Feature Flag methods before initialization is complete, they return the default group (A) or off (false).

Kotlin

import io.hackle.android.Hackle
import io.hackle.android.initialize

Hackle.initialize(applicationContext, YOUR_APP_SDK_KEY) {
  // SDK ready to use.
}

Java

import io.hackle.android.HackleApp;

HackleApp.initializeApp(getApplicationContext(), YOUR_APP_SDK_KEY);

Recommended Initialization Strategy: Initialize via Splash Screen

Display a splash screen instead of immediately launching the app, and initialize the SDK. After initialization, close the splash screen via callback so the user can begin interacting with the app.

Inject User on Initialization

You can initialize the SDK with user information included.

• If no user information is provided, the user information stored in local storage is used.

• If user information is provided, the user information stored in local storage is not used.

• If no user is injected and there is no user information in local storage, a user with the Hackle Device ID as the device ID is used.

User information can be freely updated after SDK initialization using the user configuration functions.

User information injected at initialization is not merged with user information stored in local storage.

ex) If userId: A is stored and you inject deviceId: B at initialization, the user is set to userId: null, deviceId: B.

Kotlin

import io.hackle.android.Hackle
import io.hackle.android.initialize
import io.hackle.sdk.common.User

val user = User.builder()
    .userId("142")                  // User ID
    .deviceId("ae2182e0")           // Device ID
    .build()

Hackle.initialize(applicationContext, YOUR_APP_SDK_KEY, user) {
  // SDK ready to use.
}

Java

import io.hackle.android.HackleApp;
import io.hackle.sdk.common.User

User user = User.builder()
    .userId("142")                  // User ID
    .deviceId("ae2182e0")           // Device ID
    .build()

HackleApp.initializeApp(getApplicationContext(), YOUR_APP_SDK_KEY, user, () -> {
  // SDK ready to use.
});

SDK Initialization Config

You can initialize the SDK with a configuration object.

Kotlin

import io.hackle.android.Hackle
import io.hackle.android.HackleConfig
import io.hackle.android.initialize

val config = HackleConfig.builder()
  .build()

Hackle.initialize(applicationContext, YOUR_APP_SDK_KEY, config) {
  // SDK ready to use.
}

Java

import io.hackle.android.HackleApp;
import io.hackle.android.HackleConfig;

HackleConfig config = HackleConfig.builder()
  .build();

HackleApp.initializeApp(getApplicationContext(), YOUR_APP_SDK_KEY, config, () -> {
  // SDK ready to use.
});

Configuration Options

Option	Description	Default	Min Version
exposureEventDedupIntervalMillis*	Removes duplicate exposure events for the same A/B Test or Feature Flag result triggered consecutively by the same user. Min: 1000 (1 second) Max: 86400000 (24 hours)	60000 (1 min)	2.7.0+
eventFlushIntervalMillis	The interval at which collected events are sent to the server. Min: 1000 (1 second) Max: 60000 (1 minute)	10000 (10 sec)	2.10.0+
pollingIntervalMillis	Periodically updates configuration set in the Dashboard. Min: 60000 (60 seconds)	-1 (no periodic update)	2.19.0+
automaticScreenTracking	Whether to enable automatic Screen Tracking	true	2.39.0+
automaticAppLifecycleTracking	Whether to enable automatic app start/stop tracking	true	2.64.0+
sessionPolicy	Configures session persistence and expiration conditions.	ALWAYS_NEW_SESSION , 1800000	2.65.0+
optOutTracking	Whether to enable Opt-out.	false	2.65.0+
evaluationMode	Sets the evaluation mode.	LOCAL	4.0.0+
sessionTimeoutMillis (deprecated)	Sets the session timeout duration. Use sessionPolicy instead.	1800000 (30 min)	2.13.0+

^* Supported even after app restart from version 2.47.0. ^* For versions below 2.47.0, the maximum value is: 3600000 (1 hour).

Evaluation Mode Configuration

You can choose whether the SDK performs evaluation directly or fetches results that the Hackle server has already evaluated. If not configured, the SDK uses the default value EvaluationMode.LOCAL (local evaluation).

Kotlin

import io.hackle.sdk.common.EvaluationMode

val config = HackleConfig.builder()
    .evaluationMode(EvaluationMode.REMOTE)
    .build()

Hackle.initialize(applicationContext, YOUR_APP_SDK_KEY, config) {
    // SDK ready to use.
}

Java

import io.hackle.sdk.common.EvaluationMode;

HackleConfig config = HackleConfig.builder()
    .evaluationMode(EvaluationMode.REMOTE)
    .build();

HackleApp.initializeApp(getApplicationContext(), YOUR_APP_SDK_KEY, config, () -> {
    // SDK ready to use.
});

When you use remote evaluation, user information is not stored on the device. Any user information already stored from local evaluation is deleted.

For the differences between the two modes and how to choose one, see the Evaluation Mode document.

Session Policy Configuration

You can configure session persistence and expiration conditions using the session policy.

Kotlin

val sessionPolicy = HackleSessionPolicy.builder()
    .persistCondition(HackleSessionPersistCondition.NULL_TO_USER_ID)
    .timeoutCondition(
        HackleSessionTimeoutCondition.builder()
            .millis(3600000)
            .onForeground(false)
            .onBackground(true)
            .onApplicationStateChange(true)
            .build()
    )
    .build()

val config = HackleConfig.builder()
    .sessionPolicy(sessionPolicy)
    .build()

Hackle.initialize(applicationContext, YOUR_APP_SDK_KEY, config) {
    // SDK ready to use.
}

Java

HackleSessionTimeoutCondition timeoutCondition = HackleSessionTimeoutCondition.builder()
    .millis(3600000)
    .onForeground(false)
    .onBackground(true)
    .onApplicationStateChange(true)
    .build();

HackleSessionPolicy sessionPolicy = HackleSessionPolicy.builder()
    .persistCondition(HackleSessionPersistCondition.NULL_TO_USER_ID)
    .timeoutCondition(timeoutCondition)
    .build();

HackleConfig config = HackleConfig.builder()
    .sessionPolicy(sessionPolicy)
    .build();

HackleApp.initializeApp(getApplicationContext(), YOUR_APP_SDK_KEY, config, () -> {
    // SDK ready to use.
});

Get Instance

After initialization, you can retrieve the HackleApp instance with the code below.

Kotlin

import io.hackle.android.Hackle
import io.hackle.android.app

val hackleApp = Hackle.app

Java

import io.hackle.android.HackleApp;

HackleApp hackleApp = HackleApp.getInstance();

Refresh Dashboard Configuration

After initialization, you can explicitly refresh Dashboard configuration when needed.

This function can only be called once every 60 seconds.

Kotlin

hackleApp.fetch {
  // done
}

Java

hackleApp.fetch(new Runnable() {
    @Override
    public void run() {
        // done
    }
});