Skip to main content

Initialization

To ensure proper connection to RC servers and usage of RC's Instant Messaging (IM) service, you must initialize the IMLib SDK by calling the init method. This article provides detailed instructions for initializing the IMLib SDK.

For first-time RC users, we recommend reading the [IMLib SDK Quick Start Guide] to complete developer account registration and other preliminary tasks.

Push Notifications​

Push notifications are a fundamental feature. The IMLib SDK integrates RC's native push service along with multiple third-party push services, which are triggered after SDK initialization. Therefore, client-side push configurations must be provided before initialization. For details, refer to Enabling Push Notifications.

Global Data Centers​

  • If using global data centers with development version (dev) SDK 5.4.2 or newer, ensure you pass the correct area code (AreaCode) in the initialization configuration.
  • If using stable version (stable) SDK or development version (dev) SDK earlier than 5.4.2 with global data centers, you must modify the IMLib SDK's connection service address to the global data center address before initialization. Otherwise, the SDK will default to connecting to the China (Beijing) Data Center address. For details, see [Configuring Global Data Center Service Addresses].

Processes​

tip

Starting from version 5.3.0, IMLib SDK supports single-process mode.

The SDK supports both multi-process and single-process mechanisms.

For SDK versions < 5.3.3 or ≥ 5.3.5, the default is multi-process mode. After initialization, the application will launch:

  1. The main application process
  2. <application package name>:ipc - The core IM communication process, isolated from the main process tasks
  3. io.rong.push - RC's default push process (launch depends on push channel activation strategy). See Enabling Push Notifications for details.

For SDK versions ≥ 5.3.3 and < 5.3.5, single-process mode is enabled by default.

Starting from version 5.3.0, you can enable or disable single-process mode before initialization using the enableSingleProcess interface of RongCoreClient. Note that enabling single-process mode will consume additional memory in the main process.

//Enable single-process mode
RongCoreClient.getInstance().enableSingleProcess(true);

Initializing the SDK​

tip

The following initialization method requires SDK version ≥ 5.4.2. Check the latest development (Dev) and stable (Stable) version numbers on the RC Official Website SDK Download Page.

Initialize the SDK in the Application's onCreate() method, passing either the production or development environment App Key.

String appKey = "YourAppKey"; // example: bos9p5rlcm2ba
InitOption initOption = new InitOption.Builder().build();

RongCoreClient.init(this, appKey, initOption);

The initialization configuration (InitOption) includes the area code (AreaCode) setting. The SDK uses this to obtain valid navigation service addresses, file service addresses, statistics service addresses, and logging service addresses.

  • For App Keys belonging to the China (Beijing) Data Center, no configuration is needed as the SDK uses default settings.
  • For App Keys belonging to global data centers, you must provide the correct area code (AreaCode). Verify your App Key's data center in the Console and configure the corresponding enum value.

Example for a production/development App Key using the Singapore data center:

String appKey = "Singapore_dev_AppKey";
AreaCode areaCode = AreaCode.SG;

InitOption initOption = new InitOption.Builder()
    .setAreaCode(areaCode)
    .build();

RongCoreClient.init(context, appKey, initOption);

Besides the area code, the initialization configuration (InitOption) also includes:

  • Push notification toggle (enablePush): Globally enables/disables push
  • Main process toggle (isMainProcess): Identifies the main process (auto-detected by default)
  • Navigation service address (naviServer): Not recommended for custom configuration (SDK uses area-specific defaults)
  • File service address (fileServer): For private cloud only
  • Statistics service address (statisticServer): Not recommended for custom configuration (SDK uses area-specific defaults)
String appKey = "Your_AppKey";
AreaCode areaCode = AreaCode.BJ;

InitOption initOption = new InitOption.Builder()
    .setAreaCode(areaCode)
    .enablePush(true)
    .setFileServer("http(s)://fileServer")
    .setNaviServer("http(s)://naviServer")
    .setStatisticServer("http(s)://StatisticServer")
    .build();

RongCoreClient.init(context, appKey, initOption);

Legacy SDK Initialization​

tip

Use this method only if your development SDK version is < 5.4.2 or stable SDK version is ≤ 5.3.8. We recommend upgrading to the latest SDK version.

Initialize the SDK in the Application's onCreate() method, passing either the production or development environment App Key. You can use either RongCoreClient or RongIMClient initialization methods.

RongCoreClient.init(context, appKey, enablePush);
ParameterTypeDescription
contextContextApplication context
appKeyStringDevelopment or production environment AppKey (don't mix). Optional if configured in AndroidManifest.xml
enablePushbooleanWhether to [enable push notifications]. Default true. Note: Initial setting takes effect permanently after first successful push token registration. Setting to false later won't disable push if previously enabled.

For backward compatibility, IMLib SDK 5x still supports App Key configuration in AndroidManifest.xml. However, due to App Key security concerns, RC no longer recommends this approach.

We recommend initializing only after users accept the privacy agreement.

/**
 * During app launch, check if user has accepted privacy agreement. If yes, initialize normally; otherwise redirect to privacy authorization page.
 */
public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        //Pseudo-code: Read privacy acceptance status from shared preferences
        boolean isPrivacyAccepted = getPrivacyStateFromSp();
        //Initialize if user accepted privacy agreement
        if (isPrivacyAccepted) {
            String appKey = "Your AppKey from RC Console";
            //First parameter must be application context
            RongIMClient.init(this.getApplicationContext(), appKey);
        } else {
            //Redirect to privacy authorization page if not accepted
            goToPrivacyActivity();
        }
        ...
    }
}

/**
 * Privacy authorization page demonstrating IM initialization after user acceptance
 */
public class PrivacyActivity extends Activity implements View.OnClickListener {
    ...
    @Override
    public void onClick(View v) {
        switch (v.getId()) {
            case R.id.accept_privacy:
                //Pseudo-code: Save acceptance to shared preferences
                savePrivacyStateToSp();

                String appKey = "Your AppKey from RC Console";
                //First parameter must be application context
                RongIMClient.init(this.getApplicationContext(), appKey);
                break;
            default:
                ...
        }
    }
}
Last updated on