快速上手
本教程是为了让新手快速了解融云即时通讯能力库(IMLib)。在本教程中,您可以体验集成 SDK 的基本流程和 IMLib 的基础通信能力。
融云开发者账户
融云开发者账户是使用融云 SDK 产品的必要条件。
在开始之前,请先前往融云官网注册开发者账户。注册后,控制台将自动为您创建一个应用,默认为开发环境应用,使用国内数据中心。请获取该应用的 App Key,在本教程中使用。
App Secret 用于生成数据签名,仅在请求融云服务端 API 接口时使用。本教程中暂不涉及。
如果您已拥有融云开发者账户,您可以直接选择合适的环境,创建应用。
您需要记录上图所示的应用 App Key,在本教程中使用。
应用的 App Key / Secret 是获取连接融云服务器身份凭证的必要条件,请注意不要泄露。
安装 SDK
npm install @rongcloud/react-native-im-wrapper
安装完成后,可导入 IMLib 库。
import { RCIMIWEngine, RCIMIWEngineOptions } from '@rongcloud/react-native-im-wrapper';
初始化
在使用 SDK 所有功能之前,必须先调用此方法初始化 SDK。
初始化时需要传入上文获取的 App Key。引擎配置请参见引擎配置。
let options: RCIMIWEngineOptions = {};
let engine: RCIMIWEngine = RCIMIWEngine.create(appKey, options);
以上提供了一个简化的初始化示例,关于初始化的更多配置请参见初始化。
获取用户 Token
用户 Token 是与用户 ID 对应的身份验证令牌,是应用程序的用户在融云的唯一身份标识。应用客户端在使用融云即时通讯功能前必须与融云建立 IM 连接,连接时必须传入 Token。
在实际业务运行过程中,应用客户端需要通过应用的服务端调用 IM Server API 申请取得 Token。详见 Server API 文档 注册用户。
在本教程中,为了快速体验和测试 SDK,我们将使用控制台「北极星」开发者工具箱,从 API 调试页面调用 获取 Token 接口,获取到 userId 为 1 的用户的 Token。提交后,可在返回正文中取得 Token 字符串。
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"}
建立 IM 连接
-
设置获取连接状态的监听器:
engine.setOnConnectedListener((code: number, userId: string) => {});
code
连接状态码,0 代表连接成功。userId
连接成功的用户 id。
-
使用上方获取的 Token, 模拟 userId 为 1 的用户连接到融云服务器。
engine.connect(token, timeout)
SDK 已实现自动重连机制,请参见连接。
监听消息
实现此功能需要开发者实现消息监听回调。
代码示例
设置消息接收监听器,用于接收所有类型的实时或者离线消息。
message
接收到的消息对象left
当客户端连接成功后,服务端会将所有补偿消息以消息包的形式下发给客户端,最多每 200 条消息为一个消息包,即一个 Package, 客户端接受到消息包后,会逐条解析并通知应用。left 为当前消息包(Package)里还剩余的消息条数offline
消息是否离线消息hasPackage
是否在服务端还存在未下发的消息包
engine.setOnMessageReceivedListener(
(
message: RCIMIWMessage,
left: number,
offline: boolean,
hasPackage: boolean
) => {});
发送消息
let conversationType = RCIMIWConversationType.PRIVATE;
let targetId = 'xxx';
let channelId = 'xxx';
let text = '一条文本消息';
engine.createTextMessage(
conversationType,
targetId,
channelId,
text
)
.then((message: RCIMIWTextMessage) => {
engine.sendMessage(message);
});
监听消息发送结果
// 消息存入数据库的监听
engine.setOnMessageAttachedListener((message: RCIMIWMessage) => {});
// 发送消息的监听
engine.setOnMessageSentListener((code: number, message: RCIMIWMessage) => {});
退出登录
engine.disconnect(receivePush);
引擎销毁
engine.destroy();