Analytics

미니앱의 화면 진입, UI 컴포넌트 노출, 사용자 클릭 이벤트를 기록하는 분석 네임스페이스입니다. Analytics 객체의 세 메서드(screen/impression/click)는 공통 LoggerParams를 받고, 별도의 eventLog 함수는 log_type 필드로 9가지 로그 유형을 지원합니다.

메서드

메서드	반환 타입	용도
Analytics.click	Promise<void> | undefined	버튼·링크 등 사용자 클릭 이벤트를 기록합니다.
Analytics.impression	Promise<void> | undefined	UI 컴포넌트가 화면에 노출되는 시점을 기록합니다.
Analytics.screen	Promise<void> | undefined	화면(페이지) 진입 이벤트를 기록합니다.
eventLog	Promise<void>	임의 키-값 페이로드와 9가지 log_type 중 하나로 일반 이벤트 로그를 기록합니다.

파라미터 공통 타입

Analytics.screen/impression/click은 모두 동일한 LoggerParams 타입을 받습니다. eventLog는 별도의 EventLogParams를 사용하니 페이지를 참조하세요.

import { Analytics } from '@apps-in-toss/web-framework';

type Primitive = string | number | boolean | null;

type LoggerParams = {
  log_name?: string;
} & {
  [key: string]: Primitive;
};

log_name은 이벤트를 구분하는 식별자입니다. 나머지 키는 자유롭게 추가할 수 있으며, Primitive(원시값) 타입만 허용됩니다.

권한

권한이 필요하지 않습니다. Analytics 네임스페이스의 모든 메서드는 별도의 PermissionName에 바인딩되지 않습니다 — 다른 네임스페이스에서 권한을 처리하는 방식은 Guides — 권한 처리 패턴을 참고하세요.

UX 가이드

• Analytics.screen은 페이지 마운트 시점에 호출하세요. useEffect(() => { Analytics.screen({ page: 'home' }); }, []) 패턴이 일반적입니다.
• Analytics.impression은 뷰포트 진입 시점에 호출하세요. IntersectionObserver나 라이브러리 훅으로 요소가 실제로 보일 때만 기록합니다. 마운트 즉시 호출하면 사용자가 보지 못한 컴포넌트도 집계됩니다.
• Analytics.click은 이벤트 핸들러에서 호출하세요. onClick 또는 onPress 내부에서 호출하면 실제 탭/클릭과 1:1 매칭됩니다.
• log_name을 일관되게 유지하세요. 이벤트명이 중간에 바뀌면 히스토리 연속성이 끊깁니다. 변경 시 데이터 파이프라인 측에 사전 공지를 권장합니다.
• 반환값이 undefined일 수 있습니다. 환경에 따라 Promise가 반환되지 않을 수 있으니 await만 하고 결과값에 의존하지 마세요.

직접 실행해 보기

sdk-example의 Analytics 페이지에서 메서드를 직접 실행해 볼 수 있습니다.

→sdk-example에서 실행해 보기

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. Analytics는 내부적으로 @apps-in-toss/web-analytics에서 re-export됩니다.