Skip to main content

Engine configuration

The Chat SDK engine provides the following configuration options. All configurations must be set before initialization.

Data center configuration​

By default, the SDK connects to the Singapore data center. If your app uses a different data center, configure the Chat SDK to connect to the correct server address before initialization.

Set the navigation server address for private deployments. naviServer must be a valid server address. No configuration is needed by default — contact your sales representative if required.

Dart
await NCEngine.initialize(InitParams(
  appKey: '<your-app-key>',
  naviServer: 'your-navigation-server-address',
));

Media server​

Set the media server address for private deployments (the upload address for files and images). No configuration is needed by default — contact your sales representative if required.

Dart
await NCEngine.initialize(InitParams(
  appKey: '<your-app-key>',
  fileServer: 'your-file-server-address',
));

Statistics server​

Set the statistics server address. This applies only to standalone data centers. No configuration is needed by default — contact your sales representative if required.

statisticServer must be a valid server address. An invalid address causes push notifications and other services to fail.

Format requirements:

  1. For HTTPS: https://cn.xxx.com:port or https://cn.xxx.com. The domain can be an IP address. If no port is specified, port 443 is used by default.
  2. For HTTP: cn.xxx.com:port or cn.xxx.com. The domain can be an IP address. If no port is specified, port 80 is used by default. (iOS uses HTTPS by default. If you use HTTP, configure ATS permissions in your iOS project.)
Dart
await NCEngine.initialize(InitParams(
  appKey: '<your-app-key>',
  statisticServer: 'your-statistics-server-address',
));

Push configuration​

Push is a common feature. The Chat SDK includes built-in push support and integrates with multiple third-party push providers. Push is triggered after SDK initialization, so configure push settings before calling initialize. See Enable push notifications for details.

Android push configuration​

Configure push options during initialization. Enable the push channels your app supports:

Dart
await NCEngine.initialize(InitParams(
  appKey: '<your-app-key>',
  pushOptions: PushOptions(
    enableHWPush: true,
    enableFCM: true,
  ),
));

Kick reconnecting devices​

A user-level setting that determines whether to kick the currently reconnecting device on reconnection. Requires the App Key to have user-level configuration enabled. See Reconnection and device conflicts.

Dart
await NCEngine.initialize(InitParams(
  appKey: '<your-app-key>',
  reconnectKickEnable: true,
));

Compression options​

Configure how the SDK compresses images when sending.

ParameterTypeDescription
originalImageQualityint?Original image compression quality
originalImageMaxSizeint?Maximum file size of the original image after compression (in KB)
originalImageSizeint?Target file size for the original image (in KB). Images smaller than this are sent without compression.
thumbnailQualityint?Thumbnail compression quality
thumbnailMaxSizeint?Maximum file size of the thumbnail after compression (in KB)
Dart
await NCEngine.initialize(InitParams(
  appKey: '<your-app-key>',
  compressOptions: CompressOptions(
    originalImageQuality: 80,
    originalImageMaxSize: 1080,
    originalImageSize: 200,
    thumbnailQuality: 80,
    thumbnailMaxSize: 500,
  ),
));

Data center area​

Use areaCode to route SDK traffic to the correct data center.

Dart
await NCEngine.initialize(InitParams(
  appKey: '<your-app-key>',
  areaCode: AreaCode.sg,
));

Initial log level​

Set the SDK log level before initialization if you need more or less verbose logging during development or troubleshooting.

Dart
await NCEngine.initialize(InitParams(
  appKey: '<your-app-key>',
  logLevel: LogLevel.debug,
));

Runtime utilities​

These utility APIs are available after initialization and can help you inspect runtime configuration or adjust engine behavior.

Get app settings​

Use NCEngine.getAppSettings() to retrieve server-provided application settings.

Dart
final settings = await NCEngine.getAppSettings();
print('Speech to text enabled: ${settings?.speechToTextEnable}');
print('Message editable for minutes: ${settings?.messageModifiableMinutes}');

Change log level at runtime​

Use NCEngine.setLogLevel() to update the SDK log verbosity without reinitializing.

Dart
await NCEngine.setLogLevel(LogLevel.warn);

Get server time delta​

Use NCEngine.getServerTimeDelta() to calculate the offset between the local device clock and the IM server clock.

Dart
final delta = await NCEngine.getServerTimeDelta();
final serverTime = DateTime.now().millisecondsSinceEpoch - delta;
print('Server time: $serverTime');

Destroy the engine​

Call NCEngine.destroy() when the SDK instance is no longer needed. After calling this method, you must call NCEngine.initialize() again before using any SDK API.

Dart
await NCEngine.destroy();
Last updated on