# JavaScript

{% hint style="info" %}
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`.
{% endhint %}

{% hint style="success" %}
Framework Support

* You can use the JavaScript SDK with Angular, Vue, or other frameworks.
* If you are using React, refer to the [React](/en/development-guide/react.md) guide.
* If you are using Next.JS, refer to the [Next.js](/en/development-guide/nextjs-index.md) guide.
* For integration via Google Tag Manager, see the [GTM documentation](/en/development-guide/google-tag-manager.md).

If you need support for a specific environment or framework, please contact us via [Hackle Slack Community](https://join.slack.com/t/hackle-community/shared_invite/zt-1awrnygsh-U8VCHwN06ZDTF9yAzik5SA) or <support@hackle.io>.
{% endhint %}

## Add Dependency

[![](https://img.shields.io/npm/v/%40hackler%2Fjavascript-sdk)](https://www.npmjs.com/package/@hackler/javascript-sdk)

{% tabs %}
{% tab title="NPM" %}

```shell
npm install --save @hackler/javascript-sdk
```

{% endtab %}

{% tab title="YARN" %}

```shell
yarn add @hackler/javascript-sdk
```

{% endtab %}

{% tab title="HTML" %}

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

{% endtab %}
{% endtabs %}

## 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](https://dashboard.hackle.io/config/sdk-setting) on the Hackle Dashboard.

{% tabs %}
{% tab title="JavaScript" %}

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

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

{% endtab %}

{% tab title="HTML" %}

```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>
```

{% endtab %}
{% endtabs %}

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

{% hint style="warning" %}
If you call A/B Test or Feature Flag before initialization is complete, it returns the default group (A) or off (false).
{% endhint %}

```javascript
async function initHackle(){
  await hackleClient.onInitialized();
  // SDK ready to use
}

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

### SDK Initialization Config

You can initialize the SDK with configuration options.

```javascript
const config = {
  debug: true
};

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

#### Configuration Options

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

#### Session Policy Configuration

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

```javascript
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.

{% hint style="info" %}
You can freely update user information after SDK initialization using the user information setter functions.
{% endhint %}

{% hint style="warning" %}
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`.
{% endhint %}

```javascript
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.

{% hint style="warning" %}
This function can only be called once every 60 seconds.
{% endhint %}

```javascript
hackleClient.fetch();
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hackle.io/en/development-guide/javascript.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.