사용법

기본 초기화

import * as CPL from "@teamsparta/cross-platform-logger";

// 기본 사용법
CPL.initCPLog(
  process.env.FLOUNDER_KEY,
  process.env.AMPLITUDE_KEY,
  process.env.HACKLE_SDK_KEY,
  !JSON.parse(process.env.IS_PROD)
);

Braze 포함 초기화

// 웹 상에서 CRM이 발송되어야 하는 서비스에 Braze 추가
CPL.initCPLog(
  process.env.FLOUNDER_KEY,
  process.env.AMPLITUDE_KEY,
  process.env.HACKLE_SDK_KEY,
  process.env.BRAZE_API_KEY,
  process.env.BRAZE_SDK_ENDPOINT,
  !JSON.parse(process.env.IS_PROD)
);

Amplitude 옵션 설정

CPL.initCPLog(
  process.env.FLOUNDER_KEY,
  process.env.AMPLITUDE_KEY,
  process.env.HACKLE_SDK_KEY,
  process.env.BRAZE_API_KEY,
  process.env.BRAZE_SDK_ENDPOINT,
  !JSON.parse(process.env.IS_PROD),
  {
    autocapture: {
      attribution: {
        excludeReferrers: [
          'kauth.kakao.com',
          'spartacodingclub.kr',
          'online.spartacodingclub.kr',
          'logins.daum.net'
        ],
        resetSessionOnNewCampaign: true
      },
      pageViews: false
    }
  }
);

Amplitude Session Replay 설정

Session Replay를 사용하여 사용자의 웹 세션을 녹화할 수 있습니다. 특정 endpoint에서만 recording하도록 설정할 수 있습니다.

기본 Session Replay 설정

// Session Replay 설정
CPL.setAmplitudeSessionReplayConfig({
  sampleRate: 1, // 100%의 세션만 녹화
});

// Session Replay 시작
CPL.startAmplitudeSessionReplay();

특정 endpoint에서만 Session Replay

// 특정 경로에서만 recording하도록 설정
CPL.setAmplitudeSessionReplayConfig({
  recordingEndpoints: [
    '/checkout', // 정확한 경로 매치
    '/payment/*', // 와일드카드 패턴 매치
  ],
  sampleRate: 1, // 세션 녹화 비율
});

라우터 기반 자동 Session Replay 관리

CPL을 초기화한 후 한번만 session replay를 설정하면, 라우터 변경 시마다 자동으로 해당 페이지가 recording 대상인지 판단하여 session replay를 시작/중지합니다.

중요: 같은 경로에서는 중복 호출을 방지하므로 성능에 영향을 주지 않습니다.

// 1. CPL 초기화
CPL.initCPLog(flounder_key, amplitude_key, hackle_key);

// 2. Session Replay 설정 (한번만)
CPL.setAmplitudeSessionReplayConfig({
  recordingEndpoints: [
    '/checkout', 
    '/payment/*', 
    '/user/profile',
    '/checkout/success'
  ],
  sampleRate: 1 // 세션 녹화 비율
});

// 3. 라우터 변경 시마다 호출 (중복 호출 방지됨)
// React Router 예시
useEffect(() => {
  CPL.startAmplitudeSessionReplayForEndpoint(location.pathname);
}, [location.pathname]);

// Next.js Router 예시
useEffect(() => {
  CPL.startAmplitudeSessionReplayForEndpoint(router.asPath);
}, [router.asPath]);

// Vue Router 예시
watch(() => route.path, (newPath) => {
  CPL.startAmplitudeSessionReplayForEndpoint(newPath);
});

동작 방식:

• /checkout 페이지 접근 → session replay 시작
• /payment/credit-card 페이지 접근 → session replay 시작
• /home 페이지 접근 → session replay 중지
• /user/profile 페이지 접근 → session replay 시작
• 같은 페이지 재방문 → 중복 호출 방지 (성능 최적화)

Session Replay 상태 관리

// Session Replay 중지
CPL.stopAmplitudeSessionReplay();

로그 전송

CPL.sendCPLog(key, data, is_gtm = false);

Amplitude 사용자 속성 관리

Amplitude를 통해 사용자 속성을 다양한 방식으로 관리할 수 있습니다.

기본 사용자 속성 설정

// 여러 사용자 속성을 한 번에 설정
CPL.setAmplitudeUserProperties({
  user_type: 'active',
  birth_year: '1998',
  login_type: 'kakao',
});

// 단일 사용자 속성 설정
CPL.setAmplitudeUserProperty('user_type', 'active');
CPL.setAmplitudeUserProperty('last_seen', new Date());

배열 속성 관리

// 배열 속성에 값 추가
CPL.appendAmplitudeUserProperty('applied_bootcamps', 'KDT Unreal 기반 3D 게임 개발자 양성과정 3회차');
CPL.appendAmplitudeUserProperty('in_progress_bootcamps', '항해 플러스 백엔드 코스 8기');

// 배열 속성에서 값 제거
CPL.removeAmplitudeUserProperty('in_progress_bootcamps', '항해 플러스 백엔드 코스 8기');

속성 제거

// 특정 사용자 속성 제거
CPL.unsetAmplitudeUserProperty('used_coupons');

Braze 사용자 변경 자동 감지

Braze는 초기화 시 자동으로 user_id 쿠키를 모니터링합니다. 로그인 후 user_id 쿠키가 생성되면 자동으로 changeUser 메소드가 호출됩니다.

자동 기능:

• 로그인 감지: user_id 쿠키 생성 시 자동 changeUser 호출
• 로그아웃 감지: user_id 쿠키 삭제 시 자동 익명 사용자로 변경 (세션 유지)
• 중복 호출 방지: 같은 user_id에 대해서는 changeUser가 한 번만 호출
• In-App Message: 자동으로 표시되도록 설정
• 세션 관리: 자동으로 세션 시작 및 관리

// 쿠키 체크 간격 조정 (기본값: 300ms)
const brazeInstance = CPL.getBrazeInstance();
if (brazeInstance) {
  brazeInstance.setCookieCheckInterval(500); // 0.5초마다 체크
}

// 로그아웃 후 새로운 사용자로 로그인할 때 히스토리 초기화
CPL.resetBrazeChangeUserHistory();

// 웹 푸시 알림 권한 요청
const permissionGranted = await CPL.requestBrazeNotificationPermission();
if (permissionGranted) {
  console.log('푸시 알림 권한이 허용되었습니다.');
}

// Braze 인스턴스 정리
CPL.destroyBrazeInstance();

// Braze SDK 비활성화
CPL.disableSDK()

노션 문서

배포 방법

npm run deploy

Page Unload 시 데이터 잘 전송되었는지 확인하는 법:

• 네트워크 탭에 a6wkbhd6x8 친 다음
• PUT 요청 메서드에 status 200 확인