# JavaScript

{% hint style="info" %}
JavaScript SDK는 IE11+ 및 모든 주요 브라우저를 지원합니다.

JavaScript SDK를 사용하기 위해서는 `Promise`, `Map` API가 필수로 지원되어야 합니다. 폴리필이 필요하다면 `core-js`를 이용하는 것을 추천합니다.
{% endhint %}

{% hint style="success" %}
프레임워크 지원

* Angular, Vue 또는 기타 프레임워크에서 JavaScript SDK를 사용할 수 있습니다.
* React를 사용중이라면 [React](https://docs.hackle.io/development-guide/react) 가이드를 참고해주세요.
* Next.JS를 사용중이라면 [Next.js](https://docs.hackle.io/development-guide/nextjs-index) 가이드를 참고해주세요.
* Google Tag Manager를 통한 연동 방법은 [GTM 문서](https://docs.hackle.io/development-guide/google-tag-manager)를 확인해주세요.

특정 환경 및 프레임워크에 대한 지원이 필요하시면 [핵클 슬랙 커뮤니티 ](https://join.slack.com/t/hackle-community/shared_invite/zt-1awrnygsh-U8VCHwN06ZDTF9yAzik5SA)또는 <support@hackle.io>로 문의해주세요.
{% endhint %}

## 의존성 추가

[![](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 초기화

SDK를 사용하기 위해서 반드시 HackleClient 를 초기화 해야 합니다.

* `HackleClient`는 SDK의 기능을 사용하기 위한 메소드들을 제공하는 클래스입니다.
* SDK 키는 핵클 서비스의 대시보드 안에 위치한 [SDK 연동 정보](https://dashboard.hackle.io/config/sdk-setting)에서 확인하실 수 있습니다.

{% 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 %}

### 초기화 완료

초기화는 **비동기로 실행**되며, 핵클 서버로부터 필요한 정보들을 가져와서 SDK에 저장합니다.\
await으로 초기화 완료 전까지 대기할 수 있습니다.

{% hint style="warning" %}
초기화가 완료 되기 전에 A/B 테스트, 기능 플래그를 호출하면 기본 그룹(A), 꺼짐(false)을 리턴합니다.
{% endhint %}

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

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

### 초기화 설정정보

설정정보를 포함하여 SDK를 초기화 할 수 있습니다.

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

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

#### 설정 옵션

<table data-full-width="false"><thead><tr><th width="213.57421875">설정</th><th width="295.48828125">기능</th><th width="125.8125">기본값</th><th width="108.09765625">지원 버전</th></tr></thead><tbody><tr><td><code>debug</code></td><td>모든 기능에 대한 로그를 콘솔에 출력합니다.</td><td><code>false</code></td><td>1.0.0+</td></tr><tr><td><code>pollingIntervalMillis</code></td><td><p>대시보드에서 설정한 정보를 주기적으로 업데이트 할 수 있습니다.</p><ul><li>최솟값 : 60000 (60초)</li></ul></td><td>-1<br>(주기적으로 업데이트하지 않음)</td><td>11.1.0+</td></tr><tr><td><code>exposureEventDedupIntervalMillis</code></td><td><p>동일한 사용자가 연속으로 발생시킨 동일한 A/B 테스트, 기능플래그 분배결과에 대한 노출 이벤트를 제거합니다.</p><ul><li>최솟값: 1000 (1초)</li><li>최댓값: 3600000 (1시간)</li></ul></td><td>60000 (1분 / 11.23.0 이상)<br>-1 (중복제거 하지 않음 / 11.23.0 미만)</td><td>11.1.0+</td></tr><tr><td><code>devTool</code></td><td><a href="javascript/js-user-explorer">사용자 탐색</a>을 사용할 수 있도록 합니다.</td><td><code>undefined</code></td><td>11.13.0+</td></tr><tr><td><code>autoOpenDevTool</code></td><td>사용자 탐색 버튼이 자동으로 나타나도록 하는 옵션입니다.</td><td><code>false</code></td><td>11.13.0+</td></tr><tr><td><code>sameSiteCookie</code></td><td>핵클 쿠키에 sameSite 플래그를 설정하고 쿠키 개인정보 보호 정책을 결정합니다.</td><td><code>Lax</code></td><td>11.20.0+</td></tr><tr><td><code>secureCookie</code></td><td><code>true</code>로 설정하시면 핵클 쿠키에 Secure 플래그를 설정합니다.</td><td><code>false</code></td><td>11.20.0+</td></tr><tr><td><code>user</code></td><td>초기화 시점에 사용자를 주입합니다.</td><td><code>undefined</code></td><td>11.22.3+</td></tr><tr><td><code>sessionPolicy</code></td><td>세션 유지 조건과 만료 조건을 설정합니다.</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>옵트아웃 활성화 여부.</td><td><code>false</code></td><td>11.54.0+</td></tr><tr><td><code>sessionTimeoutMillis</code><br>(deprecated)</td><td>세션만료 시간을 설정합니다. <code>sessionPolicy</code>를 사용해 주세요.</td><td>1800000 (30분)</td><td>11.8.0+</td></tr></tbody></table>

#### 세션 정책 설정

세션 정책을 설정하여 세션의 유지 조건과 만료 조건을 제어할 수 있습니다.

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

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

#### 초기화 시 사용자 주입

config에 user를 설정한 경우 유저 정보를 포함하여 SDK를 초기화 할 수 있습니다.

* 유저 정보를 포함하지 않으면 쿠키에 저장된 유저 정보를 사용합니다.
* 유저 정보를 포함하는 경우 쿠키에 저장된 유저 정보는 사용하지 않습니다.
* 쿠키에 저장된 유저 정보가 없는 경우 Hackle Device ID를 device id로 가지고 유저를 사용합니다.

{% hint style="info" %}
유저 정보는 SDK 초기화 이후에도 유저 정보 설정 함수를 통해 자유롭게 수정 할 수 있습니다.
{% endhint %}

{% hint style="warning" %}
초기화 시 주입한 유저 정보와 쿠키에 저장된 유저 정보는 병합하지 않습니다.

ex) 쿠키에 `userId: A` 가 저장된 상태에서 초기화 시 `deviceId: B` 를 주입하는 경우, `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);
```

### 대시보드 설정 정보 갱신

대시보드 설정 정보를 명시적으로 갱신 할 수 있습니다.

{% hint style="warning" %}
해당 함수는 60초에 한번 제한적으로 호출할 수 있습니다.
{% 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/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.