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. Session Replay(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 자동 수집 리스너를 제거합니다.
• Session Replay의 주기적 프레임 캡처를 중지합니다.
• Native SDK를 종료합니다.

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

현재 Cocos API는 캐시를 수동으로 정리하거나 즉시 업로드하는 메서드를 제공하지 않습니다. 데이터 캐시 및 전송 시점은 Native SDK가 관리합니다.

실행 플랫폼¶

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

관련 항목¶

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