콘텐츠로 이동

빠른 시작

이 문서는 Cocos Creator SDK를 가장 짧게 연동할 수 있는 경로를 제공하며, RUM, Log, Trace 데이터를 한 번에 검증 가능한 형태로 업로드하는 방법을 안내합니다.

연동 전에 설치한 npm 패키지와 네이티브 종속성이 SDK 버전 및 종속성 요구사항을 충족하는지 확인하세요.

사전 준비

  1. RUM에서 Android와 iOS 앱을 각각 생성하고 두 개의 앱 ID를 확보하세요.

  2. 업로드 방식을 하나 준비하세요.

    • 로컬 환경 배포: datakitUrl 준비.
    • 공용 DataWay: datawayUrl과 clientToken 준비.

  3. @cloudcare/cocos-sdk를 설치하고 프로젝트 설치 프로그램을 실행하세요. 자세한 내용은 앱 연동을 참고하세요.

  4. Cocos Creator를 다시 열고 Android 또는 iOS 네이티브 프로젝트를 생성하세요.
  5. CocoaPods를 사용하는 iOS 프로젝트는 Podfile이 있는 디렉터리에서 pod install을 실행한 후 .xcworkspace를 여세요. SPM을 사용하는 경우 iOS 네이티브 빌드에 따라 구성한 뒤 컴파일하면 되며, 새 프로젝트에 Pods를 설치할 필요는 없습니다.

아래 최소 예제는 기본 패키지만 사용합니다. 세션 리플레이가 필요하면 먼저 Replay 설치 파라미터에 따라 별도 패키지를 설치하고 --replay를 실행한 뒤, 결합된 SDK 인스턴스로 초기화하세요.

최소 초기화

다음 예제는 Creator 3을 사용합니다. Creator 2는 import 경로만 @cloudcare/cocos-sdk/creator2로 변경하면 됩니다.

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

export function startObservability(): void {
  guanceSdk.start({
    sdk: {
      datakitUrl: 'https://your-datakit.example.com',
      serviceName: 'cocos-game',
      env: 'prod',
      debug: true,
    },
    rum: {
      androidAppId: 'android-rum-app-id',
      iosAppId: 'ios-rum-app-id',
      sampleRate: 1,
    },
    logger: {
      enableCustomLog: true,
      enableLinkRumData: true,
      sampleRate: 1,
    },
    trace: {
      traceType: 'ddTrace',
      enableLinkRumData: true,
      sampleRate: 1,
    },
    autoTrack: {
      scenes: true,
      actions: true,
      errors: true,
      network: true,
    },
  });
}

컬렉션이 필요한 첫 번째 씬이 로드되기 전에 startObservability()를 호출하고, 앱 전체 수명 주기 동안 초기화가 한 번만 수행되도록 하세요.

앱의 주체가 Android/iOS 네이티브 페이지이고 Cocos를 사용하는 페이지가 하나 또는 소수인 경우 guanceSdk.start()를 다시 호출하지 마세요. 이 경우 네이티브 호스트가 SDK 초기화를 한 번 수행하고 Cocos는 attach()로 연동해야 합니다. 자세한 내용은 네이티브와 Cocos 혼합 개발을 참고하세요.

공용 DataWay를 사용한다면 sdk를 다음과 같이 변경하세요.

sdk: {
  datawayUrl: 'https://open.dataway.url',
  clientToken: 'client-token',
  serviceName: 'cocos-game',
  env: 'prod',
  debug: true,
},

datakitUrl과 datawayUrl은 둘 중 하나만 선택하며, datawayUrl을 사용할 때는 반드시 clientToken도 함께 전달해야 합니다.

커스텀 로그 출력

초기화 후 다음을 호출하세요.

guanceSdk.logger.log('Cocos SDK initialized', 'info', {
  scene: 'Boot',
});

연동 확인

  1. Android 또는 iOS 네이티브 빌드로 앱을 실행하세요. 브라우저 미리보기에서는 데이터가 업로드되지 않습니다.
  2. 씬을 전환하고 터치 조작을 한 번 수행한 뒤 네트워크 요청을 발생시키세요.
  3. Cocos 콘솔과 네이티브 로그에 초기화 또는 Bridge 오류가 있는지 확인하세요.
  4. RUM > 탐색기로 이동하여 해당 Android 또는 iOS 앱을 선택하세요.
  5. View, Action, Resource 데이터가 존재하는지 확인하고 로그 탐색기에서 커스텀 로그를 확인하세요.
  6. 검증이 끝나면 프로덕션 환경에서 debug를 끄세요.

다음 단계

문서 평가

이 페이지가 도움이 되었나요?