iOS SDK 快速集成

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

注:此文档对之前的文档进行了优化,结构更清晰,帮助您更快的集成环信 iOS SDK,且对UI进行了改版优化。如果您已集成环信 iOS SDK ,并习惯于之前文档的结构,希望再次了解其集成方式,可参考之前的旧文档


注册环信开发者账号并创建后台应用

详细操作步骤见开发者注册及管理后台

Appkey:一个 APP 的唯一标识

IM 用户:一个 appkey 下的唯一标识用户,用来登录环信服务器进行收发消息的用户。 可以在创建好的应用内注册两个 IM 用户(也可以称为环信 id),例如: 账号:user1,密码:123 ; 账号:user2,密码:123,用来通过 SDK 登录环信服务器,收发消息测试。

在环信 Console 后台,点击创建好的应用 → IM 用户 → 创建 IM 用户

建议创建两个 IM 用户,用于后面集成 SDK 之后聊天使用。例如登录 user1 ,在初始化聊天页面时传入 user2 ,user1 给 user2 发消息测试。


环信 SDK 为用户开发 IM 相关的应用提供的一套完善的开发框架。包括以下几个部分:

开发框架

  • SDK_Core: 为核心的消息同步协议实现,完成与服务器之间的信息交换。
  • SDK: 是基于核心协议实现的完整的 IM 功能,实现了不同类型消息的收发、会话管理、群组、好友、聊天室等功能。

用户可以基于我们提供的 Demo 实现自己的应用,也可以基于 SDK 开发自己应用。

SDK 采用模块化设计,每一模块的功能相对独立和完善,用户可以根据自己的需求选择使用下面的模块:

模块化设计

  • EMClient: 是 SDK 的入口,主要完成登录、退出、连接管理等功能。也是获取其他模块的入口。
  • EMChatManager: 管理消息的收发,完成会话管理等功能。
  • EMContactManager: 负责好友的添加删除,黑名单的管理。
  • EMGroupManager: 负责群组的管理,创建、删除群组,管理群组成员等功能。
  • EMChatroomManager: 负责聊天室的管理。

注意:如果您是从 SDK2.x 升级到 3.0,可以参考环信 SDK 2.x到3.0升级文档


环信 SDK 支持pod 方式导入手动导入两种方式任选其一即可,下面分别介绍两种导入方式。

Pod 导入SDK

推荐使用 Cocoapods 集成环信 SDK。 Cocoapods 提供了一个简单的依赖管理系统,避免手动导入产生的错误(首先需要确认已经安装了 Cocoapods )。

sudo gem install cocoapods
pod setup

Xcode 项目的根目录下,新建一个空文件,命名为 Podfile,向此文件添加以下行( Lite 版与 Full 版,根据自己是否需要实时音视频功能二选一添加即可):

#Lite版本(不带实时音视频通话功能)
pod 'HyphenateLite'
#Full版本(带实时音视频通话功能)
pod 'Hyphenate'

Podfile 目录下,执行以下指令:

pod install

手动导入 SDK

下载环信demo

  • HyphenateFullSDK 开发使用(包含实时通话功能的 SDK)
  • HyphenateSDK 开发使用(不包含实时通话功能的 SDK)

开发者最开始集成,如果选择手动导入文件集成的方式,只需要向工程中添HyphenateFullSDK或者HyphenateSDK文件就可以,下面会介绍具体的集成方式。

demo 中有两个 SDK 文件夹:

  • HyphenateSDK 开发使用(不包含实时语音视频通话功能)
  • HyphenateFullSDK 开发使用(包含实时语音视频通话功能)

两个 SDK 除了是否带有实时语音视频通话功能,其他功能都是相同的。

两者中选择一个 SDK 文件夹拖入到工程中,以导入 HyphenateSDK 为例,并勾选截图中标注的三项。

设置工程属性

向 General → Embedded Binaries 中添加依赖库。


Demo 目录介绍

目录 EMiOSDemo —>Class 中的 Demo 目录介绍

  • Account:主要是 demo 的注册,登录
  • AppDelegate:主要是 demo 中初始化环信SDK,注册推送等
  • Call:demo 的语音视频通话功能页面(包含 1v1 实时通话以及多人实时通话的功能)
  • Chat:demo 的聊天功能页面
  • Contact:demo 的好友功能页面
  • Conversation:demo 的会话列表功能页面
  • EMDemoHelper:demo 的单例类,主要是全局监听接收消息,好友,群组,聊天室等相关事件的回调,从而进行对应的处理
  • Group:demo 的群组功能页面
  • Helper:demo 的功能性文件,全局通用的配置
  • Home:demo 的根控制器页面
  • Notification:demo 的好友,群组相关请求通知的页面
  • Settings:demo 的功能设置页面

环信的 UI 模块在 demo 中的该路径下 EMiOSDemo—Class

demo 中有几大 UI 功能模块,在集成时将对应的模块添加到工程中即可。

  • Helper——自定义库和页面,第三方库,全局通用模块
  • Chat——聊天模块
  • Conversation——会话列表模块
  • Call——实时音视频模块(包含 1v1 实时通话以及多人实时通话的功能)
  • Contact——好友列表模块
  • Group——群组模块
  • Chatroom——聊天室模块

在集成时,必须要先向自己的工程中导入 Helper 模块,然后在根据自己的需求导入其他模块。

环信的 UI 模块依赖于以下三方库:

  • Masonry
  • MJRefresh
  • MBProgressHUD
  • SDWebImage
  • SDWebImage/GIF
  • FLAnimatedImage

保证这些三方库在自己的工程中存在。

注意:三方推荐使用 pod 方式导入,手动导入需要修改 info.plist 重复等报错。


在工程info.plist文件中增加隐私权限

用于 Chat 聊天模块中发送图片,语音,视频,位置消息使用,如您的工程中已经添加过请忽略:

  • Privacy - Photo Library Usage Description 需要访问您的相册
  • Privacy - Microphone Usage Description 需要访问您的麦克风
  • Privacy - Camera Usage Description 需要访问您的摄像机
  • Privacy - Location Always Usage Description 需要您的同意,才能在使用期间访问位置
  • Privacy - Location When In Use Usage Description 需要您的同意,才能始终访问位置

建议在 PCH 文件中引入 SDK 以及 UI 的头文件。如果工程中没有 pch 文件,需要新建一个,并在 Build Settings 中设置 Prefix Header 为该 pch 文件,例如:iOS/PrefixHeader.pch

在 pch 文件文件中添加如下代码:

#ifdef __OBJC__
// 包含实时音视频功能 SDK 的头文件
#import <Hyphenate/Hyphenate.h>
// UI 头文件
#import "EMHeaders.h"
#endif

或者

#ifdef __OBJC__
//不包含实时音视频功能 SDK 的头文件
#import <HyphenateLite/HyphenateLite.h>
// UI 头文件
#import "EMHeaders.h"
#endif

如果自己工程中的 pch 文件还引入了其他的头文件,那么所有的头文件都需要放到。

#ifdef __OBJC__

// 存放 pch 文件中所有的头文件

#endif 的内部

初始化 SDK 以及登录环信服务器

初始化 SDK

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

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // appkey替换成自己在环信管理后台注册应用中的appkey
EMOptions *options = [EMOptions optionsWithAppkey:@"appkey"];
// apnsCertName是证书名称,可以先传nil,等后期配置apns推送时在传入证书名称
    options.apnsCertName = nil;
    [[EMClient sharedClient] initializeSDKWithOptions:options];
    return YES;
}

登录环信服务器

// 传入在应用(appkey)下注册的IM用户user1,密码123,用于登录环信服务器
EMError *error = [[EMClient sharedClient] loginWithUsername:@"user1" password:@"123"];
if (!error) {
    NSLog(@"登录成功");
}
  • 如果在集成调试阶段,可以在初始化环信 SDK 完成之后,就调用登录方法。
  • 如果项目上线,建议开发者在登录自己服务器成功之后,再调用环信 SDK 登录方法使用用户绑定的环信id登录环信服务器(开发者给自己用户在自己服务器创建账号的同时,调用环信的 rest 接口在给用户授权注册一个环信 id,一起返回给 app 端,app 端拿到用户的账号密码以及环信 id 密码分别登录自己的服务器以及环信服务器)。

向工程中导入 Chat 文件

// ConversationId接收消息方的环信ID:@"user2"
// type聊天类型:EMConversationTypeChat    单聊类型
// createIfNotExist 如果会话不存在是否创建会话:YES
EMChatViewController *chatController = [[EMChatViewController alloc] initWithConversationId:@"user2" type:EMConversationTypeChat createIfNotExist:YES];

[self.navigationController pushViewController:chatController animated:YES];

有导航的话,可以用 push 方式跳转到聊天页面发消息测试,也就是用登录的 user1 给 user2 发消息,没有导航的话,可以用 present 方式跳转到聊天页面。


向工程中导入 Call 文件

在初始化 SDK 完成之后,在初始化SDK所在的类引入头文件:

#import "DemoCallManager.h"  // 1v1实时通话功能的头文件
#import "DemoConfManager.h"  // 多人实时通话功能的头文件
 添加:
 [DemoCallManager sharedManager];  // 初始化1v1实时通话功能的单例
 [DemoConfManager sharedManager];  // 初始化多人实时通话功能的单例

在聊天页面中下方,点击语音,视频通话图标按钮即可使用。


会话列表

向工程中导入 Conversation 文件

头文件:#import “EMConversationsViewController.h”

初始化页面跳转(导航跳转示例):

EMConversationsViewController *conversationVC = [[EMConversationsViewController alloc] init];
[self.navigationController pushViewController:conversationVC animated:YES];

好友列表

向工程中导入 Contact 文件

头文件:#import “EMContactsViewController.h”

初始化页面跳转(导航跳转示例):

EMContactsViewController *contactVC= [[EMContactsViewController alloc] init];
[self.navigationController pushViewController:contactVC animated:YES];

群组

向工程中导入 Group 文件

头文件:#import “EMGroupsViewController.h”

初始化页面跳转(导航跳转示例):

EMGroupsViewController *groupVC= [[EMContactsViewController alloc] init];
[self.navigationController pushViewController:groupVC animated:YES];

聊天室

向工程中导入 Chatroom 文件

头文件:#import “EMChatroomsViewController.h”

初始化页面跳转(导航跳转示例):

EMChatroomsViewController *chatRoomVC= [[EMChatroomsViewController alloc] init];
[self.navigationController pushViewController:chatRoomVC animated:YES];

由于 iOS 编译的特殊性,为了方便开发者使用,我们将 i386, x86_64, armv7, arm64 几个平台都合并到了一起,所以使用动态库上传 appstore 时需要将 i386 , x86_64 两个平台删除后,才能正常提交审核

在 SDK 当前路径下执行以下命令删除i386, x86_64两个平台
bak 文件是备份目录,上传appstore之后需要替换回 bak 目录下的 SDK
实时音视频版本Hyphenate.framework

mkdir ./bak
cp -r Hyphenate.framework ./bak
lipo Hyphenate.framework/Hyphenate -thin armv7 -output Hyphenate_armv7
lipo Hyphenate.framework/Hyphenate -thin arm64 -output Hyphenate_arm64
lipo -create Hyphenate_armv7 Hyphenate_arm64 -output Hyphenate
mv Hyphenate Hyphenate.framework/

不包含实时音视频版本 HyphenateLite.framework

mkdir ./bak
cp -r HyphenateLite.framework ./bak
lipo HyphenateLite.framework/HyphenateLite -thin armv7 -output HyphenateLite_armv7
lipo HyphenateLite.framework/HyphenateLite -thin arm64 -output HyphenateLite_arm64
lipo -create HyphenateLite_armv7 HyphenateLite_arm64 -output HyphenateLite
mv HyphenateLite HyphenateLite.framework/

下载地址,提取码 ehil

注:此 Demo 为精简版 Demo,但已涵盖了主要功能。如需更全面的功能,请前往下载页