AIMPaaS作为一个PaaS产品,不提供账号体系,便于对接业务方现有的账号体系。本文介绍AIMSDK账号集成与登录功能的实现方法。

前提条件

AIMSDK登录前,需要App已完成登录,用户通过DPSPubManager获取DPSAuthService来完成登录操作。

登录状态

调用DPSAuthService::Login开始登录。AIMSDK分两种登录方式:本地登录和网络登录。

  • 本地登录

    在一次登录成功后,如果没有执行退出登录的操作,在Token过期时间失效之前,客户端处于本地登录(免登)状态,结束进程重启也同样处于免登状态。

    调用DPSAuthService::Login接口,AIMSDK会立刻回调onLocalLogin接口,用于回调通知本地登录事件。免登状态可以通过DPSAuthService::IsLocalLogin接口的查询。

  • 网络登录

    调用DPSAuthService::Login开始登录后,AIMSDK都会向IM服务端发起网络登录请求,与本地登录的区别在于是否需要重新回调客户端Token请求回调。网络登录的结果是通过异步回调onConnectionStatusChanged接口给客户端,客户端可以根据网络登录状态做出相应动作。

    建议您使用AIMAuthService::isLocalLoginonLocalLogin用于判断用户是否完成本地登录。

    注意

    本地如果没有Token或者Token过期时,AIMSDK通过客户端得到登录Token且网络登录成功后,会回调一次onLocalLogin事件,可以理解为调用DPSAuthService::Login接口。正常情况下必定会调用onLocalLogin事件。

    创建会话、发送消息等涉及网络交互的接口必须要在鉴权成功(CS_AUTHED)后才可以调用。

完成本地登录即可进入客户端界面。等待网络登录成功事件onConnectionStatusChanged后,开启客户端界面中需要网络的功能权限,从而提高客户端界面的流畅度。登录流程图如下所示:

免登(本地登录)
登录的示例代码,如下所示:
DPSAuthService service = dpsPubManager.getAuthService();
service.addListener(
    // 需要给DPSAuthService添加Listener监听登录事件
    new DPSAuthListener() {
      @Override
      public void onConnectionStatusChanged(
          DPSConnectionStatus dpsConnectionStatus) {
        // 网络登录状态事件
        // DPSConnectionStatus::CS_UNCONNECTED 网络连接失败
        // DPSConnectionStatus::CS_CONNECTED  网络连接成功
        // DPSConnectionStatus::CS_AUTHING    正在鉴权
        // DPSConnectionStatus::CS_AUTHED  鉴权成功标志
      }

      @Override
      public void onGetAuthCodeFailed(int i, String s) {
        // 登录token获取失败事件
      }

      @Override
      public void onLocalLogin() {
        // 本地登录事件
      }
      @Override
      public void onKickout(String s) {
        // 被踢事件
      }

      @Override
      public void onDeviceStatus(int type, int deviceType, int status,
                                 long time) {
        // 其他端设备在(离)线情况
        // type    事件类型(1:事件通知,包括上下线,2:状态通知,在线状态)
        // deviceType    设备类型
        // (0:default,1:web,2:Android,3:iOS,4:Mac,5:Windows,6:iPad) status
        // 设备状态(1:上线或在线,2:下线或离线) time
        // 时间(上线或下线时间)
      }

      @Override
      public void onMainServerCookieRefresh(String s) {
        // 下载资源cookie变更事件
        // 向服务器下载图片、音频等资源时,需要携带的cookie信息
      }
    });
service.login();

离线使用

AIMSDK支持在不登录的情况下,即不调用DPSAuthService::Login,也可以调用部分接口(拉取本地会话、消息等)。

自动重试

开发者无需实现重试登录的逻辑,AIMSDK因网络断线等原因造成登录失败,会自动重试。重试策略包括网络状态变化、应用前后台切换、定时重试等。

自动重试引起的网络状态变化会通过DPSAuthListener::onConnectionStatusChanged回调通知客户端。

退出登录

调用DPSAuthService::Logout退出登录状态。

  1. 一般来说,退出登录后,应该退出IM界面。
  2. 再次进入IM界面需要重新进行登录。
  3. 退出登录后,免登(本地登录)状态会清除,不再重试登录。
  4. 退出登录返回后,应该立即退出IM界面。

强制下线

已登录的账户可能会被服务端强制下线。被强制下线会收到DPSAuthListener::onKickout回调通知,开发者不需要在回调里调用Logout接口(AIMSDK内部已经做过处理)。onKickout的参数包含了被踢的原因的message。

被服务端强制下线,应该立即退出IM界面。目前AIMSDK不提供强制下线接口,由业务方实现。业务方接入时,特别是多用户情况下,要注意对应的Manager。

Token定义与规范

  • Token定义

    AuthToken用于用户鉴权,接入方了解基本概念,根据App服务端给定的token URL,对DPSEnginesettingService作相应URL配置即可,平时无需主动获取AuthToken。

    AuthToken包含:accessToken与refreshToken两部分。accessToken有效期24h,当accessToken过期时,使用refreshToken去置换一个新的renewed accessToken。

    说明 这里的设计有安全性的考量,业务开发了解即可。

    AIMSDK获取AuthToken的时机不固定,可能是刚启动的时候,也可能是运行过程中。主动调用GetLoginToken接口会导致上一个AuthToken失效,建议App不要主动获取AuthToken(DPSSDK回调的时候会去服务端获取AuthToken),也不要缓存AuthToken。获取AuthToken前后需添加日志,方便排查问题。

  • 获取AuthToken流程
    DPSSDK在必要的时候,会向App发出请求,回调App的接口(接口在初始化的时候通过DPSSettingService::SetAuthTokenCallback设置进来),App需要对此回调接口进行响应,向AppServer请求AuthToken,AppServer通过AIMPaaS的getLoginToken接口获取AuthToken,然后返回给AIMSDK,AIMSDK拿到这个Token去AIMPaaS登录。获取AuthToken流程
    1. AIMSDK调用业务方配置的SetAuthTokenCallback向App发出鉴权请求。
    2. App与业务方服务端App Server进行通信,请求AuthToken。
    3. App Server根据对应uid向AIMPaaS请求AuthToken。
    4. AIMPaaS向App Server回传AuthToken。
    5. App Server将请求到的AuthToken回传App。
    6. App将AuthToken传递到AIMSDK,AIMSDK配置到DPSEnginesettingService中。
    7. AIMSDK拿新的AuthToken通过长连接去AIMPaaS登录。
    说明 AuthToken有相应的时效,因此绝大多数情况并不需要这样的请求过程,AIMSDK在AuthToken有效的情况下,会直接通过长连接去AIMPaaS登录。

    此外,上述的过程并不需要于接入方用户主动调用,建议不要主动获取AuthToken,也不要缓存AuthToken。