사용자 화면 추적

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

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

setCurrentPage

JavaScript SDK 11.53.0 이상 버전에서 지원하는 기능입니다.

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

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

파라미터	타입	필수	설명
`pageName`	`string`	필수	페이지명
`properties`	`object`	선택	페이지에 추가할 커스텀 속성

🚧
setCurrentPage 는 호출할 때마다 페이지 정보를 수집합니다.
동일한 pageName이 들어와도 $page_view와 $engagement 를 수집합니다.

예시

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

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

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

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

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

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

export default router

속성 (Property)

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

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

구분	타입	제약사항
속성 명(key)	`string`	글자수 제한은 128자입니다. (128 characters) 대소문자를 구분하지 않습니다. 예를 들어 amount와 AMOUNT는 같은 키로 인식합니다.
속성 값(value)	`boolean`, `string`, `number`, `array`	string 타입인 경우 글자수 제한은 1024자입니다. (1024 characters) number 타입인 경우 정수 최대 15자리, 소수점 최대 6자리를 지원합니다.

예시

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

automaticRouteTracking 비활성화

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

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

❗️
automaticRouteTracking이 활성화 된 상태에서 setCurrentPage를 통해 수동으로 화면 수집을 하는 경우,
$page_view와 $engagement가 과수집 되거나 의도하지 않은 속성으로 수집될 수 있습니다.
수동으로 화면 정보를 수집하는 경우 automaticRouteTracking 비활성화를 추천합니다.

예시

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

Updated 3 days ago