Skip to main content

Quick Start

This tutorial is designed to help beginners quickly get familiar with RC's Instant Messaging library (IMLib). In this tutorial, you will experience the basic process of integrating the SDK and the fundamental communication capabilities of IMLib.

Prerequisites​

  • Register a developer account. Upon successful registration, the Console will automatically create your first application by default, generating an App Key for the Development environment and using the Singapore Data Center.

  • Obtain the App Key for the development environment from the App Key page. If you are not using the default application, please refer to How to create an application and obtain the corresponding App Key and App Secret.

    tip

    Each application has two different App Keys, corresponding to the Development and Production environments, with data isolation between the two environments. Before your application officially goes live, you can switch to using the Production environment App Key for pre-launch testing and final release.

Environment Requirements​

Version >= 5.12.1

  • Dart: >=2.15.0 < 4.0.0
  • Flutter: ≧ 2.5.0

Version < 5.12.1

  • Dart: >= 2.15.0 < 3.0.0
  • Flutter: ≧ 2.5.0

Demo Project​

RC IMLib for Flutter SDK provides a Demo project without any chat UI, demonstrating the calling methods of various interfaces.

https://github.com/rongcloud/im-flutter-wrapper

Import SDK​

RC provides the SDK in the form of a plugin library on the Flutter platform, which includes both the Dart layer and the Android/iOS platform layer code.

  1. Add dependencies in the project's pubspec.yaml. The latest version of the SDK can be queried from the official repository.

    dependencies:
      flutter:
        sdk: flutter

    rongcloud_im_wrapper_plugin: x.y.z

  2. Execute flutter pub get in the project directory to download the relevant plugins.

  3. Import the header file.

    import 'package:rongcloud_im_wrapper_plugin/rongcloud_im_wrapper_plugin.dart';

Disable Android Auto Obfuscation​

If you need to configure obfuscation, please refer to the Android documentation.

If you do not need to configure obfuscation, disable auto obfuscation. Otherwise, when executing flutter build apk, Flutter will automatically obfuscate the Android code, leading to errors where the so library cannot be found.

android {
     buildTypes {
         release {
             // Enables code shrinking, obfuscation, and optimization for only
             // your project's release build type.
             minifyEnabled false

             // Enables resource shrinking, which is performed by the
             // Android Gradle plugin.
             shrinkResources false
         }
     }
     ...
 }

Initialization​

Before using all the features of the SDK, you must call this method to initialize the SDK. All interfaces within the SDK need to be called through the RCIMIWEngine object, which can only be obtained through the create method. Therefore, after obtaining the entity object by calling the create method, developers need to save it themselves for subsequent interface calls.

During initialization, you need to pass the App Key obtained earlier.

RCIMIWEngineOptions options = RCIMIWEngineOptions.create();
RCIMIWEngine engine = await RCIMIWEngine.create(appKey, options);

For engine configuration, please refer to Engine Configuration.

Obtain User Token​

The user Token is an authentication token corresponding to the user ID and is the unique identity of the application user in RC. Before using RC's instant messaging features, the application client must establish an IM connection with RC, and the Token must be passed during the connection.

In actual business operations, the application client needs to call the IM Server API through the application server to obtain the Token. For details, see the Server API documentation User Registration.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200,"userId":"1","token":"gxld6GHx3t1eDxof1qtxxYrQcjkbhl1V@sgyu.cn.example.com;sgyu.cn.example.com"}

Establish IM Connection​

  1. Use onConnectionStatusChanged to listen for changes in the IM connection status. When the connection status changes, [RCIMIWConnectionStatus] is returned. For details, see Connection Status Listener.

    engine?.onConnectionStatusChanged = (RCIMIWConnectionStatus? status) {
    //...
    };

  2. Use the Token obtained above to simulate the user with userId 1 connecting to the RC server. The result of the call will be directly returned through the [RCIMIWConnectCallback] passed in the connect method.

    RCIMIWConnectCallback? callback = RCIMIWConnectCallback(onDatabaseOpened: (int? code) {
    //...
    }, onConnected: (int? code, String? userId) {
    //...
    });

    int? ret = await engine?.connect(token, timeout, callback:callback);

The SDK has implemented an automatic reconnection mechanism. Please refer to Connection.

Message Listener​

To implement this feature, developers need to implement the message listener callback.

Set up a message receiver listener to receive all types of real-time or offline messages.

  1. message The received message object
  2. left After the client successfully connects, the server will send all compensation messages to the client in the form of message packages, with a maximum of 200 messages per package. After receiving the message package, the client will parse it one by one and notify the application. left indicates the number of messages remaining in the current message package.
  3. offline Whether the message is an offline message
  4. hasPackage Whether there are undelivered message packages on the server
engine?.onMessageReceived = (RCIMIWMessage? message, int? left, bool? offline, bool? hasPackage) {
//...
};

Send Message​

RCIMIWTextMessage? textMessage = await engine.createTextMessage(
        conversationType,
        targetId,
        channelId,
        text,
      );

engine.sendMessage(message);

Listen to Message Sending Result​

engine?.onMessageAttached = (RCIMIWMessage? message) {
//...
};

engine?.onMessageSent = (int? code, RCIMIWMessage? message) {
//...
};

Logout​

int? ret = await engine?.disconnect(receivePush);

Destroy the engine​

await engine?.destroy();
Last updated on