Skip to content

Quick Start

This article provides the shortest integration path for the Cocos Creator SDK, helping you complete verifiable reporting of RUM, Log, and Trace data.

Before integration, confirm that the installed npm package and native dependencies meet the SDK Version and Dependency Requirements.

Prerequisites

  1. In Real User Monitoring (RUM), create an Android app and an iOS app separately, and obtain the two App IDs.

  2. Prepare a reporting method:

    • Local environment deployment: prepare datakitUrl.
    • Public DataWay: prepare datawayUrl and clientToken.

  3. Install @cloudcare/cocos-sdk and run the project installer. For detailed steps, see App Access.

  4. Reopen Cocos Creator and generate an Android or iOS native project.
  5. For iOS projects using CocoaPods, go to the directory containing the Podfile and run pod install, then open the .xcworkspace. When using SPM, configure it as described in iOS Native Build and compile; there is no need to install Pods for a new project.

The following minimal example uses only the base package. If you need Session Replay, first install the standalone package according to Replay Install Options and run --replay, then initialize with the combined SDK instance.

Minimal Initialization

The following example uses Creator 3. For Creator 2, simply change the import entry to @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,
    },
  });
}

Call startObservability() before the first scene that requires collection loads, and ensure that it is initialized only once during the entire app lifecycle.

If the app mainly consists of Android/iOS native pages and only one or a few pages use Cocos, do not call guanceSdk.start() again. In this scenario, the native host should complete the SDK initialization once, and Cocos should integrate through attach(). For details, see Native and Cocos Hybrid Development.

If you use the public DataWay, change sdk to:

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

Use either datakitUrl or datawayUrl; when using datawayUrl, you must also pass clientToken.

After initialization, call:

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

Verify Integration

  1. Run the app with an Android or iOS native build; browser preview does not report data.
  2. Switch scenes, trigger a touch operation, and initiate a network request.
  3. Check the Cocos console and native logs for initialization or Bridge errors.
  4. Go to RUM > Explorer and select the corresponding Android or iOS app.
  5. Confirm that View, Action, or Resource data exists, and confirm the custom log in the Log Explorer.
  6. After verification, disable debug in the production environment.

Next Steps

Feedback

Is this page helpful?