사용자 화면 추적

Hackle SDK는 기본적으로 브라우저의 URL 변경을 감지하여 자동으로 페이지뷰 정보를 수집합니다.
하지만 페이지별로 URL을 구분하지 않는 경우 자동 수집이 어려울 수 있습니다.

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

setCurrentPage

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

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

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

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

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

예시

React에서는 라우트 변경이 완료된 시점에 화면 추적을 하는 것을 추천합니다.

import { useEffect } from 'react'
import { useLocation } from 'react-router-dom'
import { useHackleClient } from '@hackler/react-sdk'

function usePageTracking() {
  const location = useLocation()
  const hackleClient = useHackleClient()
  useEffect(() => {
    hackleClient.setCurrentPage({
      pageName: "pageName"
    })
  }, [location, hackleClient])
}

'use client'

import { useEffect } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'

export function PageTracker() {
  const pathname = usePathname()
  const searchParams = useSearchParams()

  useEffect(() => {
    // 페이지 경로(pathname) 또는 쿼리 파라미터(searchParams)가 변경될 때마다 실행
    hackleClient.setCurrentPage({
      pageName: "pageName"
    })
  }, [pathname, searchParams])

  return null
}

import { useEffect } from 'react'
import { useRouter } from 'next/router'

export default function App({ Component, pageProps }) {
  const router = useRouter()

  useEffect(() => {
    // 페이지 변경 시 호출될 핸들러 함수
    const handleRouteChange = (url: string) => {
      hackleClient.setCurrentPage({
        pageName: "pageName"
      })
    }

    handleRouteChange(router.asPath)
    router.events.on('routeChangeComplete', handleRouteChange)

    return () => {
      router.events.off('routeChangeComplete', handleRouteChange)
    }
  }, [router])

  return <Component {...pageProps} />

속성 (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 config = {
  automaticRouteTracking: false
};

const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY", config);

ReactDOM.render(
  <HackleProvider hackleClient={hackleClient}>
    <YourApp />
  </HackleProvider>,
  document.getElementById('root')
);

Updated 3 days ago