SDK 초기화¶

이 문서에서는 Cocos Creator SDK의 기본 설정, 초기화 순서, 사용자 바인딩 및 수명 주기에 대해 설명합니다.

기본 설정¶

import { guanceSdk } from '@cloudcare/cocos-sdk/creator3';

guanceSdk.start({
  sdk: {
    datakitUrl: 'https://your-datakit.example.com',
    serviceName: 'cocos-game',
    env: 'prod',
    debug: true,
    globalContext: {
      game_channel: 'app-store',
    },
  },
});

다음 조건 중 하나를 충족해야 합니다. 그렇지 않으면 초기화 시 Configure datakitUrl or datawayUrl with clientToken 예외가 발생합니다.

• 비어 있지 않은 datakitUrl 구성
• 비어 있지 않은 datawayUrl과 clientToken 동시 구성

두 방식을 동시에 구성하면 Bridge는 datakitUrl을 우선 사용합니다. 환경 전환 시 모호함을 피하려면 한 가지 방식만 유지하는 것이 좋습니다.

SDK는 기본 전역 태그에 sdk_package_cocos를 자동으로 추가하며, 값은 현재 Cocos npm 패키지 버전입니다. 동일한 이름의 사용자 정의 태그를 사용하지 마세요.

전체 초기화 및 순서¶

guanceSdk.start()는 다음 순서로 초기화됩니다:

1. 기본 SDK
2. RUM
3. Log
4. Trace
5. 세션 리플레이(Replay 패키지를 결합하고 replay 구성을 전달한 경우)
6. Cocos 자동 수집

해당 구성 객체를 전달한 경우에만 해당 모듈이 초기화됩니다:

다음은 Replay가 포함된 독립적인 전체 예시입니다. 동일한 버전의 @cloudcare/cocos-session-replay를 먼저 설치하고 설치 프로그램 --replay를 실행해야 합니다. 자세한 내용은 애플리케이션 연동을 참조하세요. withSessionReplay()는 첫 번째 start() 또는 attach() 호출 이전에 호출해야 합니다. 기본 패키지만 사용하는 경우 위의 기본 구성을 따르며 replay를 전달하지 마세요.

import { guanceSdk as baseSdk } from '@cloudcare/cocos-sdk/creator3';
import { withSessionReplay } from '@cloudcare/cocos-session-replay/creator3';

export const guanceSdk = withSessionReplay(baseSdk);
guanceSdk.start({
  sdk: {
    datawayUrl: 'https://open.dataway.url',
    clientToken: 'client-token',
    serviceName: 'cocos-game',
    env: 'prod',
  },
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
  },
  logger: {
    enableCustomLog: true,
  },
  trace: {
    traceType: 'ddTrace',
  },
  replay: {
    captureFps: 1,
  },
  autoTrack: {
    scenes: true,
  },
});

첫 번째 수집 대상 씬이 로드되기 전에 초기화하고, 애플리케이션 수명 주기 동안 한 번만 호출해야 합니다. 초기화를 반복하면 Native SDK 또는 자동 리스너에 중복 상태가 발생할 수 있습니다.

사용자 정보 바인딩¶

사용자 ID만 전달할 수 있습니다:

guanceSdk.mobile.bindUser('user-123');

전체 사용자 정보를 전달할 수도 있습니다:

guanceSdk.mobile.bindUser({
  userId: 'user-123',
  userName: '玩家昵称',
  userEmail: 'player@example.com',
  extra: {
    membership: 'gold',
    region: 'cn-east',
  },
});

사용자가 로그아웃하면 바인딩을 해제합니다:

guanceSdk.mobile.unbindUser();

SDK 종료¶

guanceSdk.shutdown();

이 메서드는 다음 작업을 수행합니다:

• Cocos 자동 수집 리스너 제거
• 세션 리플레이의 주기적 프레임 캡처 중지
• Native SDK 종료

종료 후에는 수집 API를 계속 호출하지 마세요. 다시 활성화해야 한다면 애플리케이션을 재시작하고 초기화를 한 번 수행하는 것이 좋습니다.

현재 Cocos API는 캐시 수동 정리 또는 즉시 업로드 메서드를 노출하지 않습니다. 데이터 캐시와 전송 시점은 Native SDK가 관리합니다.

실행 플랫폼¶

브라우저 미리보기와 Web 빌드는 지원되지 않는 플랫폼입니다. TypeScript 호출은 Native Bridge로 전달되지 않으며 업로드 데이터도 생성되지 않습니다. 연동 검증은 Android 또는 iOS 네이티브 빌드를 사용해야 합니다.

관련 항목¶

• RUM 설정
• Log 설정
• Trace 설정
• Cocos Creator 세션 리플레이(실험적)
• 사용자 정의 태그 사용