SDK integration

This document provides steps for integrating your application with Hackle React Native SDK. SDK Integration is a must in order to use the functions we provide.

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

1. Add Dependencies

Think of this step as importing and installing our SDK into your codebase. To use our Hackle services add the following dependency code and import our SDK.

flutter pub add hackle
dependencies:
	hackle: ^2.7.0

πŸ“˜

Rebuild your app after Step 1

Flutter SDK includes Android and iOS SDKs.
The app that is being tested has to be newly built in order to complete the Step 1.

2. Initialize the SDK

Once you have imported the dependencies, in order to start using the Hackle SDK you must initialize the HackleApp. During this step, we get the information needed for SDK integration from the Hackle Server and store it in the SDK. You need to pass the SDK key to initialize HackleApp

  • HackleApp is a class that provides methods to use the functionalities of the SDK.
  • The SDK key can be found in the SDK integration in the dashboard of Hackle service.
import "package:hackle/hackle.dart";

await HackleApp.initialize(YOUT_APP_SDK_KEY);

Initialization Completed

When initialization starts, necessary information is fetched from the Hackle server and stored in the SDK. This process runs asynchronously, and you can determine when the SDK is ready for use by passing a callback as the last parameter during initialization. If you make A/B test or feature flag calls before initialization is completed, it will return the default group (A) and off (false) values.

Recommended Initialization Strategy: Initialization via Loading Screen

Instead of immediately starting the app, display a loading screen and initialize the SDK. Afterward, close the loading screen asynchronously and allow users to interact with the app.

When using this strategy, it's advisable to set a time limit for the loading screen.

Add Settings

You can add additional settings in SDK initialization

import "package:hackle/hackle.dart";

HackleConfig config = HackleConfigBuilder()
  .exposureEventDedupIntervalMillis(1000)
  .debug(true)
  .build();

await HackleApp.initialize(YOUT_APP_SDK_KEY, hackleConfig: config);
keyfunctiondefault valuesupported
version
exposureEventDedupIntervalMillisRemoves 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)
All
debugDebug logs for all functions can be viewed from the the console, and send events immediatelyfalse2.1.0+
pollingIntervalMillisYou can periodically update the information you set in the dashboard.

Min value : 60000 (60s)
-1
(Do not update periodically)
2.3.0+

3. User Configuration

You can configure user information in the SDK.

Setting User ID

If the user logs in, you can call setUserId to set the ID of the logged-in user.

  • You only need to set it once when the user logs in.
  • For users who are already logged in, you can call it when retrieving their login information.
String userId = ...// ID of the logged-in user (e.g., member number, user ID)
await HackleApp.setUserId(userId);

Setting User Properties

You can use user properties such as email address, location, age, and membership level. You can use the setUserProperty and setUserProperties methods to set user properties.

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

await HackleApp.updateUserProperties(operations);

Resetting User Configuration on Logout

If the user logs out, you can call resetUser to reset the previously set user information. The following information will be reset:

  • User ID
  • User properties
await HackleApp.resetUser();

4. Event Tracking

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

import "package:hackle/hackle.dart";

// Collecting an event
HackleApp.track(HackleEvent.builder("purchase").build());

// Collecting an event with properties
HackleEvent event = HackleEvent.builder("purchase")
  .property("amound", 4200)
  .property("pay_method", "CARD")
  .property("is_discount", false)
  .build();
HackleApp.track(event);

Viewing Sent Events

You can view the sent events in the Event Management menu on the dashboard. It typically takes around 60 seconds for the events to appear on the dashboard after being sent.

5. A/B Testing

To implement A/B testing, you can distribute users into test groups and write logic based on the assigned group. You can achieve this by passing the experiment key to variation.

Experiment Key: A unique identifier for each A/B test. It is automatically assigned when creating an A/B test.

import "package:hackle/hackle.dart";

  // Determines the test group to be exposed to the user in an A/B test with variation key 42.
  // If unable to determine, it returns test group A.
Variation variation = await HackleApp.variation(42);

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

Viewing Distribution Results

You can check the distribution results in the Real-Time Status tab on the A/B test's details page. It typically takes around 60 seconds for the distribution results to appear on the dashboard after being distributed.

6. Feature Flags

To implement feature flags where you can write different logic based on the on/off state, you can use the is FeatureOn. By passing the feature flag key, you can retrieve the on/off status.

Feature Flag Key: A unique identifier for each feature flag. It is automatically assigned when creating a feature flag.

import "package:hackle/hackle.dart";

  // Determines the user's status in a feature flag with key 42.
  // If unable to determine, it returns false (off state).
bool featureOn = await HackleApp.isFeatureOn(42);

if (featureOn) {
// On state logic
} else {
// Off state logic
}