iOS

Hackle iOS SDK supports iOS 13 and above.

• Starting from Hackle iOS SDK 3.0.0, the minimum supported version has been changed to iOS 13.

• The minimum supported version for Hackle iOS SDK 2.x is iOS 10.

Add Dependency

Hackle iOS SDK supports Swift Package Manager and CocoaPods.

Swift Package Manager

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

CocoaPods

pod 'Hackle', '3.2.1'

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 in the Hackle Service Dashboard.

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

Do not call SDK features before initialization is complete.

Initialization runs asynchronously and is only complete once synchronization with the Hackle server has finished. If you call SDK features before initialization is complete, the SDK may not work correctly or events may be lost.

• A/B Tests, Feature Flags, and Remote Config do not work correctly. Instead of the actual assignment result, they return the default group (A), off (false), or the default value passed in the call. (Reason: SDK_NOT_READY)

• Exposure events are not recorded. Even if a user was actually part of the experiment, they are not counted as exposed, which can distort the experiment results.

• Events may be lost. Events collected with track() may not be sent.

• Events may carry an inaccurate session ID.

• In-App Messages are not displayed. Trigger conditions are evaluated at the moment an event is collected, and events collected before initialization is complete are not re-evaluated afterwards.

Make sure to call SDK features only after initialization is complete.

Swift

import Hackle

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

await Hackle.initialize(sdkKey: YOUR_APP_SDK_KEY)

Objective-C

@import Hackle;

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

Recommended Initialization Strategy: Initialize via Loading 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.

Swift

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

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

await Hackle.initialize(sdkKey: YOUR_APP_SDK_KEY, user: user)

Objective-C

HackleUserBuilder *builder = [HackleUser builder];
[builder userId:@"142"];                   // User ID
[builder deviceId:@"ae2182e0"];            // Device ID
HackleUser *user = [builder build];

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

SDK Initialization Config

You can initialize the SDK with a configuration object.

Swift

let config = HackleConfigBuilder()
  .build()

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

await Hackle.initialize(sdkKey: YOUR_APP_SDK_KEY, config: config)

Objective-C

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.
}];

Configuration Options

Option	Description	Default	Min Version
exposureEventDedupIntervalSeconds	Removes duplicate exposure events for the same A/B Test or Feature Flag result triggered consecutively by the same user. Min: 1 Max: 86400 (24 hours)	60 (1 min)	2.7.0+
eventFlushInterval	The interval at which collected events are sent to the server. Min: 1 Max: 60 (1 minute)	10	2.10.0+
pollingIntervalSeconds	Periodically updates configuration set in the Dashboard. Min: 60 (1 minute)	-1 (no periodic update)	2.18.0+
automaticScreenTracking	Whether to enable automatic Screen Tracking	true	2.34.0+
automaticAppLifecycleTracking	Whether to enable automatic app start/stop tracking	true	2.59.0+
sessionPolicy	Configures session persistence and expiration conditions.	ALWAYS_NEW_SESSION , 1800000	3.1.0+
optOutTracking	Whether to enable Opt-out.	false	3.1.0+
evaluationMode	Sets the evaluation mode.	local	4.0.0+
sessionTimeoutIntervalSeconds (deprecated)	Sets the session timeout duration. Use sessionPolicy instead.	1800 (30 min)	2.13.0+

^* Supported even after app restart from version 2.41.0. ^* For versions below 2.41.0, the maximum value is: 3600 (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 .local (local evaluation).

Swift

let config = HackleConfigBuilder()
    .evaluationMode(.remote)
    .build()

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

Objective-C

HackleConfigBuilder *configBuilder = [[HackleConfigBuilder alloc] init];
[configBuilder evaluationMode:EvaluationModeRemote];
HackleConfig *config = [configBuilder build];

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

Swift

let sessionPolicy = HackleSessionPolicy.builder()
    .persistCondition(.nullToUserId)
    .timeoutCondition(
        HackleSessionTimeoutCondition.builder()
            .timeoutIntervalSeconds(3600)
            .onForeground(false)
            .onBackground(true)
            .onApplicationStateChange(true)
            .build()
    )
    .build()

let config = HackleConfigBuilder()
    .sessionPolicy(sessionPolicy)
    .build()

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

Objective-C

HackleSessionTimeoutCondition *timeoutCondition = [[[[[[HackleSessionTimeoutCondition builder]
    timeoutIntervalSeconds:3600]
    onForeground:NO]
    onBackground:YES]
    onApplicationStateChange:YES]
    build];

HackleSessionPolicy *sessionPolicy = [[[[HackleSessionPolicy builder]
    persistCondition:[HackleSessionPersistCondition nullToUserId]]
    timeoutCondition:timeoutCondition]
    build];

HackleConfigBuilder *configBuilder = [[HackleConfigBuilder alloc] init];
[configBuilder sessionPolicy:sessionPolicy];
HackleConfig *config = [configBuilder build];

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

Get Instance

After initialization, you can retrieve the HackleApp instance with the code below. If called before initialization, it returns nil. You must call it after initialization.

Swift

let hackleApp = Hackle.app()

Objective-C

HackleApp *hackleApp = [Hackle app];

Refresh Dashboard Configuration

You can explicitly refresh the Dashboard configuration.

This function can only be called once every 60 seconds.

Swift

hackleApp.fetch {
  // done
}

await hackleApp.fetch()

Objective-C

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