@teamsparta/cross-platform-logger/README.md

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

## 사용법

### 기본 초기화

```typescript
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 포함 초기화

```typescript
// 웹 상에서 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 옵션 설정

```typescript
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 설정

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

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

#### 특정 endpoint에서만 Session Replay

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

#### 라우터 기반 자동 Session Replay 관리

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

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

```typescript
// 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 상태 관리

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

### 로그 전송
```typescript
CPL.sendCPLog(key, data, is_gtm = false);
```

### Amplitude 사용자 속성 관리

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

#### 기본 사용자 속성 설정

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

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

#### 배열 속성 관리

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

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

#### 속성 제거

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

### Braze 사용자 변경 자동 감지

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

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

```typescript
// 쿠키 체크 간격 조정 (기본값: 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()
```
---
[노션 문서](https://www.notion.so/teamsparta/teamsparta-cross-platform-logger-da524a8f72d64c959fd95b350f332739?pvs=4)

---
## 배포 방법
```bash
npm run deploy
```

#### Page Unload 시 데이터 잘 전송되었는지 확인하는 법:
+ 네트워크 탭에 a6wkbhd6x8 친 다음
+ PUT 요청 메서드에 status 200 확인