Skip to main content

🚀 Usage Demo​

Note: Demo is only used to demonstrate the introduction and use of the SDK, and is not a complete application.

We strongly recommend that you first run the framework-related examples we have prepared for you DEMO. This will not only allow you to intuitively experience the functionality of OpenIMSDK but also help you quickly identify and resolve issues during the actual integration process.

❗️Tips​

1. Server Preparation​

2. Developing Cross-Platform Applications (APP, H5, Mini Programs) with Uni​

  • The latest npm package now supports the development of cross-platform applications on uni-app. However, it requires the use of conditional compilation syntax. It is recommended to refer to the demo before starting development, as it demonstrates how to develop in a cross-platform scenario.

2. Development for H5/Mini Programs Only​

  • If you are developing for H5 and Mini Programs (or native Mini Programs) using uniapp, simply use the pure JS version SDK without following the steps below.

Integration Steps​

Including APP-side development, it is essential to follow the steps below to import the SDK using cloud plugins and npm packages. This is because the implementation for the APP side is done through App Native Language Plugins.

1. Add Dependencies​

Official plugins have been uploaded to the dcloud plugin market.

  • Choose the corresponding project and package name to import the SDK.

uni_import

  • Open the manifest.json file in the root directory of the imported SDK project, select App Native Plugin Configuration, and import the cloud plugin.

uni_import_manifest

  • Download the npm package to simplify the import and use of the SDK and wrap the API in Promise form.

For versions of openim-uniapp-polyfill >= 1.3.0, use the pure JS version SDK for non-APP platforms.

npm install openim-uniapp-polyfill open-im-sdk

2. Import in Project (Pure APP Project)​

import IMSDK from 'openim-uniapp-polyfill';

IMSDK.asyncApi('login', IMSDK.uuid(), {
  userID: '123',
  token: 'token',
});

const onConnectSuccess = () => {
  // Connection successful
};
// Set up listener
IMSDK.subscribe(IMSDK.IMEvents.OnConnectSuccess, onConnectSuccess);
// Unsubscribe listener
IMSDK.unsubscribe(IMSDK.IMEvents.OnConnectSuccess, onConnectSuccess);

3. Import in Project (APP、H5、Mini Program Project)​

You need to use cloud plugins to import the SDK. For the new npm package, use the pure JS version SDK for non-APP platforms.

  • Note 1: openim-uniapp-polyfill version should be >= 1.2.0 ,open-im-sdk version should be >= 3.5.1-alpha.8 .

  • Note 2: Use uniapp's method to call listeners, passing in methods from IMSDK.IMEvents, as there is a difference in case sensitivity between JSSDK and APP. This conversion is already handled in the npm package.

  • Note 3: In some APIs, there may be differences between platforms due to platform support. When using them, check the documentation for the respective platform's API and note the differences:

    • Depending on the platform, pass the correct platformID.
    • Login API parameters may vary.
    • On APP you need to initSDK before using it.
    • Creating image and file messages uses different APIs, so use conditional compilation to call different methods.
    • And so on...

3.1 Usage in Cross-Platform Scenarios​

Method 1: If parameters and method names are consistent across platforms, use uniapp's method to call them.

  • This is a multi-platform compatible approach. In cross-platform scenarios, check if the API return content structure is consistent.
import IMSDK from 'openim-uniapp-polyfill';

IMSDK.asyncApi('createTextMessage', IMSDK.uuid(), 'text')
  .then((data) => {
    // do something
  })

Method 2: If parameters and method names differ across platforms, use conditional compilation to handle significant parameter differences.

import IMSDK from 'openim-uniapp-polyfill';

// #ifdef H5 || MP-WEIXIN
IMSDK.asyncApi('login', IMSDK.uuid(), {
  userID : '123',
  token: 'token',
  platformID: 5,
  wsAddr: 'ws://your-server-ip:10003',
  apiAddr: 'http://your-server-ip:10002',
});
// #endif

// #ifdef APP-PLUS
IMSDK.asyncApi('login', IMSDK.uuid(), {
  userID: '123',
  token: 'token',
});
// #endif

4. 🛠️ Local Development​

4.1 Create Custom Debug Base​

Note: The package name needs to match the package name set when importing cloud plugins in the first step.

uni_build

4.2. Run on Custom Debug Base​

When debugging the APP side locally, you must package a custom base and start debugging on it.

uni_run

5. 🚀 Build and Release​

For APP platform packaging and release, use Release -> Native APP Cloud Packaging.