SDK Initialization¶

This document describes the basic configuration, initialization order, user binding, and lifecycle of the Cocos Creator SDK.

Basic Configuration¶

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',
    },
  },
});

One of the following conditions must be met; otherwise, initialization throws Configure datakitUrl or datawayUrl with clientToken:

• A non-empty datakitUrl is configured;
• Both a non-empty datawayUrl and clientToken are configured.

If both methods are configured, the Bridge prioritizes datakitUrl. It is recommended to keep only one method to avoid ambiguity when switching environments.

The SDK automatically adds sdk_package_cocos to the base global tags, with the current Cocos npm package version as its value. Do not use a custom tag with the same name.

Complete Initialization and Order¶

guanceSdk.start() initializes in the following order:

1. Base SDK;
2. RUM;
3. Log;
4. Trace;
5. Session Replay(when the Replay package has been combined and the replay configuration is provided);
6. Cocos automatic collection.

Each module is initialized only when the corresponding configuration object is provided:

The following is a complete standalone example that includes Replay. You need to install the same version of @cloudcare/cocos-session-replay and run the installer with --replay. See App Integration for details. Call withSessionReplay() before the first start() or attach(). When using only the base package, follow the basic configuration above and do not pass in 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,
  },
});

Initialize before the first collection scene loads, and ensure it is called only once during the application lifecycle. Repeated initialization may create duplicate states in the Native SDK or automatic listeners.

User Binding¶

You can pass only the user ID:

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

Or you can pass the full user information:

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

Unbind when the user logs out:

guanceSdk.mobile.unbindUser();

Shutting Down the SDK¶

guanceSdk.shutdown();

This method:

• Removes the Cocos automatic collection listeners;
• Stops Session Replay scheduled frame capture;
• Shuts down the Native SDK.

After shutdown, do not continue to call collection APIs. To re-enable it, restart the application and complete one initialization.

The current Cocos API does not expose methods for manually clearing the cache or uploading immediately. Data caching and sending timing are managed by the Native SDK.

Supported Platforms¶

Browser preview and Web builds are unsupported platforms. TypeScript calls do not enter the Native Bridge and do not generate report data. Integration verification must be performed using Android or iOS native builds.

Related Topics¶

• RUM Configuration
• Log Configuration
• Trace Configuration
• Cocos Creator Session Replay (Experimental)
• Custom Tags