This document provides steps for integrating your iOS app with Hackle via the Hackle SDK.

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

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

CocoaPods

pod 'Hackle', '~> 2.27.0'

Swift Package Manager

// ...
dependencies: [
    .package(url: "https://github.com/hackle-io/hackle-ios-sdk.git", 
                          .upToNextMinor("2.27.0"))
],
targets: [
    .target(
        name: "YOUR_TARGET",
        dependencies: ["Hackle"]
    )
],
// ...

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 Hackle

Hackle.initialize(sdkKey: YOUR_APP_SDK_KEY)

@import Hackle;

[Hackle initializeWithSdkKey:@"YOUR_APP_SDK_KEY" config:[HackleConfig DEFAULT]];

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).

Hackle.initialize(sdkKey: YOUR_APP_SDK_KEY) {
    // SDK ready to use.
}

[Hackle initializeWithSdkKey:@"YOUR_APP_SDK_KEY" config:[HackleConfig DEFAULT] completion:^{
    // 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:

let hackleApp = Hackle.app()

HackleApp *hackleApp = [Hackle app];

Initialization Configuration

You can initialize the SDK with configuration options.

let config = HackleConfigBuilder()
  .exposureEventDedupIntervalSeconds(60)
  .build()

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

HackleConfigBuilder *builder = [[HackleConfigBuilder alloc] init];
[builder exposureEventDedupIntervalSeconds:1];
HackleConfig *config = [builder build];

[Hackle initializeWithSdkKey:@"YOUR_APP_SDK_KEY" config:config completion:^{
    // SDK ready to use.
}];

All Configuration Options

Update Dashboard Configuration Information

You can explicitly update the dashboard configuration information.

hackleApp.fetch { 
  // done
}

[hackleApp fetch:^{
    // done
}];

📘

This feature is supported in Hackle iOS SDK version 2.29.0 and above.

🚧

This function can be called in a limited manner, once every 60 seconds.

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.

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

NSString *userId = ... // ID of the logged-in user (membership number, member ID, etc.)
[hackleApp setUserIdWithUserId:userId];

Setting User Properties

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

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

hackleApp.updateUserProperties(operations: operations)

PropertyOperationsBuilder *builder = [PropertyOperations builder];
[builder set:@"age" :@42];
[builder set:@"grade" :@"GOLD"];
PropertyOperations *operations = [builder build];

[hackleApp updateUserPropertiesWithOperations: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 Hackle

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

// Sending an event with properties
let event = Event.builder("purchase")
    .property("amount", 4200)
    .property("pay_method", "CARD")
    .property("is_discount", false)
    .build()

hackleApp.track(event: event)

@import Hackle;

// Sending an event
[hackleApp trackWithEventKey:@"purchase"];

// Sending an event with properties
HackleEventBuilder *builder = [Event builder:@"purchase"];
[builder property:@"amount" :@4200];
[builder property:@"pay_method" :@"CARD"];
[builder property:@"is_discount" :@false];
Event *event = [builder build];

[hackleApp trackWithEvent: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.

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

// Logic for the assigned group
if variation == "A" {
  // Group A logic
} else if variation == "B" {
  // Group B logic
}

// Determines the test group to expose to the user in an A/B test with experiment key 42.
NSString *variation = [hackleApp variationWithExperimentKey:42 defaultVariation:@"A"];

// Logic for the assigned group
if([variation isEqual:@"A"]) {
    // Group A logic
} else if ([variation isEqual:@"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.
let isFeatureOn: Bool = hackleApp.isFeatureOn(featureKey: 42)

if isFeatureOn {
    // ON feature
} else {
    // OFF feature
}

// Determines the user's status in a feature flag with feature key 42.
bool isFeatureOn = [hackleApp isFeatureOnFeatureKey:@42];

if (isFeatureOn) {
    // ON feature      
} else {
    // OFF feature
}