# SDK 集成概述

    介绍 React Native 集成相关内容。

    # 前提条件

    开始前,请注册有效的环信即时通讯 IM 开发者账号和取得 App key,见 环信即时通讯云管理后台 (opens new window)

    # 集成环境

    具体见 开发环境要求

    # 增加隐私权限

    对于 Android 平台:

    1. 找到文件 android/app/src/main/AndroidManifest.xml
    2. SDK 必需要添加的权限如下:
    <!-- access network permissions -->
    <uses-permission android:name="android.permission.INTERNET" />
    <!-- Get carrier information -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <!-- Wake up permission -->
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    

    # SDK 初始化

    初始化是使用 SDK 必要的、执行在所有接口方法调用之前的步骤。如果进行多次初始化操作,只有第一次初始化以及相关的参数生效。初始化的结果通过异步的方式返回。

    初始化示例代码:

    ChatClient.getInstance()
      .init(
        new ChatOptions({
          appKey: "<your app key>",
          autoLogin: false,
          debugModel: true,
        })
      )
      .then(() => {
        console.log("init success");
      })
      .catch((error) => {
        console.log("init fail: ", error);
      });
    

    初始化参数非常多,这里做主要参数介绍。参数聚合在 ChatOptions 类型中。

    • appKey:App 在控制台注册完成之后会生成该参数,这是 App 在系统中的唯一标识。
    • autoLogin:是否自动登录。该参数设置为 true,则在登录成功之后,后续 App 启动之后自动执行登录操作。如果登录失败会返回错误提示。
    • debugModel:是否启用日志输出功能。设置为 true 则会启用日志输出功能,在调试开发阶段帮助定位和分析问题。
    • acceptInvitationAlways:是否自动接受申请。设置为 true 则当有人申请好友时,自动接受申请。
    • autoAcceptGroupInvitation:是否自动接受邀请。设置为 true 则当有人邀请当前用户入群时,自动接受邀请。
    • requireAck:是否需要发送已读回执。设置为 true 则消息需要已读回执。详见 消息回执章节
    • requireDeliveryAck:是否需要发送送达回执。设置为 true 则消息需要送达回执。详见消息回执章节。
    • deleteMessagesAsExitGroup:是否需要在离开群组时自动删除聊天历史消息。设置为 true 则在退出群组的时候,会删除聊天记录。
    • deleteMessagesAsExitChatRoom:是否需要在离开聊天室时自动删除聊天历史消息。设置为 true 则在退出聊天室的时候,会删除记录。
    • isChatRoomOwnerLeaveAllowed:是否允许聊天室所有者离开聊天室。设置为 true 则允许。详见 聊天室 章节。
    • isAutoDownload: 是否开启自动下载。设置为 true 则收到图片、视频、音频、语音消息会自动下载。详见 消息 章节。

    # 注册用户

    目前注册的方式有几种。第一种是通过控制台注册。第二种通过 REST API 接口注册。第三种是调用 SDK 接口注册(该方法需在 控制台 (opens new window) 设置允许 开放注册)。

    # 控制台注册

    控制台的注册请到 这里 (opens new window)

    # REST API 注册

    请参考 注册用户

    # SDK 注册

    ChatClient.getInstance()
      .createAccount(username, password)
      .then((value: any) => {
        console.log("createAccount: success", value);
      })
      .catch((reason: any) => {
        console.log("createAccount: fail", reason);
      });
    

    # 用户登录

    目前登录服务器有两种方式:

    • 用户 ID + 密码
    • 用户 ID + token

    注意

    使用 token 登录时需要处理 token 过期的问题,比如在每次登录时更新 token 等机制。

    # 手动登录

    用户 ID +密码 登录是传统的登录方式。用户名和密码都是你的终端用户自行决定,密码需要符合密码规则要求。

    ChatClient.getInstance()
      .login(username, password, true)
      .then((value: any) => {
        console.log(`login success`, value);
      })
      .catch((reason: any) => {
        console.log(`login fail`, reason);
      });
    

    用户 ID + token 是更加安全的登录方式。token 可以通过调用 REST API 获取。 详见 环信用户 token 的获取

    ChatClient.getInstance()
      .login(username, token, false)
      .then((value: any) => {
        console.log(`login success`, value);
      })
      .catch((reason: any) => {
        console.log(`login fail`, reason);
      });
    

    # 自动登录

    在初始化的时候,可以设置是否自动登录。如果设置为自动登录,则登录成功之后,后续启动初始化的时候会自动登录,登录结果异步返回。

    # 退出登录

    登出也是异步返回。

    ChatClient.getInstance()
      .logout()
      .then(() => {
        console.log(`logout success`);
      })
      .catch((reason: any) => {
        console.log(`logout fail`, reason);
      });
    

    # 连接状态相关

    你需添加 ChatConnectEventListener#onConnected 回调。

    // 监听器建议在初始化完成之后,登录之前设置,这样可以恰当地收到登录通知。
    let listener = new (class s implements ChatConnectEventListener {
      // token即将过期
      onTokenWillExpire(): void {
        console.log("onTokenWillExpire");
      }
      // token已过期
      onTokenDidExpire(): void {
        console.log("onTokenDidExpire");
      }
      onConnected(): void {
        console.log("onConnected");
      }
      onDisconnected(errorCode?: number): void {
        console.log("onDisconnected: ", errorCode);
      }
    })();
    ChatClient.getInstance().removeAllConnectionListener();
    ChatClient.getInstance().addConnectionListener(listener);
    

    # 断网自动重连

    如果由于网络信号弱、切换网络等引起的连接终端,系统会自动尝试重连。重连成功或者失败的结果分别会收到通知 onConnectedonDisconnected

    # 被动退出登录

    对于 onDisconnected 通知,这些 errorCode 需要用户关注,收到这些通知,建议 APP 返回登录界面。

    • USER_LOGIN_ANOTHER_DEVICE=206: 用户已经在其他设备登录
    • USER_REMOVED=207: 用户账户已经被移除
    • USER_BIND_ANOTHER_DEVICE=213: 用户已经绑定其他设备
    • SERVER_SERVING_DISABLED=305: 服务器服务停止
    • USER_LOGIN_TOO_MANY_DEVICES=214: 用户登录设备超出数量限制
    • USER_KICKED_BY_CHANGE_PASSWORD=216: 由于密码变更被踢下线
    • USER_KICKED_BY_OTHER_DEVICE=217: 由于其他设备登录被踢下线
    • USER_DEVICE_CHANGED=220: 和上次设备不同导致下线

    以上参数具体可以参考原生平台对应说明。

    # 输出信息到日志文件

    如果开启日志调试模式,会通过控制台输出日志。debugModel 设置为 true

    chatlog.log(`${ChatClient.TAG}: login: `, userName, "******", isPassword);
    
    更新时间:2023-01-04 19:11:01