SDK Integration
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:
- Add Dependencies
- Initialize the SDK
- User Configuration
- Event Tracking
- A/B Testing
- 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.
});
Key | Function | Default Value | Supported Version |
---|---|---|---|
exposureEventDedupIntervalMillis | Removes consecutive exposure events for the same A/B test, feature flag from the same user Min value: 1000 (1s) Max value: 3600000 (1h) | -1 (Do not deduplication) | 2.7.0+ |
pollingIntervalMillis | Allows periodic updates of information set in the dashboard. Minimum value: 60 (1 minute) | -1 (주기적으로 업데이트하지 않음) | 2.19.0+ |
Update Dashboard Configuration Information
You can explicitly update the dashboard configuration information.
hackleApp.fetch {
// done
}
hackleApp.fetch(new Runnable() {
@Override
public void run() {
// done
}
});
This feature is supported in Hackle Android SDK version 2.34.0 and above.
This function can be called in a limited manner once every 60 seconds.
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
}
Updated 8 months ago