集成 SDK 基础功能


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

SDK 中,大部分与网络有关的操作,都提供了3种调用方法:

  • 同步方法
  • 通过 delegate 回调的异步方法。要想能收到回调,必须要注册委托
    <IChatManagerDelegate>

    实现注册

    [[EaseMob sharedInstance].chatManager addDelegate:self delegateQueue:nil];

    不用时需要移除,执行

    [[EaseMob sharedInstance].chatManager removeDelegate:self];
  • block 异步方法(推荐使用)

引入相关头文件 #import”EaseMob.h”(不需要实时语音功能)或者 #import”EMSDKFull.h”

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

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
	//registerSDKWithAppKey: 注册的AppKey,详细见下面注释。
	//apnsCertName: 推送证书名(不需要加后缀),详细见下面注释。
    [[EaseMob sharedInstance] registerSDKWithAppKey:@"douser#istore" apnsCertName:@"istore_dev"];
    [[EaseMob sharedInstance] application:application didFinishLaunchingWithOptions:launchOptions];
    return YES;
}

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

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

// 申请处理时间
- (void)applicationWillTerminate:(UIApplication *)application
{
    [[EaseMob sharedInstance] applicationWillTerminate:application];
}

调用的 SDK 接口 [registerSDKWithAppKey:apnsCertName:] 参数解释如下:

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

注册模式分两种,开放注册和授权注册。只有开放注册时,才可以客户端注册。

  • 开放注册是为了测试使用,正式环境中不推荐使用该方式注册环信账号;
  • 授权注册的流程应该是您服务器通过环信提供的 REST API 注册,之后保存到您的服务器或返回给客户端。

注册提供了三种方法。

同步方法

EMError *error = nil;
BOOL isSuccess = [[EaseMob sharedInstance].chatManager registerNewAccount:@"8001" password:@"111111" error:&error];
if (isSuccess) {
    NSLog(@"注册成功");
}

block 异步方法

[[EaseMob sharedInstance].chatManager asyncRegisterNewAccount:@"8001" password:@"111111" withCompletion:^(NSString *username, NSString *password, EMError *error) {
    if (!error) {
        NSLog(@"注册成功");
    }
} onQueue:nil];

IChatManagerDelegate 回调方法

接口调用:

[[EaseMob sharedInstance].chatManager asyncRegisterNewAccount:@"8001" password:@"111111"];

监听回调方法:

/*!
 @method
 @brief 注册新用户后的回调
 @discussion
 @result
 */
- (void)didRegisterNewAccount:(NSString *)username 
					 password:(NSString *)password
					    error:(EMError *)error;

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

提供了三种方法。

同步方法

EMError *error = nil;
NSDictionary *loginInfo = [[EaseMob sharedInstance].chatManager loginWithUsername:@"8001" password:@"111111" error:&error];
if (!error && loginInfo) {
    NSLog(@"登录成功");
}

block 异步方法

[[EaseMob sharedInstance].chatManager asyncLoginWithUsername:@"8001" password:@"111111" completion:^(NSDictionary *loginInfo, EMError *error) {
    if (!error && loginInfo) {
        NSLog(@"登录成功");
    }
} onQueue:nil];

IChatManagerDelegate 回调方法

接口调用:

[[EaseMob sharedInstance].chatManager asyncLoginWithUsername:@"8001" password:@"111111"];

监听回调方法:

/*!
 @method
 @brief 用户登录后的回调
 @discussion
 @param loginInfo 登录的用户信息
 @param error     错误信息
 @result
 */
- (void)didLoginWithInfo:(NSDictionary *)loginInfo error:(EMError *)error;

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

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

[[EaseMob sharedInstance].chatManager asyncLoginWithUsername:@"8001" password:@"111111" completion:^(NSDictionary *loginInfo, EMError *error) {
        if (!error) {
            // 设置自动登录
            [[EaseMob sharedInstance].chatManager setIsAutoLoginEnabled:YES];
        }
    } onQueue:nil];

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

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

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

BOOL isAutoLogin = [[EaseMob sharedInstance].chatManager isAutoLoginEnabled];
if (!isAutoLogin) {
	[[EaseMob sharedInstance].chatManager asyncLoginWithUsername:@"8001" 
														password:@"111111" 
													  completion:^(NSDictionary *loginInfo, EMError *error) {
	} onQueue:nil];
}

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

/*!
 @method
 @brief 用户将要进行自动登录操作的回调
 @discussion
 @param loginInfo 登录的用户信息
 @param error     错误信息
 @result
 */
- (void)willAutoLoginWithInfo:(NSDictionary *)loginInfo error:(EMError *)error;

/*!
 @method
 @brief 用户自动登录完成后的回调
 @discussion
 @param loginInfo 登录的用户信息
 @param error     错误信息
 @result
 */
- (void)didAutoLoginWithInfo:(NSDictionary *)loginInfo error:(EMError *)error;

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

/*!
 @method
 @brief 将要发起自动重连操作时发送该回调
 @discussion
 @result
 */
- (void)willAutoReconnect;

/*!
 @method
 @brief 自动重连操作完成后的回调(成功的话,error为nil,失败的话,查看error的错误信息)
 @discussion
 @result
 */
- (void)didAutoReconnectFinishedWithError:(NSError *)error;

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

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

退出登录提供了三种方法。

logoffWithUnbindDeviceToken:是否解除 device token 的绑定,在被动退出时传 NO,在主动退出时传 YES。

同步方法

EMError *error = nil;
NSDictionary *info = [[EaseMob sharedInstance].chatManager logoffWithUnbindDeviceToken:YES/NO error:&error];
if (!error) {
    NSLog(@"退出成功");
}

block 异步方法

[[EaseMob sharedInstance].chatManager asyncLogoffWithUnbindDeviceToken:YES/NO completion:^(NSDictionary *info, EMError *error) {
    if (!error) {
        NSLog(@"退出成功");
    }
} onQueue:nil];

IChatManagerDelegate 回调方法

接口调用:

// 退出,传入YES,会解除device token绑定,不再收到群消息;传NO,不解除device token
[[EaseMob sharedInstance].chatManager asyncLogoffWithUnbindDeviceToken:YES/NO];

回调方法监听:

/*!
 @method
 @brief 用户注销后的回调
 @discussion
 @param error        错误信息
 @result
 */
- (void)didLogoffWithError:(EMError *)error;

回调方法监听:

/*!
 @method
 @brief 当前登录账号在其它设备登录时的通知回调
 @discussion
 @result
 */
- (void)didLoginFromOtherDevice;

上一页:集成 iOS SDK

下一页:消息