RUM Configuration¶

This document describes the Cocos Creator RUM initialization parameters, automatic collection scope, and Native monitoring configuration.

RUM Initialization¶

guanceSdk.start({
  ...,
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
    sampleRate: 1,
    sessionOnErrorSampleRate: 0,
    enableNativeCrash: true,
    enableNativeAnr: true,
    globalContext: {
      game_mode: 'ranked',
    },
  },
});

The Android runtime requires androidAppId, and the iOS runtime requires iosAppId. A single cross-platform TypeScript configuration can provide both values.

errorMonitorType and deviceMetricsMonitorType pass through numeric bitmasks directly and must remain consistent with the definitions of the current Native SDK version. For specific combinations, refer to Android RUM Configuration and iOS RUM Configuration.

Cocos Automatic Collection¶

Automatic collection is enabled through the autoTrack configuration of guanceSdk.start(). All options are disabled by default:

guanceSdk.start({
  ...,
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
  },
  logger: {
    enableCustomLog: true,
  },
  trace: {
    traceType: 'ddTrace',
  },
  autoTrack: {
    scenes: true,
    actions: true,
    errors: true,
    console: false,
    network: true,
  },
});

Calling guanceSdk.shutdown() restores the Console, Fetch, XHR, and scene/touch listeners.

Manual RUM Instrumentation¶

When automatic collection cannot cover scenarios such as custom pages, business operations, caught exceptions, and custom network stacks, you can report data manually through guanceSdk.rum. In standalone mode, initialize rum first in guanceSdk.start(); in native host Hybrid mode, the native side must initialize RUM first.

Attribute Types¶

The attributes parameter in the following methods is optional and supports JSON-serializable strings, numbers, booleans, null, arrays, and objects.

Action¶

Add an immediate Action:

guanceSdk.rum.addAction('Use Skill', 'click', {
  skill_id: 'fireball',
});

Start an Action whose associated lifecycle is managed by the Native SDK:

guanceSdk.rum.startAction('Matchmaking', 'custom', {
  queue: 'ranked',
});

Method signatures:

guanceSdk.rum.addAction(
  name: string,
  type?: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.startAction(
  name: string,
  type?: string,
  attributes?: FTAttributes,
): void

name and type cannot be empty; the default value of type is click.

When autoTrack.actions is enabled, global touch-end events automatically generate Actions. Do not call the manual Action API for the same touch.

View¶

Start a View:

guanceSdk.rum.startView('Battle', {
  map_id: 'map-001',
});

Stop the current View:

guanceSdk.rum.stopView({
  battle_result: 'victory',
});

Method signatures:

guanceSdk.rum.startView(name: string, attributes?: FTAttributes): void
guanceSdk.rum.stopView(attributes?: FTAttributes): void

name cannot be empty. The application should ensure Views are stopped in pairs; stop the previous View before starting a new one.

When autoTrack.scenes is enabled, the SDK automatically manages scene Views. Do not call the View API manually for the same scene, to avoid duplicate or nested errors.

Error¶

try {
  startBattle();
} catch (error) {
  const exception = error instanceof Error
    ? error
    : new Error(String(error));

  guanceSdk.rum.addError(
    exception.message,
    exception.stack || '',
    'game_logic_error',
    'run',
    {
      scene: 'Battle',
    },
  );
}

Method signatures:

guanceSdk.rum.addError(
  message: string,
  stack: string,
  type?: string,
  state?: 'run' | 'startup' | 'unknown',
  attributes?: FTAttributes,
): void

When autoTrack.errors is enabled, uncaught JavaScript Errors and Promise rejections are reported automatically. Exceptions caught and manually reported by business code are not captured again by the global listeners.

LongTask¶

guanceSdk.rum.addLongTask(
  'GenerateWorld',
  850 * 1_000_000,
  {
    map_size: 'large',
  },
);

Method signatures:

guanceSdk.rum.addLongTask(
  stack: string,
  durationNs: number,
  attributes?: FTAttributes,
): void

durationNs is in nanoseconds. The Cocos JavaScript layer does not currently recognize LongTasks automatically; the business code needs to call this method after a known time-consuming task ends.

Resource¶

A complete Resource consists of three phases:

1. startResource(): starts timing;
2. stopResource(): stops timing;
3. addResource(): adds request content and optional performance metrics.

export async function requestMatch(): Promise<void> {
  const key = `match-${Date.now()}`;
  const url = 'https://api.example.com/match';
  const started = Date.now() * 1_000_000;

  guanceSdk.rum.startResource(key, {
    request_source: 'matchmaking',
  });

  try {
    const traceHeaders = guanceSdk.trace.getHeaders(url, key);
    const response = await fetch(url, {
      headers: traceHeaders,
    });
    const ended = Date.now() * 1_000_000;

    guanceSdk.rum.stopResource(key);
    guanceSdk.rum.addResource(
      key,
      {
        url,
        httpMethod: 'GET',
        requestHeaders: traceHeaders,
        statusCode: response.status,
        responseContentType: response.headers.get('content-type') || undefined,
      },
      {
        fetchStartTime: started,
        responseStartTime: ended,
        responseEndTime: ended,
      },
    );
  } catch (error) {
    guanceSdk.rum.stopResource(key);
    const exception = error instanceof Error
      ? error
      : new Error(String(error));
    guanceSdk.rum.addError(
      exception.message,
      exception.stack || '',
      'network_error',
    );
  }
}

Method signatures:

guanceSdk.rum.startResource(
  key: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.stopResource(
  key: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.addResource(
  key: string,
  content: FTResourceContent,
  metrics?: FTResourceMetrics,
): void

Resource Content¶

Resource Performance Metrics¶

All time fields are in nanoseconds:

key must be identical in the three RUM methods and guanceSdk.trace.getHeaders().

Upload Behavior¶

The current Cocos API does not expose a manual Flush. After events are written to the Native SDK, they are sent by the Native SDK according to its cache and upload policies. Do not rely on guanceSdk.shutdown() to force upload before the application closes.

Cocos and Native Data Boundary¶

• scenes, actions, errors, and network collect behaviors at the Cocos JavaScript layer.
• The enableNative* options collect behaviors at the Android/iOS native container layer.
• Native Crash, ANR, UI Block, and device metrics are generated by the underlying Android/iOS SDK.
• Cocos Long Tasks are not currently collected automatically; call the manual API instead.
• Automatic network collection only covers the fetch and XMLHttpRequest actually provided by the current runtime.

When the native app uses Cocos on only some pages, complete initialization according to the native SDK requirements, and use enterCocos() and leaveCocos() to switch the View lifecycle while the Cocos page is visible. For the complete configuration, see Native and Cocos Hybrid Development.

Sampling Notes¶

sampleRate and sessionOnErrorSampleRate must be finite numbers within 0–1. When out of range, the TypeScript layer throws a RangeError during initialization. When not provided, the default values of the corresponding Native SDK are used.

Related Topics¶

• Cocos Creator Session Replay
• Application Data Collection
• Using Custom Tags
• Custom Collection Rules
• Native and Cocos Hybrid Development
• Troubleshooting