Analytics.screen

화면(페이지)에 진입하는 시점을 기록합니다. 어떤 페이지를 얼마나 방문했는지 측정하는 페이지뷰 로깅에 사용합니다. SPA 환경에서는 라우트 변경 시마다 호출하는 것이 일반적입니다.

시그니처

screen은 Analytics 네임스페이스 객체의 멤버로 노출됩니다. 함수 자체를 단독으로 import하지 않습니다.

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

type Primitive = string | number | boolean | null;

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

declare const Analytics: {
  screen: (params?: LoggerParams) => Promise<void> | undefined;
};

파라미터

이름	타입	필수	설명
params	LoggerParams	—	로깅할 키-값 쌍. log_name으로 이벤트를 식별하고, 나머지 키는 자유롭게 추가합니다. 생략 가능합니다.
params.log_name	string	—	이벤트 식별자. 분석 대시보드에서 이벤트를 구분하는 데 사용됩니다.
params[key]	string | number | boolean | null	—	추가 컨텍스트 필드. 원시값(Primitive)만 허용됩니다.

반환값

• Promise<void> | undefined — 로깅이 완료되면 resolve. 환경에 따라 undefined가 반환될 수 있으므로 반환값에 의존하지 마세요.

권한

권한이 필요하지 않습니다 — Analytics.screen은 별도의 PermissionName에 바인딩되지 않습니다. 권한이 필요한 다른 네임스페이스의 일반적인 처리 흐름은 Guides — 권한 처리 패턴을 참고하세요.

예제

최소 예제

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

function HomePage() {
  useEffect(() => {
    Analytics.screen({ page: 'home' });
  }, []);

  return <main>홈 화면</main>;
}

실전 예제 — 페이지 진입 시 추가 컨텍스트 함께 기록하기

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

function ProductDetailPage({ productId, category }: { productId: string; category: string }) {
  useEffect(() => {
    Analytics.screen({
      log_name: 'product_detail_screen',
      page: 'product_detail',
      product_id: productId,
      category,
    });
  }, [productId, category]);

  return <main>상품 상세</main>;
}

직접 실행해 보기

sdk-example의 Analytics 페이지에서 Analytics.screen 카드를 실행해 결과를 확인할 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• Analytics.click — 버튼·링크 등 사용자 클릭 이벤트를 기록합니다.
• Analytics.impression — UI 컴포넌트가 화면에 노출되는 시점을 기록합니다.

관련 가이드

• Recipes — 화면 진입 이벤트 수집 패턴

외부 참조

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