본문으로 건너뛰기

화면 진입 이벤트 수집 패턴

Analytics.screen은 log_type: 'screen'으로 미리 고정된 얇은 래퍼입니다. SPA 라우트 변경 시마다 "이 화면을 얼마나 방문했는지" 측정하는 페이지뷰 로깅에 씁니다.

최소 호출​

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

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

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

useEffect 의존성 배열에 파라미터를 포함하면, 같은 컴포넌트가 다른 productId로 재렌더되더라도 진입 이벤트가 정확히 발화됩니다.

재사용 가능한 useScreenView 훅​

화면마다 같은 useEffect 패턴을 반복 작성하지 않으려면, 훅 하나로 추상화합니다.

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

type Primitive = string | number | boolean | null;

interface ScreenViewParams {
  log_name: string;
  [key: string]: Primitive;
}

/**
 * 마운트 시 Analytics.screen을 fire-and-forget으로 호출합니다.
 * deps 배열 값이 바뀌면 재호출됩니다.
 */
function useScreenView(params: ScreenViewParams, deps: readonly unknown[] = []) {
  useEffect(() => {
    Analytics.screen(params);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, deps);
}

// 사용 예
function HomeScreen() {
  useScreenView({ log_name: 'home_screen' });
  return <main>홈</main>;
}

function ProductDetailScreen({ productId, category }: { productId: string; category: string }) {
  useScreenView(
    { log_name: 'product_detail_screen', product_id: productId, category },
    [productId, category],
  );
  return <main>상품 상세</main>;
}

deps를 명시하지 않으면 마운트 1회만 발화합니다. 라우트 파라미터가 바뀌어도 재진입을 추적해야 한다면 의존값을 두 번째 인자로 전달하세요.

log_name 일관성 유지​

화면 이름은 대시보드 리텐션 분석의 기본 키입니다. 상수 파일로 관리하면 이름 drift를 방지할 수 있습니다.

// analytics-events.ts
export const Screens = {
  HOME: 'home_screen',
  PRODUCT_DETAIL: 'product_detail_screen',
  CART: 'cart_screen',
} as const;

관련 API​