Skip to content

Quick Start

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

The examples on this page use the current SDK version combination.

Prerequisites

  1. Create an Android and an iOS app in Real User Monitoring (RUM) respectively, and obtain the two App IDs.

  2. Prepare one data reporting method:

  3. Local environment deployment: prepare datakitUrl.

  4. Public DataWay: prepare datawayUrl and clientToken.

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

  6. Reopen Cocos Creator and generate the Android or iOS native project.
  7. For an iOS project using CocoaPods, enter the directory where the Podfile is located and run pod install, then open the .xcworkspace.When using SPM, configure as described in iOS Native Build and compile; there is no need to install Pods for a brand-new project.

The following minimal example uses only the base package. If Session Replay is needed, first install the standalone package with the Replay installation 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 data collection is loaded, and make sure it is initialized only once throughout the entire application lifecycle.

If the main body of the app is 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 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,
},

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

Call the following after initialization:

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 action, and make 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?