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.

Step 1: Add Dependencies
Step 2: Initialize the SDK
Step3 : A/B test, Feature Flag
Step4 : Send customer event

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.

npm install --save @hackler/javascript-sdk

yarn add @hackler/javascript-sdk

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

📘
SDK update notice
If you are currently using @hackler/js-client-sdk, you must migrate from your existing @hackler/js-client-sdk to @hackler/javascript-sdk.

Step 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//
  var HACKLE_SDK_KEY = "YOUR_BROWSER_SDK_KEY";
  window.hackleClient = Hackle.createInstance(HACKLE_SDK_KEY);
</script>

Find SDK Key

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

📘
You can add settings to the createInstance() method.
For more information, see Step 2-1 below: Add Settings.

When HackleClient is instantiated, it gets the necessary information from the Hackle server and stores it in the SDK.
This operation is executed asynchronously and the onReady() method lets you know that the SDK is ready to use.

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

Step 2-1: Add Settings

When you initialize the SDK, you can add some settings. Please refer to the following example.

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

// Place the SDK key in the YOU_BROWSER_SDK_KEY position
// You can set debug, auto_track_page_view values.
const hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY", { debug: false, pollingIntervalMillis: 30000 })

<html>
  <head>
    <!-- Existing Code -->
    <!-- ExcistingCode End -->
    <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 -->
      HACKLE_SDK_KEY = "YOUR_BROWSER_SDK_KEY";
      HACKLE_SDK_CONFIG = { debug: false, pollingIntervalMillis: 30000 };
      window.hackleClient = Hackle.createInstance(HACKLE_SDK_KEY, HACKLE_SDK_CONFIG);
    </script>
  </head>
  <body>
  ...
  </body>
</html>

The settings have the following meanings.

key	function	default value	supported version
debug	You can view debug logs for all features from the console.	false	1.0.0+
pollingIntervalMillis	You can periodically update the information you set in the dashboard. Min value : 30000 (30s)	-1 (Do not update periodically)	11.1.0+
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)	11.1.0+
auto_track_page_view	Auto track $page_view event when a page is loaded.	true	11.9.0+

Step3. A/B test, Feature Flag

A/B test

Before running an A/B test, you must distribute users to the test group and create the logic corresponding to each test group.
User distribution can then be carried out through the hackle SDK.

📘
Test Group
The test group refers to the existing one (control group) and improvement one (treatment group) to be tested, and there may be more than one treatment group. You can configure in the dashboard and for information on how to manage test groups, visit see the document A/B setting.

variation

Input Experiment key and user identifier to the 'variation()' method to distribute users and receive results. You can implement logic by test group afterwards.

The experiment key is a unique number for each A/B test and can be found on the dashboard within the Hackle service.

The example code below inputs the experiment key 42.

// It must run after the SDK is ready. Don't forget to wrap it in onReady.
hackleClient.onReady(function() {
  
// Determine which test group to expose to the user in the A/B test with the test key of 42.
// Returns test group A if the test group can not be decided.
  const variation = hackleClient.variation(42);

  // Logic for Assigned Group
  if (variation === "A") {
    // Logic for Group A
  } else if (variation === "B") {
    // Logic for Group B
  }
});

Feature Flag

The feature flags are in the ON state and the OFF state. Different features will be set for each state.
When a user accesses a function with a feature flag applied, the user must be able to receive an on or off state. This status determination can be made via the hackle SDK.

isFeatureOn

Input Flag key to the 'isFeatureOn()' method to receive status results for the user. Implement logic based on subsequent states.

The Feature key is a unique number for each Feature Flag and can be found on the dashboard within the Hackle service.

The example code below input the function key 42.

// It must run after the SDK is ready. Don't forget to wrap it in onReady.
hackleClient.onReady(function() {
  
// Determine which status to expose to the user in the flag with the flag key of 42.
// Returns off statep if the state can not be decided.  
  const isOn = hackleClient.isFeatureOn(42);

  // logic for assigned state
  if (isOn) {
    // logic for ON
  } else {
    // logic for OFF 
  }
});

Check the exposure results

On the [Dashboard Left Menu Bar] - [A/B Test] or [Feature Flag] page, browse to the detail page for the list of exposed A/B tests or feature flags, and click the Real-Time Exposure tab in the middle of the page to view the distribution results from integrated SDK.

Step 4. Send User Events

The Hackle SDK provides the ability to send user events to the hackle.
At each point where changes in user behavior occur, this feature provides meaningful data about user behavior and allows you to analyze user behavior from those collected data.

track

User events can be sent by passing event keys and user identifiers to the 'track()' method. If necessary, when sending user events, numeric values can be put in 'value' to be sent together.

You can only put the number type for 'value'

Example

Suppose you have defined an event key called 'purchase' to collect events when the user presses the buy button. At this time, you may want to collect the purchase price together. In this case, you can also receive the purchase amount in 'value'.

/* Example 1: Send event key only */
<button onClick="purchase()">purchase</button>

function purchase() {
  // Existing Purchase Code
  
  hackleClient.onReady(() => {
    // Send User Events
    hackleClient.track("purchase");
  });
}

/* Example 2: Send event keys and numeric values together */
<button onClick="purchase_with_value()">purchase</button>

function purchase_with_value() {
  // Existing Purchase Code

  hackleClient.onReady(() => {
    // Put the numeric value to collect with the event key into the value
    const event = {
      key: "purchase",
      value: 13200
    }
    hackleClient.track(event);
  });
}

Example 1 only sends event keys; Example 2 shows a case of putting the purchase amount in 'value' to collect the purchase amount together.

Validate the sending of user events

Verify that user events sent by SDK are being collected successfully.
You can check the real-time event collection status by finding events sent to the SDK in the [left menu bar of dashboards] - [Event Management].

SDK Integration

Step 1: Add Dependencies

📘
SDK update notice

Step 2: Initialize the SDK

Find SDK Key

📘
You can add settings to the createInstance() method.

Step 2-1: Add Settings

Step3. A/B test, Feature Flag

A/B test

📘
Test Group

variation

Feature Flag

isFeatureOn

Check the exposure results

Step 4. Send User Events

track

Example

Validate the sending of user events

Step 1: Add Dependencies

📘SDK update notice

Step 2: Initialize the SDK

Find SDK Key

📘You can add settings to the createInstance() method.

Step 2-1: Add Settings

Step3. A/B test, Feature Flag

A/B test

📘Test Group

variation

Feature Flag

isFeatureOn

Check the exposure results

Step 4. Send User Events

track

Example

Validate the sending of user events

📘
SDK update notice

📘
You can add settings to the createInstance() method.

📘
Test Group