Initialization

Update time: 2024/03/07 11:13:59

After integrating the NIM SDK for Flutter, you must initialize the SDK and create an SDK instance.

Prerequisites

Before starting initialization, make sure you have Integrated the SDK.

Initialize the SDK

After you integrate the SDK, you can initialize the SDK by calling the initialize method.

Sample code:

dart
final NIMSDKOptions options;
if (Platform.isAndroid) {
  options = NIMAndroidSDKOptions(
    appKey: 'appkey',
    /// Other generic options
  );
} else if (Platform.isIOS) {
  options = NIMIOSSDKOptions(
    appKey: 'appkey',
    /// Other generic or iOS configuration
  );
} else if (KisWeb) {
    options = NIMSDKOptions(
      appKey: 'appKey',
      /// Other generic parameters    
    )
}
NimCore.instance.initialize(options)
    .then((result){
        if (result.isSuccess) {
            /// success
        } else {
            /// Initialization failure
        }
    });

Configure parameters for initialization

You can configure parameters for SDK initialization with NIMSDKOptions. NIMSDKOptions contains options for different platforms.

  • NIMSDKOptions provides basic options for generic parameters.
  • NIMAndroidSDKOptions specifies parameters applied to only Android apps.
  • NIMIOSSDKOptions specifies parameters applied to only iOS apps.
  • NIMWINDOWSSDKOptions specifies parameters applied to only Windows apps.
  • NIMMACOSSDKOptions specifies parameters applied to only macOS apps.

Web apps use common parameters.

Common parameters

NIMSDKOptions representation

Parameter Type Required Description
appKey String Yes Specify the AppKey
sdkRootDir String No Root directory of the external storage for storing multimedia messages and log files.
enablePreloadMessageAttachment bool No Whether the SDK automatically load attachment of multimedia messages.
shouldSyncUnreadCount bool No Whether to enable multi-device synchronization for read messages.
shouldTeamNotificationMessageMarkUnread bool No Whether group notifications are counted as unread. The group notifications are not counted as unread by default.
enableAnimatedImageThumbnail bool No Enable animation thumbnails. The default value is false. if true, the first frame of the animation image will be captured as the thumbnail.
enableTeamMessageReadReceipt bool No Whether to enable read receipt for group messages. the setting is disabled by default.
shouldConsiderRevokedMessageUnreadCount bool No Whether to decrement the unread count for recalled messages.
nosSceneConfig Map<NIMNosScene, int> No Set the scenario of Netease Object Storage (NOS) to specify the expiration time of IM-related resources (such as attachments of multimedia messages) on NOS.
loginCustomTag String No Custom field for login, synced with other devices after successful logins. Other devices can get the field by listening to the event stream of multi-device login (AuthService#onlineClients).
shouldSyncStickTopSessionInfos bool No Whether to sync pinned sessions.
cdnTrackInterval int No Interval for reporting CDN info
enableDatabaseBackup bool No Whether to enable database backup.
enableReportLogAutomatically bool No Whether to enabled automatically reporting IM logs. The setting is disabled by default.
autoLoginInfo NIMLoginInfo No Account info for automatic login. Windows and macOS are not supported.

Android-specific parameters

NIMAndroidSDKOptions representation

Parameter Type Required Description
notificationConfig NIMStatusBarNotificationConfig No Settings for the notification bar
improveSDKProcessPriority bool Yes Specify whether to increase the priority of the SDK process. By default, the setting is enabled. This default value can lower the probability of the SDK core process being recycled by the system.
preLoadServers bool Yes Preload services. The default setting is true. We recommend you not set the value to false. Preloading connections can optimize the login process.
reducedIM bool Yes Specify whether the scene is non-intensive messaging. The default value is false. Set the value to true if your app only uses the messaging capability on demand at times (automatic login is not required when the application starts) and notification messages and data are not required to be synced in real time. In non-intensive messaging scenarios, the push process adopts the lazy start strategy (delayed until the login), and its life cycle will follow the UI process after startup. This reduces the background power consumption of the app.
checkManifestConfig bool Yes Whether to check the configuration of the manifest file is complete when the SDK is initialized. The default is false, Set the value to true in debugging phase, and false if your app rolls out.
mixPushConfig NIMMixPushConfig No Configure appid, appkey and certificates pushed by third parties.
disableAwake bool Yes Whether to disable background processes from awakening UI processes.
fetchServerTimeInterval int Yes Get the interval between consecutive requests sent to get the server time. The minim value is 1000ms. The default value is 2000ms.
customPushContentType String No The custom type of the string to be displayed when offline push notifications does not show details. For information about how to configure the settings for hiding details of push notifications, see Push body.
databaseEncryptKey String No Database encryption key, used for message database encryption.
If the key is unspecified, the database is in the plain text state. If the key is configured, the data stored in the database will be encrypted. Encrypted data cannot be stored in plain text.
thumbnailSize int Yes The size of a thumbnail. The value is the length of thumbnail. The length of the downloaded thumbnail will not exceed this value. Default value: 350px
enableFcs bool Yes Whether to enable converged storage. Converged storage provides a new storage method for international users. After enabling converged storage, the SDK will automatically enable CDN acceleration to select the fastest node for storage when the application receives file messages, and store the file messages on AWS servers or NetEase Object Storage (NOS) servers. Default value: true.
Note: Though Converged Storage is enabled by default, the service must be activated before use. You can consult the business manager to activate this service using the WhatsApp provided on the homepage of CommsEase official website

iOS-specific parameters

NIMIOSSDKOptions representation:

Parameter Type Required Description
apnsCername String No Name of APNs certificate configured in the CommsEase console
pkCername String No Name of PushKit certificate configured in the CommsEase console
disableTraceroute bool No Whether to disable the traceroute capability of NIM SDK for Flutter. The default value is NO. If a request fails, the SDK will perform traceroute to detect each node in the network to determine which node loses the connection.
maxUploadLogSize int No The upper limit of the log size. The default value is 0, and no limit is applied. Unit: bytes
enableFetchAttachmentAutomaticallyAfterReceivingInChatroom bool No Whether to automatically download attachments after receiving chat room messages, the default is No.
enableFileProtectionNone bool No Specify whether to use NSFileProtectionNone as NSProtectionKey. Default value: NO. The setting takes effect only if Data Protection is enabled in the upper tier of your app.
enabledHttpsForInfo bool No Enable the HTTPS protocol support for user profiles. The default value is YES. By default, user avatars, group avatars, and user avatars in chat rooms are hosted on CommsEase servers. The SDK will automatically enable HTTPS support. If you want to host all the data on your app server, you must set this parameter to NO to prevent the SDK from automatically converting HTTP URLs to HTTPS URLs.
enabledHttpsForMessage bool No Whether to enable HTTPS protocol support for message content, default is YES. By default, messages, including images, videos, and audio data, are hosted on CommsEase servers. The SDK will automatically enable HTTPS support for the data. To host all the data on your app server, you must this parameter to NO (NOT recommended) to prevent the SDK from automatically converting HTTP URLs to HTTPS URLs. Note that even if this parameter is set, the URL of a message sent by the SDK is still using the HTTPS protocol, and this setting only affects the URL format conversion of received messages.
maxAutoLoginRetryTimes int No Number of auto login retries, default is 0. By default, automatic login will retry infinitely. If the value set to a number greater than 0, the automatic login will retry up to maxAutoLoginRetryTimes times before successful login
maximumLogDays int No Validity period for local logs, default is 7 days. local log stored more than 7 days will be cleared. Only values greater than or equal to 2 are valid.
disableReconnectInBackgroundState bool No Whether to disable reconnection in the background. The default is NO. By default, if an app is switched to the background and gets disconnected and is still running, the SDK will continue to execute the automatic reconnection mechanism. If the value is set to YES, the app will not automatically reconnect in the background, and the reconnection will be postponed until the app is switched to the foreground. This setting is only required for special scenarios. Proceed with caution.
enableTeamReceipt bool No Enable read receipt of group messages. The default value is NO.
enableFileQuickTransfer bool No Whether to enable file quick transfer, the default is YES.
enableAsyncLoadRecentSession bool No Whether to enable asynchronous reading of recent sessions. The default value is NO. For users with numerous recent sessions, the startup speed may be affected in retrieving data from the database. These Users can enable this option to enable asynchronous loading recent sessions and querySessionList returns a part of recent sessions. When all sessions are loaded, the result will be sent to users and the UI will be refreshed

Parameters for Windows

NIMWINDOWSSDKOptions representation

Parameter Type Required Description
databaseEncryptKey String Database encryption key, used for message database encryption. Only encryption keys of up to 32 characters are supported. Use 32 characters for the key.
preloadImageQuality int No Quality of pre-download image, optional, value range: 0-100.
preloadImageResize String No Pre-loaded images based on the length and width of a scale-down thumbnail, optional. For example, an thumbnail with width 100 and height 50 can be assigned 100x50, The lowercase x is used in the middle.
preloadImageNameTemplate String No Pre-download image naming rules, replace with {filename} as token.
maxAutoLoginRetryTimes int No The maximum number of auto retries for login failures. Set the value greater than 3. Default value: 0.
enabledHttps bool No Enable the HTTPS protocol. The default value is true.
shouldVchatMissMessageMarkUnread bool No Whether new audio message are counted as unread. The audio messages are not counted as unread by default.
enableClientAntispam bool No Whether the client-side content moderation is enabled. The default value is false. To enable the service, contact your account manager.
needUpdateLbsBeforeRelogin bool No Whether the LBS endpoints are refreshed before re-login. The option is suitable for switching networks.

Parameters for macOS

NIMMACOSSDKOptions representation

Parameter Type Required Description
databaseEncryptKey String Database encryption key, used for message database encryption. Only encryption keys of up to 32 characters are supported. Use 32 characters for the key.
preloadImageQuality int No Quality of pre-download image, optional, value range: 0-100.
preloadImageResize String No Pre-loaded images based on the length and width of a scale-down thumbnail, optional. For example, an thumbnail with width 100 and height 50 can be assigned 100x50, The lowercase x is used in the middle.
preloadImageNameTemplate String No Pre-download image naming rules, replace with {filename} as token.
maxAutoLoginRetryTimes int No The maximum number of auto retries for login failures. Set the value greater than 3. Default value: 0.
enabledHttps bool No Enable the HTTPS protocol. The default value is true.
shouldVchatMissMessageMarkUnread bool No Whether new audio message are counted as unread. The audio messages are not counted as unread by default.
enableClientAntispam bool No Whether the client-side content moderation is enabled. The default value is false. To enable the service, contact your account manager.
needUpdateLbsBeforeRelogin bool No Whether the LBS endpoints are refreshed before re-login. The option is suitable for switching networks.
pushCertName String No The name of the push certificate configured in the CommsEase console.
pushToken String No The token of a device for receiving push notifications
enableAppNap bool No Specify whether App Nap is enabled on macOS. The default value is false
Was this page helpful?
Yes
No
  • Prerequisites
  • Initialize the SDK
  • Configure parameters for initialization
  • Common parameters
  • Android-specific parameters
  • iOS-specific parameters
  • Parameters for Windows
  • Parameters for macOS