集成 SDK 基础功能


在您阅读此文档时,我们假定您已经具备了基础的 iOS 应用开发经验,并能够理解相关基础概念。

SDK 同步/异步方法区分

SDK 中,大部分与网络有关的操作,提供的是同步方法(注:同步方法会阻塞主线程,需要用户自己创建异步线程执行;带有 async 的方法为异步方法。)

初始化 SDK

第 1 步:引入相关头文件 #import <HyphenateLite/EMSDK.h>。

第 2 步:在工程的 AppDelegate 中的以下方法中,调用 SDK 对应方法。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //AppKey:注册的AppKey,详细见下面注释。
    //apnsCertName:推送证书名(不需要加后缀),详细见下面注释。
    EMOptions *options = [EMOptions optionsWithAppkey:@"douser#istore"];
    options.apnsCertName = @"istore_dev";
    [[EMClient sharedClient] initializeSDKWithOptions:options];

    return YES;
}

// APP进入后台
- (void)applicationDidEnterBackground:(UIApplication *)application
{
    [[EMClient sharedClient] applicationDidEnterBackground:application];
}

// APP将要从后台返回
- (void)applicationWillEnterForeground:(UIApplication *)application
{
    [[EMClient sharedClient] applicationWillEnterForeground:application];
}

调用的 SDK 接口参数解释如下:

环信为 IM 部分提供了 APNS 推送功能,如果您要使用,请跳转到APNS离线推送

注册

注册模式分两种,开放注册和授权注册。

  • 只有开放注册时,才可以客户端注册。开放注册是为了测试使用,正式环境中不推荐使用该方式注册环信账号。
  • 授权注册的流程应该是您服务器通过环信提供的 REST API 注册,之后保存到您的服务器或返回给客户端。
EMError *error = [[EMClient sharedClient] registerWithUsername:@"8001" password:@"111111"];
if (error==nil) {
    NSLog(@"注册成功");
}

登录

登录:调用 SDK 的登录接口进行的操作。

EMError *error = [[EMClient sharedClient] loginWithUsername:@"8001" password:@"111111"];
if (!error) {
    NSLog(@"登录成功");
}

自动登录

自动登录:即首次登录成功后,不需要再次调用登录方法,在下次 APP 启动时,SDK 会自动为您登录。并且如果您自动登录失败,也可以读取到之前的会话信息。

SDK 中自动登录属性默认是关闭的,需要您在登录成功后设置,以便您在下次 APP 启动时不需要再次调用环信登录,并且能在没有网的情况下得到会话列表。

EMError *error = [[EMClient sharedClient] loginWithUsername:@"8001" password:@"111111"];
if (!error)
{
   [[EMClient sharedClient].options setIsAutoLogin:YES];
}

自动登录在以下几种情况下会被取消:

  • 用户调用了 SDK 的登出动作;
  • 用户在别的设备上更改了密码,导致此设备上自动登录失败;
  • 用户的账号被从服务器端删除;
  • 用户从另一个设备登录,把当前设备上登录的用户踢出。

所以,在您调用登录方法前,应该先判断是否设置了自动登录,如果设置了,则不需要您再调用。

BOOL isAutoLogin = [EMClient sharedClient].options.isAutoLogin;
if (!isAutoLogin) {
    EMError *error = [[EMClient sharedClient] loginWithUsername:@"8001" password:@"111111"];
}

SDK 中,如果发生自动登录,会有以下回调:

/*!
 *  自动登录返回结果
 *
 *  @param aError 错误信息
 */
- (void)didAutoLoginWithError:(EMError *)aError

//添加回调监听代理: [[EMClient sharedClient] addDelegate:self delegateQueue:nil];

重连

当掉线时,iOS SDK 会自动重连,只需要监听重连相关的回调,无需进行任何操作。

/*!
 *  SDK连接服务器的状态变化时会接收到该回调
 *
 *  有以下几种情况,会引起该方法的调用:
 *  1. 登录成功后,手机无法上网时,会调用该回调
 *  2. 登录成功后,网络状态变化时,会调用该回调
 *
 *  @param aConnectionState 当前状态
 */
- (void)didConnectionStateChanged:(EMConnectionState)aConnectionState;

退出登录

退出登录分两种类型:主动退出登录和被动退出登录。

  • 主动退出登录:调用 SDK 的退出接口;
  • 被动退出登录:1. 正在登录的账号在另一台设备上登录;2. 正在登录的账号被从服务器端删除。

logout:YES:是否解除 device token 的绑定,在被动退出时 SDK 内部处理,不需要调用退出方法。

EMError *error = [[EMClient sharedClient] logout:YES];
if (!error) {
     NSLog(@"退出成功");
}

被动退出登录

使用回调方法监听被动退出登录。

/*!
 *  当前登录账号在其它设备登录时会接收到该回调
 */
- (void)didLoginFromOtherDevice;

/*!
 *  当前登录账号已经被从服务器端删除时会收到该回调
 */
- (void)didRemovedFromServer;