This document provides steps for integrating your Android app with the Hackle Android SDK. SDK Integration is a must in order to use the functions provided by Hackle.

Follow these steps to quickly integrate the SDK:

1. Add Dependencies
2. Initialize the SDK
3. User Configuration
4. Event Tracking
5. A/B Testing
6. Feature Flags

Step 1: Add Dependencies

The SDK is distributed to mavenCentral.

repositories {
  mavenCentral()
}

Add SDK Dependencies

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

ProGuard / R8

If you are using ProGuard, R8, the obfuscation rules are automatically included in the aar artifact. If this is not the case, you should also include the rule below.

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

Step 2: Initialize the SDK

To use the SDK, you must initialize the HackleApp instance by providing the SDK key.

HackleApp is a class that provides methods for using the SDK's features.
You can find the SDK key in the SDK Integration section of the Hackle dashboard.

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

Hackle.initialize(applicationContext, YOUR_APP_SDK_KEY)

import io.hackle.android.HackleApp

HackleApp.initializeApp(getApplicationContext(), YOUR_APP_SDK_KEY);

Initialization Complete

During initialization, necessary information is retrieved from the Hackle server and stored in the SDK. This operation is performed asynchronously, and you can determine when the SDK is ready for use by providing a callback as the last parameter of the initialization method. If A/B testing or feature flag methods are called before initialization is complete, they will return the default group ("A") or the feature turned off (false).

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

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

import io.hackle.android.HackleApp

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

Recommended initialization method: initialize via loading screen

Instead of starting the app immediately, display a loading screen and initialize the SDK.
The callback then closes the loading screen and allows the user to start interacting with the app.

If you're using this method, it's a good idea to put a time limit on the loading screen.

Get the SDK Instance

After initialization, you can retrieve the HackleApp instance using the following code:

After initialization, you can obtain the HackleApp instance through the code below.

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

val hackleApp = Hackle.app

import io.hackle.android.HackleApp;

HackleApp hackleApp = HackleApp.getInstance();

Initialization Configuration

You can initialize the SDK with configuration options.

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

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

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

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

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

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

Third-party dependencies

Hackle Android SDK has the following third-party dependencies.

• com.squareup.okhttp3:okhttp:3.12.2
• com.google.code.gson:gson:2.8.6
• com.google.android.gms:play-services-base:17.3.0

3. User Configuration

You can configure user information in the SDK.

Setting User ID

If the user is logged in, you can set the ID of the logged-in user by calling setUserId.

• Set it only once when the user logs in.
• For users who are already logged in, you can call it at the point where you check the logged-in information.

val userId: String = ... //  ID of the logged-in user (membership number, member ID, etc.)
hackleApp.setUserId(userId)

String userId = ...// ID of the logged-in user (membership number, member ID, etc.)
hackleApp.setUserId(userId);

Setting User Properties

You can use information such as email address, location, age, and membership grade as user properties.

val operations = PropertyOperations.builder()
    .set("age", 42)
    .set("grade", "GOLD")
    .build()

hackleApp.updateUserProperties(operations)

PropertyOperations operations = PropertyOperations.builder()
    .set("age", 42)
    .set("grade", "GOLD")
    .build();

hackleApp.updateUserProperties(operations);

Resetting User Settings upon Logout

If the user logs out, you can reset the user information that has been set by calling resetUser. The following information will be reset:

• User ID
• User properties

hackleApp.resetUser()

hackleApp.resetUser();

4. Event Tracking

You can send user actions as events. The sent events are used for A/B test analysis, data analysis, and more. For example, if a user performs a purchase action, you can send the event as follows:

import io.hackle.sdk.common.Event  

// Sending an event
hackleApp.track("purchase")

// Sending an event with properties
val event = Event.builder("purchase")
    .property("amount", 4200)
    .property("pay_method", "CARD")
    .property("is_discount", false)
    .property("product_ids", listOf(42, 43))
    .build()
hackleApp.track(event)

import io.hackle.sdk.common.Event  

// Sending an event
hackleApp.track("purchase");

// Sending an event with properties
Event event = Event.builder("purchase")
    .property("amount", 4200)
    .property("pay_method", "CARD")
    .property("is_discount", false)
    .property("product_ids", Arrays.asList(42, 43))
    .build();
hackleApp.track(event);

Viewing Sent Events

You can view the sent events in the Event Management menu of the dashboard. Typically, it takes about 60 seconds for the events to appear on the dashboard after they are sent.

5. A/B Testing

You can distribute users into test groups and implement A/B tests based on the distributed results. By passing the experiment key to the variation method, you can receive the distribution result.

Experiment Key: A unique number assigned to each A/B test. It is automatically generated when an A/B test is created.

import io.hackle.sdk.common.Variation

// Determines the test group to expose to the user in an A/B test with experiment key 42.
val variation: Variation = hackleApp.variation(42)

// Logic for the assigned group
if (variation == Variation.A) {
  // Group A logic
} else if (variation == Variation.B) {
  // Group B logic
}

import io.hackle.sdk.common.Variation

// Determines the test group to expose to the user in an A/B test with experiment key 42.
Variation variation = hackleApp.variation(42);

// Logic for the assigned group
if (variation == Variation.A) {
    // Group A logic
} else if (variation == Variation.B) {
    // Group B logic
}

Viewing Distribution Results

You can view the distributed results on the Real-Time Status tab of the detailed page of the A/B test in the dashboard. Typically, it takes about 60 seconds for the distribution to appear on the dashboard after it is made.

6. Feature Flags

Feature flags have an on state and an off state. You can implement feature flags by writing different logic based on the state. By passing the feature flag key to isFeatureOn, you can receive the on/off status.

Feature Flag Key: A unique number assigned to each feature flag. It is automatically generated when a feature flag is created.

// Determines the user's status in a feature flag with feature key 42.
val featureOn = hackleApp.isFeatureOn(42)

// Logic for Assigned Group
if (featureOn) {
 // Logic for feature ON 
} else {
 // Logic for feature OFF
}

// Determines the user's status in a feature flag with feature key 42.
boolean featureOn = hackleApp.isFeatureOn(42);

// Logic for Assigned Group
if (featureOn) {
 // Logic for feature ON 
} else {
 // Logic for feature OFF
}