@starlawfirm/tracking

v0.0.18

Published

3 months ago

- 스타법무법인 자사 홈페이지 트래킹 기능 패키지 - 사용중인 곳 : 리본회생, 다시

0High
0Medium
0Low

choiyeongung

kimminsu_2

imjiwon

스타법무법인 트래킹 기능 패키지(Tracking)

스타법무법인 자사 홈페이지 트래킹 기능 패키지
사용중인 곳 : 리본회생, 다시

📋 목차

설치

npm i @starlawfirm/tracking

사용법

1. TrackingProvider 파일 생성

import {
  daangn,
  kakao,
  meta,
  naver,
  googleAnalytics,
  googleTagManager,
  mixpanel,
  smartlog,
  googleAds,
} from "@starlawfirm/tracking";
import { useEffect } from "react";

export default function TrackingProvider() {
  useEffect(() => {
    // window 객체가 있는지 확인 (클라이언트 사이드에서만 실행)
    if (typeof window === "undefined") return;

    const initTracking = async () => {
      try {
        await Promise.all([
          googleAnalytics.init(process.env.NEXT_PUBLIC_DASI_GA_ID || ""),
          googleTagManager.init(process.env.NEXT_PUBLIC_DASI_GTM_ID || ""),
          googleAds.init(process.env.NEXT_PUBLIC_DASI_GAS_ID || ""),
          naver.init(process.env.NEXT_PUBLIC_DASI_NAVER_ID || ""),
          meta.init(process.env.NEXT_PUBLIC_DASI_META_ID || ""),
          daangn.init(process.env.NEXT_PUBLIC_DASI_DAANGN_ID || ""),
          kakao.init(process.env.NEXT_PUBLIC_DASI_KAKAO_ID || ""),
          mixpanel.init(process.env.NEXT_PUBLIC_DASI_MIXPANEL_ID || ""),
          smartlog.init(process.env.NEXT_PUBLIC_DASI_SMARTLOG_ID || ""),
          // tiktok.init(
          //   process.env.NEXT_PUBLIC_DASI_TIKTOK_ID || "CSI7R1RC77U221904TM0",
          // ),
        ]);

        console.log("모든 트래킹 스크립트 초기화 완료");
      } catch (error) {
        console.warn("트래킹 초기화 중 오류 발생:", error);
      }
    };
    initTracking();
  }, []);

  return null;
}

2. 최상위 파일에서 TrackingProvider import

import TrackingProvider from "@/components/providers/TrackingProvider";

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>
        <TrackingProvider />
        {children}
      </body>
    </html>
  );
}

3. 트래킹 전송 함수 (사용시)

configState는 전역 프로바이더임. 2025-07-29 기준 리본회생, 다시쪽에는 전부 다 있음.
sendSectionMixpanel은 click_button, section_view,

const { sendSectionMixpanel } = useMixpanel(configState);

sendSectionMixpanel({
  event: "content_interaction",
  section: "view_article_01",
  content_name: "article_like_click",
  article_num: contentId,
});

const { sendTracking, sendCounselTracking } = useAllTracking(configState);

const { request_date, request_time } = getRequestDateTime(anotherState);
const mixpanelData = makeMixpanelData(anotherState, request_date, request_time, "dasi") || {};

sendCounselTracking({
  eventKey: `signUp${state.locationTracking}`,
  mixpanel: mixpanelData,
});

sendTracking({
  eventKey: `signUpPopup${trackingLocation}`,
  mixpanel: {
    event: "consult_action",
    section: `view_meetbrand_${location}_${section}`,
  },
});

지원하는 트래킹 서비스

| 서비스 | 초기화 함수 | 이벤트 추적 | 특별 기능 | | ------------------ | ------------------------------ | --------------------------------------- | ----------------------- | | Google Analytics | googleAnalytics.init(gaId) | googleAnalytics.event(action, params) | 페이지뷰, 커스텀 이벤트 | | Google Tag Manager | googleTagManager.init(gtmId) | - | 태그 관리 | | Google Ads | googleAds.init(gasId) | googleAds.event(action, params) | 광고 전환 추적 | | Naver | naver.init(naverId) | naver.event(action, params) | 네이버 애널리틱스 | | Meta (Facebook) | meta.init(metaId) | meta.event(action, params) | 페이스북 픽셀 | | Daangn | daangn.init(daangnId) | daangn.event(action, params) | 당근마켓 픽셀 | | Kakao | kakao.init(kakaoId) | kakao.event(action, params) | 카카오 픽셀 | | Mixpanel | mixpanel.init(mixpanelId) | mixpanel.event(action, params) | 이벤트 분석 | | SmartLog | smartlog.init(smartlogId) | smartlog.track(category, tag) | 스마트로그 | | TikTok | tiktok.init(tiktokId) | tiktok.event(action, params) | 틱톡 픽셀 |

API 문서

공통 인터페이스

모든 트래킹 서비스는 다음 인터페이스를 따릅니다:

interface ProviderConfig {
  init: (pixelId?: string) => Promise<void>;
  isInitialized: () => boolean;
  event?: (action?: string, params?: any, code?: string) => void;
  track?: (category: string, tag: string) => Promise<void>;
}

이벤트 추적 예시

// Google Analytics 이벤트 추적
googleAnalytics.event("button_click", {
  event_category: "engagement",
  event_label: "signup_button",
});

// Naver 이벤트 추적
naver.event("purchase", {
  value: 10000,
  currency: "KRW",
});

// SmartLog 추적
smartlog.track("user_action", "signup_completed");

환경 변수 설정

프로젝트의 .env.local 파일에 다음 환경 변수들을 설정하세요:

# Google Analytics
NEXT_PUBLIC_DASI_GA_ID=G-XXXXXXXXXX

# Google Tag Manager
NEXT_PUBLIC_DASI_GTM_ID=GTM-XXXXXXX

# Google Ads
NEXT_PUBLIC_DASI_GAS_ID=AW-XXXXXXXXXX

# Naver Analytics
NEXT_PUBLIC_DASI_NAVER_ID=XXXXXXXXXX

# Meta (Facebook) Pixel
NEXT_PUBLIC_DASI_META_ID=XXXXXXXXXX

# Daangn Pixel
NEXT_PUBLIC_DASI_DAANGN_ID=XXXXXXXXXX

# Kakao Pixel
NEXT_PUBLIC_DASI_KAKAO_ID=XXXXXXXXXX

# Mixpanel
NEXT_PUBLIC_DASI_MIXPANEL_ID=XXXXXXXXXX

# SmartLog
NEXT_PUBLIC_DASI_SMARTLOG_ID=XXXXXXXXXX

# TikTok Pixel
NEXT_PUBLIC_DASI_TIKTOK_ID=XXXXXXXXXX

개발 가이드

프로젝트 구조

src/
├── hooks/          # 트래킹 전송 함수
├── init/           # 각 트래킹 서비스 초기화 모듈
├── types/          # TypeScript 타입 정의
├── utils/          # 유틸리티 함수
└── constants/      # 상수 정의

새로운 트래킹 서비스 추가하기

src/init/ 폴더에 새로운 서비스 파일 생성
ProviderConfig 인터페이스 구현
src/index.ts에서 export 추가
README 업데이트

적용 테스트

npm run build를 한 후, dist 파일을 복사한다.
사용하려고 하는 repo의 node_modules안에 해당 페키지의 dist 폴더와 교체한다.

참고사항 : 간단한 테스트를 위한 확인용임.

배포 방법

작업을 완료 한 후, pacakage.json 의 version을 올려준다.
npm publish 을 하여서 배포를 진행한다.

문제 해결

자주 발생하는 문제들

1. 트래킹이 초기화되지 않는 경우

환경 변수가 올바르게 설정되었는지 확인
브라우저 콘솔에서 에러 메시지 확인
클라이언트 사이드에서만 실행되는지 확인
dev 환경 조건 처리 확인

2. 이벤트가 전송되지 않는 경우

해당 서비스가 초기화되었는지 확인: service.isInitialized()
네트워크 탭에서 요청이 실제로 전송되는지 확인
광고 차단기나 개인정보 보호 확장 프로그램 비활성화

3. 개발 환경에서 테스트하기

브라우저의 개발자 도구에서 네트워크 탭 확인
각 서비스의 디버그 모드 활성화 (가능한 경우)

라이선스

GPL-3.0-or-later