From b6a71d0b6fce858d87a93dc7c41a07bcae4ebb36 Mon Sep 17 00:00:00 2001 From: Oliver Wong Date: Thu, 12 Oct 2023 16:23:45 +0800 Subject: [PATCH] Update README.md Update README.md --- README.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 152 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index cfb7dd2..543ea6a 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,160 @@ -# flutter_openim_sdk -image +# Flutter Client SDK for OpenIM ๐Ÿ‘จโ€๐Ÿ’ป๐Ÿ’ฌ -[![pub package](https://img.shields.io/pub/v/flutter_openim_sdk.svg)](https://pub.flutter-io.cn/packages/flutter_openim_sdk) -[![Generic badge](https://img.shields.io/badge/platform-android%20|%20ios%20-blue.svg)](https://pub.dev/packages/flutter_openim_sdk) -[![GitHub license](https://img.shields.io/github/license/OpenIMSDK/Open-IM-SDK-Flutter)](https://github.com/OpenIMSDK/Open-IM-SDK-Flutter/blob/main/LICENSE) +Use this SDK to add instant messaging capabilities to your Flutter app. By connecting to a self-hosted [OpenIM](https://www.openim.online/) server, you can quickly integrate instant messaging capabilities into your app with just a few lines of code. -A flutter im plugin for android and ios. -#### [demo open source code](https://github.com/OpenIMSDK/Open-IM-Flutter-Demo.git) +The underlying SDK core is implemented in [OpenIM SDK Core](https://github.com/openimsdk/openim-sdk-core). Using [gomobile](https://github.com/golang/mobile), it can be compiled into an AAR file for Android integration. Android interacts with the [OpenIM SDK Core](https://github.com/openimsdk/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](https://github.com/openimsdk/openim-sdk-core). -Scan the QR code below to experience the SDK call example Demo -![Android](https://www.pgyer.com/app/qrcode/OpenIM-Flutter) -# [SDK Documents](https://doc.rentsoft.cn/sdks/quickstart/flutter) +## Documentation ๐Ÿ“š +Visit [https://doc.rentsoft.cn/](https://doc.rentsoft.cn/) for detailed documentation and guides. + +For the SDK reference, see [https://doc.rentsoft.cn/sdks/quickstart/browser](https://doc.rentsoft.cn/sdks/quickstart/browser). + +## Installation ๐Ÿ’ป +### Adding Dependencies +```dart + flutter_openim_sdk: + git: + url: https: //github.com/OpenIMSDK/Open-IM-SDK-Flutter.git +``` + +## Usage ๐Ÿš€ + +The following examples demonstrate how to use the SDK. +### Importing the SDK + +```dart +import 'package:flutter_openim_sdk/flutter_openim_sdk.dart'; +``` +### Initialize +``` +final success = await OpenIM.iMManager.initSDK( + platform: 0, // Platform, referring to the IMPlatform class. + apiAddr: "", // SDK's API interface address. + wsAddr: "", // SDK's WebSocket address. + dataDir: "", // Data storage path. For example, you can use getApplicationDocumentsDirectory() to get a path. + objectStorage: 'cos', // Image server (default is 'cos'). + logLevel: 6, // Log level (default value is 6). + listener: OnConnectListener( + onConnectSuccess: () { + // Successfully connected to the server. + }, + onConnecting: () { + // Connecting to the server, suitable for showing a "Connecting" status on the UI. + }, + onConnectFailed: (code, errorMsg) { + // Failed to connect to the server, you can notify the user that the current network connection is not available. + }, + onUserSigExpired: () { + // User's login token (UserSig) has expired, prompting the user to log in again with a new token. + }, + onKickedOffline: () { + // The current user has been kicked offline, and you can prompt the user to log in again with a message like "You have been logged in on another device. Do you want to log in again?" + }, + ), +); + +``` +### Logging In and Listening for Connection Status + +> Note1: You need to [deploy](https://github.com/openimsdk/open-im-server#rocket-quick-start) OpenIM Server first, the default port of OpenIM Server is 10001, 10002. +> Note2: You need to set up the listeners first and then log in. + + +```dart +// Set listener + OpenIM.iMManager + // + ..userManager.setUserListener(OnUserListener( + )) + // Add message listener (remove when not in use) + ..messageManager.setAdvancedMsgListener(OnAdvancedMsgListener( + )) + + // Set up message sending progress listener + ..messageManager.setMsgSendProgressListener(OnMsgSendProgressListener( + )) + ..messageManager.setCustomBusinessListener( + ) + // Set up friend relationship listener + ..friendshipManager.setFriendshipListener(OnFriendshipListener( + )) + + // Set up conversation listener + ..conversationManager.setConversationListener(OnConversationListener( + )) + + // Set up group listener + ..groupManager.setGroupListener(OnGroupListener( + )); + +// Retrieve the profile of the currently logged-in user +final userInfo = await OpenIM.iMManager.login( + userID: "", // userID is obtained from your own business server + token: "", // The token should be acquired by your business server by exchanging with OpenIM server based on a secret key + ); + +``` + +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](https://doc.rentsoft.cn/restapi/userManagement/userRegister) 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. + +```dart +//Send + OpenIM.iMManager.messageManager.sendMessage( + message: await OpenIM.iMManager.messageManager.createTextMessage( + text: 'hello openim', + ), + userID: userID + ).catchError((error, _){ + // Message sent successfully โœ‰๏ธ + + } ) + .whenComplete(() { + // Failed to send message โŒ + + }); + +//Receive +OpenIM.iMManager.messageManager.setAdvancedMsgListener(OnAdvancedMsgListener( + onRecvNewMessage:(Message msg) { + // Received new message ๐Ÿ“จ + + } + )) +``` + +## Examples ๐ŸŒŸ + +You can find a demo Flutter app that uses the SDK in the [open-im-flutter-demo](https://github.com/openimsdk/open-im-flutter-demo) repository. + + +## Community :busts_in_silhouette: + +- ๐Ÿ“š [OpenIM Community](https://github.com/OpenIMSDK/community) +- ๐Ÿ’• [OpenIM Interest Group](https://github.com/Openim-sigs) +- ๐Ÿš€ [Join our Slack community](https://join.slack.com/t/openimsdk/shared_invite/zt-22720d66b-o_FvKxMTGXtcnnnHiMqe9Q) +- :eyes: [Join our wechat (ๅพฎไฟก็พค)](https://openim-1253691595.cos.ap-nanjing.myqcloud.com/WechatIMG20.jpeg) + +## Community Meetings :calendar: + +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](https://join.slack.com/t/openimsdk/shared_invite/zt-22720d66b-o_FvKxMTGXtcnnnHiMqe9Q) ๐ŸŽฏ, then you can search the Open-IM-Server pipeline to join + +We take notes of each [biweekly meeting](https://github.com/orgs/OpenIMSDK/discussions/categories/meeting) in [GitHub discussions](https://github.com/openimsdk/open-im-server/discussions/categories/meeting), Our historical meeting notes, as well as replays of the meetings are available at [Google Docs :bookmark_tabs:](https://docs.google.com/document/d/1nx8MDpuG74NASx081JcCpxPgDITNTpIIos0DS6Vr9GU/edit?usp=sharing). + +## Who are using OpenIM :eyes: + +Check out our [user case studies](https://github.com/OpenIMSDK/community/blob/main/ADOPTERS.md) page for a list of the project users. Don't hesitate to leave a [๐Ÿ“comment](https://github.com/openimsdk/open-im-server/issues/379) and share your use case. + +## License :page_facing_up: + +OpenIM is licensed under the Apache 2.0 license. See [LICENSE](https://github.com/openimsdk/open-im-server/tree/main/LICENSE) for the full license text.