CommsEase offers a network infrastructure that includes data centers and service nodes within and outside of Mainland China. This infrastructure allows your applications to effectively manage and process traffic from domestic Chinese regions and international locations.

This document describes how to connect your applications to data centers located outside of Mainland China, ensuring a seamless and reliable experience for users across various geographic regions.

Connect to international nodes

1. Create an application

2. Choose the overseas endpoint for API calling

3. Configure domain names for link and LBS in the SDK

Create an application

1. Create an application in the CommsEase console. For more information about how to create an application, see Create application and get AppKey.
2. Select the created application in the Applications section on the home page in the console.
3. Click Free trial or Activate Now, and specify other information.

Try it for free:

Activate the service：

4. If you want to try for free, click Try Now, or activate the service by clicking Select the Plan to configure and submit the transaction.

Configure API endpoints for global service regions

The default API endpoint is api.netease.im, which belongs to the data center in Mainland China. Data centers out of China use the exclusive domain names.

For example: the API endpoint for Singapore is api-sg.netease.im.

You must replace the domain name for API endpoints in your codebase.

Configure endpoints for link and LBS

For data centers out of Mainland China, the on-premises deployment is used by default. You must configure the link domain name and LBS domain name.

For example: the default link domain name for servers in Singapore is link-sg.netease.im:7000. The default weblink domain name for servers in Singapore is weblink01-sg.netease.im:443.

The LBS domain name uses lbs.netease.im.

Web

When initializing the SDK, add the LBS and link domain name in NIM.getInstance. For example:

javascriptvar nim = window.SDK.NIM.getInstance({
      "lbsUrl": "https://lbs.netease.im/lbs/webconf",
      "defaultLink": "weblink01-sg.netease.im:443",
    })

Parameters:

iOS

When initializing the SDK, configure the LBS and link domain name parameters in NIMServerSetting. You must create NIMServerSetting and specify the parameters. Example:

objective-csetting.lbsAddress =  @"https://lbs.netease.im/lbs/conf.jsp";
setting.linkAddress =  @"link-sg.netease.im:7000";

Parameters:

Android

Configure the LBS and link domain name in the private server address in SDKOptions. Example:

javaserverConfig.defaultLink = "link-sg.netease.im:7000"; 
serverConfig.lbs = "https://lbs.netease.im/lbs/conf.jsp"; 
serverConfig.nosUploadLbs = "http://wannos.127.net/lbs"; 
serverConfig.nosUploadDefaultLink = "https://nosup-hz1.127.net"; 
serverConfig.nosDownloadUrlFormat = "{bucket}-nosdn.netease.im/{object}"; 
serverConfig.nosUpload = "nosup-hz1.127.net"; 
serverConfig.nosSupportHttps = true;

Parameters:

Desktop

You must create the nim_server.conf file and move it in the same level directory of the SDK, and the SDK will automatically recognize it. See the following example for the nim_server.conf file:

json{
    "lbs":"https://lbs.netease.im/lbs/conf.jsp",
    "lbs.backup":[
        "https://lbs.netease.im/lbs/conf.jsp"
    ],
    "link":"link-sg.netease.im:7000",
    "nos_lbs":"https://wanproxy.127.net/lbs?version=1.0",
    "nos_uploader":"http://nosup-hz1.127.net",
    "nos_uploader_host":"nosup-hz1.127.net",
    "nos_downloader":"{bucket}.nosdn.127.net/{object}",
    "https_enabled":true
}

Before using the file, check whether the file is in valid JSON format.

Enhanced Web/uni-app/mini program

Add the parameters for the LBS and link domain name .

jsonnew NIM({

  "lbsUrls": ["https://lbs.netease.im/lbs/webconf"],
  "linkUrl": "weblink01-sg.netease.im:443"
  
})

jsongetInstance({

  "lbsUrls": ["https://lbs.netease.im/lbs/webconf"],
  "linkUrl": "weblink01-sg.netease.im:443"
  
})

Parameters:

Flutter

Configure the LBS and link domain name in NIMServerConfig. Example:

dartNIMServerConfig config = NIMServerConfig(
    defaultLink: "link-sg.netease.im:7000",
    lbs: "https://lbs.netease.im/lbs/conf.jsp",
    nosUploadLbs: "http://wannos.127.net/lbs",
    nosUploadDefaultLink: "https://nosup-hz1.127.net",
    nosDownloadUrlFormat: "{bucket}-nosdn.netease.im/{object}",
    nosUpload: "nosup-hz1.127.net",
    nosSupportHttps: true);
if (Platform.isAndroid) {
  final directory = await getExternalStorageDirectory();
  options = NIMAndroidSDKOptions(
      appKey: appKey,
      shouldSyncStickTopSessionInfos: true,
      serverConfig: config,
      sdkRootDir:
          directory != null ? '${directory.path}/NIMFlutter' : null);
} else if (Platform.isIOS) {
  final directory = await getApplicationDocumentsDirectory();
  options = NIMIOSSDKOptions(
    appKey: appKey,
    shouldSyncStickTopSessionInfos: true,
    sdkRootDir: '${directory.path}/NIMFlutter',
    apnsCername: 'ENTERPRISE',
    serverConfig: config,
    pkCername: 'DEMO_PUSH_KIT',
  );
}

Parameters:

Migration

For applications that have connected to the service nodes in Mainland China, you can migrate your data to service nodes out of Mainland China.

Notes

You can migrate the application data in Mainland China to the required service region, such as, user profile, friends data, conversation lists, group data, supergroup data, chat room data, message syncing, message history, and offline messaging.

• User profiles: all user profiles that has obtained the token can be migrated to data centers out of Mainland China, including user ID, user name, and user avatar.
• Group data: basic information and member information
• Supergroup data: basic information and member information
• Chat room data: basic information, permanent member information
• Message history data: Messages sent by the app can be migrated to data centers out of Mainland China, including: private 1-on-1 chat, group chat, and chat room messages.
• Offline message data: Messages that users have not received can be migrated to data centers out of Mainland China.

Before you begin

You must request Public Cloud Dedicated Service from CommsEase, and CommsEase will be responsible for deploying the dedicated cloud service. Consult sales for help.

Public Cloud Exclusive Service is used for isolated resources generated during migration to ensure that the business will not be disturbed by public cloud traffic. The deployment time is subject to the actual migration time. After all migrations are completed, the service deployment can be canceled.

Migration procedure

1. Contact sales for migrating data of the required application with the AppKey to a specific global data center, and confirm the scope with technical support.

2. For the data generated in the public cloud (api.netease.im) in Mainland China before migration, CommsEase will deploy dedicated cloud services with API endpoints and the link domain name.

3. You must replace the public cloud domain name for API endpoints with the dedicated cloud domain name.

4. Replace the link public cloud domain name for link in the SDK with dedicated cloud domain name, and release a new version of the app client.

5. CommsEase deploys dedicated cloud services to the destination data center (api-sg.netease.im) for migration and migrates the data stored in the public cloud data center in Mainland China to the destination data center.

6. Update the app client. Fro migration from Mainland China to service regions out of Mainland China, the app clients must be force upgraded to the new version to connect to the service region because the link endpoint of the server is changed. Legacy versions will not be unable to connect to the server.

7. You must contact sales for the specific schedule for migration. If the migration is scheduled, CommsEase will transfer the traffic to the destination service region. It is recommended to perform migration during the off-peak period of online business.

Notes

• The data of your application whose workload is running in the service region out of Mainland China is stored out of China, including but not limited to:

  • accounts (accid, nickname, avatar)
  • Groups and chat rooms
  • Friends and blocklist
  • Message history
  • Images and files
  • Others

• Data centers in China and out of China:

  • Application information is shared, such as AppKey and settings (CommsEase and Moderator)
  • The data generated in the operation of the application is stored in the data center to which belongs.

• Content moderator

  • The data audited by Content moderator is not delivered to data centers in China.
  • Support multilingual content moderation.

• The link, weblink, chatlink, chatwl, and API domain names of data centers in China and out of China are separate and isolated. If an error occurs during connection, 403 will be returned.

• To facilitate access, accelerator proxies are deployed for data centers out of China, such as: Singapore API domain name api-sg.netease.im.

  • The BGP entry to China can be resolved, but all data will eventually be stored in Singapore.
  • In the US region, the SDK can parse the accelerator entry to the US, but all data will eventually be stored in Singapore.

FAQ on data migration

Q: Does the app have to be upgraded?

A: Yes, CommsEase only supports overseas service region from IM v8.10.0, and the endpoints configured in the SDK must be replaced with the domain name out of China. The app client must be upgraded to the new version before connecting to the destination data center.

Q: Is message syncing supported for migration.

A: Yes, 7 days before the migration, CommsEase will enable the dual-write mode. Messages are synced in the destination data center.

Q: Does the message history stored on the CommsEase server support migration?

A： Yes, you must contact sales for the time scope of the data for migration.

Q: Does CommsEase support migration from data center out of China nodes in China?

A: No.

Q: Is the service unavailable during the migration?

A: Yes, all clients will be forced to log out during migration, triggering reconnection to the data centers out of China. During the migration, services will stops in a few minutes, in most cases, less than one.

Q: Does CommsEase support the migration of images and files?

A: No. Images and files will not be migrated, and will still be stored in data centers China, but access will not be affected.