JavaScript

The JavaScript SDK supports IE11+ and all major browsers.

To use the JavaScript SDK, Promise and Map APIs must be supported. If polyfills are needed, we recommend using core-js.

Framework Support

• You can use the JavaScript SDK with Angular, Vue, or other frameworks.

• If you are using React, refer to the React guide.

• If you are using Next.JS, refer to the Next.js guide.

• For integration via Google Tag Manager, see the GTM documentation.

If you need support for a specific environment or framework, please contact us via Hackle Slack Community or [e-mail].

Add Dependency

NPM

npm install --save @hackler/javascript-sdk

YARN

yarn add @hackler/javascript-sdk

HTML

<!-- HTML의 경우 의존성 추가 작업이 필요하지 않습니다 -->

SDK Initialization

You must initialize HackleClient before using the SDK.

• HackleClient is the class that provides methods for using SDK features.

• You can find the SDK Key in SDK Integration Info on the Hackle Dashboard.

JavaScript

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

// YOUR_BROWSER_SDK_KEY로 초기화
const hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY");

HTML

<!-- 기존 코드 head 안에 추가 -->
<script src="https://cdn2.hackle.io/npm/@hackler/javascript-sdk@11.52.0/lib/index.browser.umd.min.js"></script>
<script>
  // YOUR_BROWSER_SDK_KEY로 초기화
  window.hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY");
</script>

Initialization Complete

Initialization runs asynchronously and fetches necessary data from the Hackle server and stores it in the SDK. You can use await to wait until initialization is complete.

If you call A/B Test or Feature Flag before initialization is complete, it returns the default group (A) or off (false), and the exposure event is not recorded, which may cause experiment data to be missing.

If you await onInitialized(), you can use the SDK after initialization is complete. Even if initialization fails due to a network error or similar issue, subsequent SDK calls safely return the default values.

async function initHackle(){
  try {
    await hackleClient.onInitialized();
    // SDK ready to use
  } catch (e) {
    // Even if initialization fails, subsequent SDK calls return the default values (A, false).
    console.warn("Hackle initialization failed:", e);
  }
}

initHackle();

// deprecated: onReady is deprecated because it does not support the Promise-based async/await pattern.
// Please use onInitialized() instead.
hackleClient.onReady(() => {
    // SDK ready to use
});

SDK Initialization Config

You can initialize the SDK with configuration options.

const config = {
  debug: true
};

const hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY", config);

Configuration Options

Option	Description	Default	Supported Version
debug	Prints logs for all features to the console.	false	1.0.0+
pollingIntervalMillis	Periodically updates the configuration set in the Dashboard. Minimum: 60000 (60 seconds)	-1 (no periodic update)	11.1.0+
exposureEventDedupIntervalMillis	Removes duplicate exposure events for the same A/B Test or Feature Flag distribution result triggered by the same user consecutively. Minimum: 1000 (1 second) Maximum: 3600000 (1 hour)	60000 (1 min / 11.23.0+) -1 (no dedup / below 11.23.0)	11.1.0+
devTool	Enables User Explorer.	undefined	11.13.0+
autoOpenDevTool	Option to automatically show the User Explorer button.	false	11.13.0+
sameSiteCookie	Sets the sameSite flag on Hackle cookies and determines cookie privacy policy.	Lax	11.20.0+
secureCookie	When set to true, sets the Secure flag on Hackle cookies.	false	11.20.0+
user	Injects a user at initialization time.	undefined	11.22.3+
sessionPolicy	Configures session persistence and expiration conditions.	ALWAYS_NEW_SESSION , 1800000	11.54.0+
optOutTracking	Whether opt-out is enabled.	false	11.54.0+
evaluationMode	Configures the evaluation mode.	local	12.0.0+
sessionTimeoutMillis (deprecated)	Sets the session expiration time. Please use sessionPolicy instead.	1800000 (30 min)	11.8.0+

Evaluation Mode Configuration

You can choose whether the SDK performs evaluation itself or fetches results that the Hackle server has already evaluated. If not configured, the default value "local" (local evaluation) is used.

const config = {
    evaluationMode: "remote"
};

const hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY", config);

When you use remote evaluation, user information is not stored in the browser. If user information was already stored while using local evaluation, it is deleted.

For the differences between the two modes and how to choose between them, refer to the Evaluation Mode documentation.

Session Policy Configuration

You can configure session persistence and expiration conditions using the session policy.

const config = {
    sessionPolicy: {
        timeoutMillis: 3600000,
        persistCondition: HackleSessionPersistConditions.NULL_TO_USER_ID
    }
};

const hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY", config);

Injecting User at Initialization

When user is set in config, you can initialize the SDK with user information included.

• If no user information is provided, the user information stored in cookies is used.

• If user information is provided, the user information stored in cookies is not used.

• If there is no user information in cookies, a user with the Hackle Device ID as the device id is used.

You can freely update user information after SDK initialization using the user information setter functions.

The user information injected at initialization and the user information stored in cookies are not merged.

e.g.) If userId: A is stored in cookies and you inject deviceId: B at initialization, the user is set to userId: null, deviceId: B.

const user = {
  userId: "LOGIN_ID",
  deviceId: "CUSTOM_DEVICE_ID"
};

const config = {
  user: user
};

const hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY", config);

Refreshing Dashboard Configuration

You can explicitly refresh the Dashboard configuration.

This function can only be called once every 60 seconds.

await hackleClient.fetch();