Skip to content

Latest commit

 

History

History
182 lines (129 loc) · 7.22 KB

README.md

File metadata and controls

182 lines (129 loc) · 7.22 KB
Raw

React Native Client SDK for OpenIM 👨‍💻💬

Use this SDK to add instant messaging capabilities to your application. By connecting to a self-hosted OpenIM server, you can quickly integrate instant messaging capabilities into your app with just a few lines of code.

The iOS SDK core is implemented in OpenIM SDK Core. Using gomobile, it can be compiled into an XCFramework for iOS integration. iOS interacts with the OpenIM SDK Core through JSON, and the SDK exposes a re-encapsulated API for easy usage. In terms of data storage, iOS utilizes the SQLite layer provided internally by the OpenIM SDK Core.

The android SDK core is implemented in OpenIM SDK Core. Using gomobile, it can be compiled into an AAR file for Android integration. Android interacts with the OpenIM SDK Core through JSON, and the SDK exposes a re-encapsulated API for easy usage. In terms of data storage, Android utilizes the SQLite layer provided internally by the OpenIM SDK Core.

The React Native Client SDK use NativeModule system exposes instances of Java/Objective-C classes to JavaScript (JS) as JS objects, thereby allowing you to execute arbitrary native code from within JS.

Tips 🔔

  1. The [email protected] has contains significant disruptive updates. If you need to upgrade, please check the incoming data and the returned data.

  2. Unlike other SDKS, React Native SDK operationID is not optional, but required.

Documentation 📚

Visit https://doc.rentsoft.cn for detailed documentation and guides.

For the SDK reference, see https://doc.rentsoft.cn/sdks/quickstart/reactnative.

Installation 💻

Adding Dependencies

yarn add open-im-sdk-rn

For android add following urls to build gradle:

https://open-im-online.rentsoft.cn:51000/repository/maven2/

// Top-level build file where you can add configuration options common to all sub-projects/modules.
buildscript {
    ext {
        buildToolsVersion = "33.0.0"
        minSdkVersion = 21
        compileSdkVersion = 33
        targetSdkVersion = 33

        // We use NDK 23 which has both M1 support and is the side-by-side NDK version from AGP.
        ndkVersion = "23.1.7779620"
    }
    repositories {
        google()
        mavenCentral()
        maven {
            allowInsecureProtocol = true
            url 'https://open-im-online.rentsoft.cn:51000/repository/maven2/'
        }
    }
    dependencies {
        classpath("com.android.tools.build:gradle")
        classpath("com.facebook.react:react-native-gradle-plugin")
    }
}
allprojects {
    repositories {
        maven {
            allowInsecureProtocol = true
            url 'https://open-im-online.rentsoft.cn:51000/repository/maven2/'
        }
    }
}

Usage 🚀

The following examples demonstrate how to use the SDK. TypeScript is used, providing complete type hints.

Importing the SDK and init

import OpenIMSDKRN from 'open-im-sdk-rn';
import RNFS from 'react-native-fs';

RNFS.mkdir(RNFS.DocumentDirectoryPath + '/tmp');

OpenIMSDKRN.initSDK({
  platformID: 2,  // 1: ios, 2: android
  apiAddr: 'http://your-server-ip:10002',
  wsAddr: 'ws://your-server-ip:10001',
  dataDir: RNFS.DocumentDirectoryPath + '/tmp',
  logLevel: 5,
  isLogStandardOutput: true,
}, 'opid');

Logging In and Listening for Connection Status

import OpenIMSDKRN, { OpenIMEmitter } from 'open-im-sdk-rn';

OpenIMSDKRN.login({
  userID: 'IM user ID',
  token: 'IM user token',
}, 'opid');

OpenIMEmitter.addListener('onConnecting', () => {
  console.log('onConnecting');
});

OpenIMEmitter.addListener('onConnectSuccess', () => {
  console.log('onConnectSuccess');
});

OpenIMEmitter.addListener('onConnectFailed', ({ errCode, errMsg }) => {
  console.log('onConnectFailed', errCode, errMsg);
});

To log into the IM server, you need to create an account and obtain a user ID and token. Refer to the access token documentation for details.

Receiving and Sending Messages 💬

OpenIM makes it easy to send and receive messages. By default, there is no restriction on having a friend relationship to send messages (although you can configure other policies on the server). If you know the user ID of the recipient, you can conveniently send a message to them.

import OpenIMSDKRN, { OpenIMEmitter } from 'open-im-sdk-rn';
import type { MessageItem } from 'open-im-sdk-rn';

OpenIMEmitter.addListener('onRecvNewMessages', (data: MessageItem[]) => {
  console.log('onRecvNewMessages', data);
});

const message = await OpenIMSDKRN.createTextMessage('hello openim', 'opid');

OpenIMSDKRN.sendMessage({
  recvID: 'recipient user ID',
  groupID: '',
  message,
}, 'opid')
  .then(() => {
    // Message sent successfully ✉️
  })
  .catch(err => {
    // Failed to send message ❌
    console.log(err);
  });

Examples 🌟

You can find a demo web app that use the SDK in the openim-reactnative-demo repository.

or:

Use the examples(only the simplest SDK calls) under this project to try it out:

yarn

yarn example android

yarn example ios

Community 👥

Community Meetings 📆

We want anyone to get involved in our community and contributing code, we offer gifts and rewards, and we welcome you to join us every Thursday night.

Our conference is in the OpenIM Slack 🎯, then you can search the Open-IM-Server pipeline to join

We take notes of each biweekly meeting in GitHub discussions, Our historical meeting notes, as well as replays of the meetings are available at Google Docs 📑.

Who are using OpenIM 👀

Check out our user case studies page for a list of the project users. Don't hesitate to leave a 📝comment and share your use case.

License 📄

OpenIM is licensed under the Apache 2.0 license. See LICENSE for the full license text.