Skip to content

SDK Initialization

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

Basic Configuration

import { truewatchSdk } from '@truewatchtech/cocos-sdk/creator3';

truewatchSdk.start({
  sdk: {
    datakitUrl: 'https://your-datakit.example.com',
    serviceName: 'cocos-game',
    env: 'prod',
    debug: true,
    globalContext: {
      game_channel: 'app-store',
    },
  },
});
Field Type Required Description
datakitUrl string Conditionally required Local DataKit reporting endpoint. Provide either this or datawayUrl
datawayUrl string Conditionally required Public DataWay reporting endpoint. Must be configured together with clientToken
clientToken string Conditionally required DataWay authentication token
serviceName string No Service name to which the data belongs; it is recommended that Android and iOS use the same value
env string No Environment name. Common values are prod, gray, pre, common, and local; custom values are also supported
debug boolean No Whether to print Native SDK debug logs; it is recommended to disable this in production environments
globalContext Record<string, string> No Static global tags added to SDK data

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

  • Configure a non-empty datakitUrl;
  • Configure both a non-empty datawayUrl and clientToken.

If both methods are configured at the same time, 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

truewatchSdk.start() initializes in the following order:

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

A module is initialized only when the corresponding configuration object is passed.

The following is a standalone complete example that includes Replay. You need to first install the same version of @truewatchtech/cocos-session-replay and run the installer with --replay; see Application Access. You should call withSessionReplay() before the first start() or attach(). When using only the base package, follow the base configuration above and do not pass replay.

import { truewatchSdk as baseSdk } from '@truewatchtech/cocos-sdk/creator3';
import { withSessionReplay } from '@truewatchtech/cocos-session-replay/creator3';

export const truewatchSdk = withSessionReplay(baseSdk);
truewatchSdk.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 produce duplicate state in the Native SDK or automatic listeners.

User Binding

You can pass only the user ID:

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

You can also pass complete user information:

truewatchSdk.mobile.bindUser({
  userId: 'user-123',
  userName: '玩家昵称',
  userEmail: 'player@example.com',
  extra: {
    membership: 'gold',
    region: 'cn-east',
  },
});
Field Type Required Description
userId string Yes Unique user identifier; cannot be an empty string
userName string No User name
userEmail string No User email
extra Record<string, string> No Additional user tags

Unbind when the user logs out:

truewatchSdk.mobile.unbindUser();

SDK Shutdown

truewatchSdk.shutdown();

This method:

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

Do not continue calling collection APIs after shutdown. To re-enable the SDK, it is recommended to restart the application and complete initialization once.

The current Cocos API does not expose methods for manually clearing the cache or uploading immediately. The Native SDK manages data caching and when data is sent.

Platform Support

Browser preview and Web builds are unsupported platforms. TypeScript calls do not enter the Native Bridge and do not generate reporting data. Integration validation must use Android or iOS native builds.