This document provides steps for integrating your browser with Hackle via the Hackle SDK for Javascript platforms. SDK Integration is a must in order to use the functions we provide.

Follow these steps to quickly integrate the SDK:

Add Dependencies
Initialize the SDK
User Configuration
Event Tracking
A/B Testing
Feature Flags

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.

npm install --save @hackler/javascript-sdk

yarn add @hackler/javascript-sdk

<!-- Add dependency action is not required for HTML -->

2. Initialize the SDK

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

HackleClient is a class that provides methods for using SDK functions.
Here you can pass the SDK key to the createInstance() method to instantiate it.

The SDK key can be found in the SDK integration in the dashboard of Hackle service. Copy and use the App or Browser SDK key.

import * as Hackle from "@hackler/javascript-sdk";

//Enter the SDK Key in the YOUR_BROWSER_SDK_KEY.
const hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY")

<!-- Add to existing head code -->
<script src="https://cdn.jsdelivr.net/npm/@hackler/[email protected]/lib/index.browser.umd.min.js"></script>
<script>
  // Place the SDK key in the YOU_BROWSER_SDK_KEY position//
  window.hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY");
</script>

Initialization Configuration

You can initialize the SDK with configuration options.

Debug Mode

You can activate the debug mode by setting the debug option to true. When the debug mode is enabled, logs for all features will be displayed in the console.

const config = {
  debug: true
};

// Initialize with configuration, including the debug option
const hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY", config);

All Configuration Options

Key	Description	Default Value	Supported Version
debug	Logs all features to the console.	false	1.0.0+
pollingIntervalMillis	Allows periodic updates of the information set in the dashboard. Minimum value: 30000 (30 seconds)	-1 (No periodic updates)	11.1.0+
exposureEventDedupIntervalMillis	Removes duplicate exposure events generated by the same user for consecutive A/B tests and feature flag distributions. Minimum value: 1000 (1 second) Maximum value: 3600000 (1 hour)	36000 (1 minute / 11.23.0+) -1 (No deduplication / below 11.23.0)	11.1.0+
auto_track_page_view	Automatically collects pageview events on page entry.	true	11.9.0+
devTool	Enables user exploration. Refer to the User Explorer documentation for more information.	undefined	11.13.0+
autoOpenDevTool	Option to automatically display the user exploration button.	false	11.13.0+
sameSiteCookie	Sets the SameSite flag on the hackle cookie. Decides cookie privacy policy.	Lax	11.20.0+
secureCookie	If true, the hackle cookie will be set with the Secure flag.	false	11.20.0+

Initialization Complete

Once the initialization process starts, the necessary information is retrieved from the Hackle server and stored in the SDK. This process is asynchronous, and you can determine when the SDK is ready to use by using the onReady callback. It is mainly used for functionalities (A/B testing, feature flags) that need to be executed after the initialization is complete.

hackleClient.onReady(() => {
  // SDK ready to use
});

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.

const userId = ... // ID of the logged-in user (e.g., member number, user ID)
hackleClient.setUserId(userId);

Setting User Properties

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

import { PropertyOperationsBuilder } from "@hackler/javascript-sdk"

const operations = new PropertyOperationsBuilder()
    .set("age", 42)
    .set("grade", "GOLD")
    .build();

hackleClient.updateUserProperties(operations);

<script>
  const operations = new Hackle.PropertyOperationsBuilder()
      .set("age", 42)
      .set("grade", "GOLD")
      .build();

  hackleClient.updateUserProperties(operations);
</script>

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

hackleClient.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:

// Collecting an event
hackleClient.track('purchase')

// Collecting an event with properties
const event = {
  key: "purchase",
  properties: {
    amount: 4200,
    pay_method: "CARD",
    is_discount: false,
    product_ids: [42, 43]
  }
}
hackleClient.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

You can distribute users into test groups and implement A/B testing by writing logic based on the assigned variations. By passing the experiment key to variation, you can receive the distribution result.

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

// It should be executed after the SDK is ready. Don't forget to wrap it with onReady.
hackleClient.onReady(function() {
  
  // 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.
  const variation = hackleClient.variation(42);

  // Logic for each assigned group
  if (variation === "A") {
    // Group A logic
  } else if (variation === "B") {
    // Group B logic
  }
});

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

Feature flags can 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 identifier for each feature flag. It is automatically assigned when creating a feature flag.

// It should be executed after the SDK is ready. Don't forget to wrap it with onReady.
hackleClient.onReady(function() {
  
  // Determines the user's status in a feature flag with key 42.
  // If unable to determine, it returns false (off state).
  const isOn = hackleClient.isFeatureOn(42);

  // Logic for each state
  if (isOn) {
    // On state logic
  } else {
    // Off state logic
  }
});