# 사용자 화면 추적

Hackle SDK는 기본적으로 브라우저의 URL 변경을 감지하여 자동으로 페이지뷰 정보를 수집합니다. 하지만 Single Page Application(SPA)이나 동적 페이지 구성 환경에서는 자동 수집이 어려울 수 있습니다.

이러한 경우 `setCurrentPage` 메소드를 직접 호출하여 페이지뷰를 수동으로 추적할 수 있습니다.

## setCurrentPage

{% hint style="info" %}
JavaScript SDK 11.53.0 이상 버전에서 지원하는 기능입니다.
{% endhint %}

`setCurrentPage` 메소드를 호출하여 현재 페이지 정보를 수동으로 설정할 수 있습니다.

* 화면 추적의 최소 단위 시간은 1초 입니다.
* 1초 이내에 변경된 페이지의 `$engagement` 는 측정되지 않습니다.

<table><thead><tr><th width="150">파라미터</th><th width="120">타입</th><th width="110">필수</th><th>설명</th></tr></thead><tbody><tr><td><code>pageName</code></td><td><code>string</code></td><td>필수</td><td>페이지명</td></tr><tr><td><code>properties</code></td><td><code>object</code></td><td>선택</td><td>페이지에 추가할 커스텀 속성</td></tr></tbody></table>

{% hint style="warning" %}
`setCurrentPage` 는 호출할 때마다 페이지 정보를 수집합니다.

동일한 pageName이 들어와도 `$page_view`와 `$engagement` 를 수집합니다.
{% endhint %}

#### 예시

이벤트 리스너를 활용해 이벤트가 발생할 때 화면 추적을 하는 것을 추천합니다.

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

```javascript
// 1. 페이지 로드 + 뒤로가기/앞으로가기 (bfcache 복원)
window.addEventListener('pageshow', (event) => {
  hackleClient.setCurrentPage({pageName: "page"})
)

// 2. 탭 복귀 / 최소화 복귀
document.addEventListener('visibilitychange', () => {
    if (document.visibilityState === 'visible') {
        hackleClient.setCurrentPage({pageName: "page"})
    }
})
```

{% endtab %}

{% tab title="Vue.js" %}

```javascript
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    // ... routes definitions
  ]
})

// 네비게이션이 완료된 후 호출되는 전역 가드
router.afterEach((to) => {
  hackleClient.setCurrentPage({
    pageName: "pageName"
  })
})

export default router
```

{% endtab %}
{% endtabs %}

### 속성 (Property)

핵클 SDK는 이벤트(Event) 객체에 속성을 추가할 수 있도록 지원합니다.

* 이벤트 객체에 추가 가능한 속성 개수는 최대 64개입니다.

<table><thead><tr><th width="150">구분</th><th width="120">타입</th><th>제약사항</th></tr></thead><tbody><tr><td>속성 명(key)</td><td><code>string</code></td><td>글자수 제한은 128자입니다. (128 characters)<br>대소문자를 구분하지 않습니다. 예를 들어 amount와 AMOUNT는 같은 키로 인식합니다.</td></tr><tr><td>속성 값(value)</td><td><code>boolean</code>, <code>string</code>, <code>number</code>, <code>array</code></td><td>string 타입인 경우 글자수 제한은 1024자입니다. (1024 characters)<br>number 타입인 경우 정수 최대 15자리, 소수점 최대 6자리를 지원합니다.</td></tr></tbody></table>

#### 예시

```javascript
hackleClient.setCurrentPage({
  pageName: "Product Detail",
  properties: {
    productId: "12345",
    category: "Electronics",
    price: 99000,
    inStock: true
  }
});
```

## automaticRouteTracking 비활성화

SDK에서는 기본적으로 `automaticRouteTracking`이 활성화되어 있습니다. 페이지 이동을 감지하여 자동 화면 정보 수집을 원하지 않는 경우 `automaticRouteTracking`를 비활성화 해야 합니다.

SDK를 초기화 할 때 `automaticRouteTracking`을 설정할 수 있습니다.

{% hint style="danger" %}
`automaticRouteTracking`이 활성화 된 상태에서 `setCurrentPage`를 통해 수동으로 화면 수집을 하는 경우, `$page_view`와 `$engagement`가 과수집 되거나 의도하지 않은 속성으로 수집될 수 있습니다.

**수동으로 화면 정보를 수집하는 경우 `automaticRouteTracking` 비활성화를 추천합니다.**
{% endhint %}

#### 예시

```javascript
const hackleClient = HackleClient.create("YOUR_SDK_KEY", {
  automaticRouteTracking: false
});
```


---

# 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/event-tracking/js-track-page.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.