> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/development-guide/faq.md).

# 개발자 문서 FAQ

핵클 SDK를 연동하고 A/B 테스트를 구현할 때 자주 묻는 질문입니다.

#### 외부 솔루션으로 만든 홈페이지에도 SDK를 연동할 수 있나요?

코드를 수정할 수 있으면 SDK를 연동할 수 있습니다.

{% hint style="info" %}
대표적으로 카페 24 기반의 사이트는 SDK 연동을 할 수 있습니다.
{% endhint %}

{% hint style="danger" %}
네이버 스마트스토어는 코드 수정이 불가능해 SDK 연동을 할 수 없습니다.
{% endhint %}

***

#### 핵클 인스턴스는 언제 생성해야 하나요?

초기 구동 시 한 번 생성하세요. 싱글톤으로 구현되므로 다시 생성할 필요가 없습니다.

***

#### 테스트 시작 전에 연동을 검증할 수 있나요?

개발과 운영 환경 모두 테스트 기기 등록으로 연동을 검증할 수 있습니다.

테스트 기기 등록은 지정한 사용자 식별자를 특정 그룹에 강제 할당합니다. 수동할당이라고도 합니다.

[A/B 테스트 설정](/ab-test/management/ab-settings.md)에서 수동할당 설정을 확인하세요.

{% stepper %}
{% step %}
**테스트 기기를 등록하세요**

검증할 사용자의 식별자를 각 테스트 그룹에 등록합니다.
{% endstep %}

{% step %}
**테스트를 시작하고 동작을 확인하세요**

등록한 사용자가 의도한 그룹과 화면을 확인합니다. 운영 환경에서는 트래픽을 `0%`로 설정하세요.
{% endstep %}

{% step %}
**이벤트 전송을 확인하세요**

이벤트 상세 화면에서 실시간 전송 현황을 확인합니다.
{% endstep %}
{% endstepper %}

***

#### 모바일 앱의 사용자 식별자는 무엇으로 정하면 좋을까요?

서비스에서 관리하는 고유 사용자 ID 사용을 권장합니다.

핵클 식별자는 앱을 삭제한 뒤 다시 설치하면 새로 발급됩니다. 동일 사용자로 인식되지 않습니다.

{% hint style="warning" %}
핵클에서 제공하는 사용자 식별자를 사용하기 어려운 경우, 자체적으로 각 사용자를 구분할 수 있는 고유값을 만들어 해당 값을 사용자 식별자로 정하는 것이 좋습니다.
{% endhint %}

***

#### 비로그인 사용자의 식별자는 어떻게 정해야 하나요?

웹에서는 브라우저별 고유 쿠키를 사용할 수 있습니다. 앱에서는 설치 시 생성한 고유값을 사용할 수 있습니다.

서비스의 사용자 식별 정책에 맞는 값을 선택하세요.

***

#### 쿠키 기반 사용자 식별자를 만들 때 유의할 점이 있나요?

일반적으로 16자리 또는 32자리 식별자를 사용하세요.

또한 쿠키 도메인은 `.{회사명}.kr`과 같은 형태로 하는 것을 추천합니다.\
서브 도메인이 생기더라도 손쉽게 해당 값을 공유할 수 있으며, 클라이언트 및 서버 중 어느 곳에서 이벤트를 전송하더라도 같은 값을 공유하기 용이하기 때문입니다.

쿠키 기반 식별자 예시는 [사용자 식별자와 속성](/development-guide/sdk/user-identifier.md)에서 확인하세요.

***

#### 세션 단위로 측정하려면 사용자 식별자를 무엇으로 해야 하나요?

사용자 단위 식별자 사용을 권장합니다.

하지만 사용자 식별자를 Session ID로 정하면 세션 단위의 결과 분석 또한 가능합니다.\
이 경우 지표 계산의 기준을 잡기 위해 세션에 대한 기준, 세션 로직 등은 직접 정의해야 합니다.

***

#### 서버 분배 결과가 클라이언트에도 영향을 주면 어떻게 구현하나요?

서버에서 그룹별 값을 결정한 뒤, 클라이언트에는 처리할 값만 전달하세요.\
클라이언트에 그룹 값을 전달해 분기하면, 확정 후 서버와 클라이언트를 모두 수정해야 합니다.

그룹 A는 빨간색, 그룹 B는 파란색을 적용하는 예시입니다.

{% hint style="info" %}
`variation` 대신 처리할 값을 응답하면, 실험 확정 후 클라이언트 변경이 필요 없습니다.
{% endhint %}

{% columns %}
{% column %}
{% hint style="success" %}
Good Case

```
# 서버에서 그룹에 대한 값을 할당한 후 서버가 클라이언트 측으로 그 값을 내려준다
# 테스트그룹 A인 경우
HTTP/1.1 200 OK
{
  "color" : "red",
  ...
}
# 테스트그룹 B인 경우
HTTP/1.1 200 OK
{
  "color" : "blue",
  ...
}

# 클라이언트 측 처리
fill_color(response.color)
```

{% endhint %}
{% endcolumn %}

{% column %}
{% hint style="danger" %}
Bad Case

```
# 서버가 클라이언트 측으로 서버에서 할당된 그룹 값을 바로 내려 줌
HTTP/1.1 200 OK
{
  "variation" : "B"
  ...
}

# 클라이언트 측 처리
if response.variation == 'A'
  fill_color(red)
elif response.variation == 'B'
```

{% endhint %}
{% endcolumn %}
{% endcolumns %}

***

#### 클라이언트 기능 테스트마다 새 API를 만들어야 하나요?

기존 API가 있으면 해당 API에 그룹별 응답을 추가하세요. 

테스트 대상이 되는 값을 관리하는 API가 이미 존재한다면 해당 API에서 테스트 그룹 별 응답을 추가하는 것이 관리에 용이합니다.\
하지만 그런 API가 존재하지 않는 상황이라면 새로 API를 만들고 그 안에서 테스트 그룹을 분배한 다음에 그룹 별 응답을 내려주도록 하는 것이 좋습니다.

예를 들어 글자 수를 바꾸는 실험은 기존 글자 수 API에 그룹별 응답을 추가합니다. \
해당 API가 없다면 새 API에서 분배와 응답을 처리하세요.

***

#### 운영 환경에서 테스트 그룹 분배를 확인하려면 어떻게 하나요?

해당 A/B 테스트의 **실시간 노출 현황** 탭에서 그룹별 분배 상태를 확인하세요. [실시간 노출 현황](/ab-test/management/realtime-status.md)에서 상세 내용을 확인하세요.

***

#### 개발 환경에서 사용자 탐색 또는 강제 할당이 동작하지 않아요.

`vercel.app` 도메인에서 발생하는 Cookie 관리 문제일 수 있습니다. 커스텀 도메인 사용을 권장합니다.

{% hint style="warning" %}
핵클은 브라우저 Cookie로 사용자를 식별합니다.\
`vercel.app` 도메인에서는 SDK가 Cookie를 정상적으로 관리하지 못할 수 있습니다.
{% endhint %}

[Vercel 커스텀 도메인](https://vercel.com/guides/how-do-i-add-a-custom-domain-to-my-vercel-project)을 사용하세요.

***

#### SSG 페이지에서 React SDK로 A/B 테스트를 할 수 있나요?

SSG 방식에서는 어렵습니다. SSR로 전환하거나 클라이언트 사이드 컴포넌트를 사용하세요.

A/B 테스트는 사용자가 페이지에 진입할 때 분배를 결정합니다. 이후 해당 분배에 맞춰 콘텐츠를 동적으로 렌더링합니다.

{% hint style="info" %}
빌드 시 콘텐츠가 결정되는 SSG에서는 이 방식을 구현하기 어렵습니다. \
SSG를 유지해야 하면 클라이언트 사이드 컴포넌트에서 A/B 테스트를 구현하세요.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.hackle.io/development-guide/faq.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.