这是本文档旧的修订版!
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 发消息测试。
iOS SDK 介绍
环信 SDK 为用户开发 IM 相关的应用提供的一套完善的开发框架。包括以下几个部分:
- SDK_Core: 为核心的消息同步协议实现,完成与服务器之间的信息交换。
- SDK: 是基于核心协议实现的完整的 IM 功能,实现了不同类型消息的收发、会话管理、群组、好友、聊天室等功能。
- UI:见集成 UI
用户可以基于我们提供的 Demo 实现自己的应用,也可以基于 SDK 开发自己应用。
SDK 采用模块化设计,每一模块的功能相对独立和完善,用户可以根据自己的需求选择使用下面的模块:
- EMClient: 是 SDK 的入口,主要完成登录、退出、连接管理等功能。也是获取其他模块的入口。
- EMChatManager: 管理消息的收发,完成会话管理等功能。
- EMContactManager: 负责好友的添加删除,黑名单的管理。
- EMGroupManager: 负责群组的管理,创建、删除群组,管理群组成员等功能。
- EMChatroomManager: 负责聊天室的管理。
注意:如果您是从 SDK2.x 升级到 3.0,可以参考环信 SDK 2.x到3.0升级文档。
集成 SDK
环信 SDK 支持pod 方式导入,手动导入两种方式任选其一即可,下面分别介绍两种导入方式。
Pod 导入SDK
推荐使用 Cocoapods
集成环信 SDK。 Cocoapods 提供了一个简单的依赖管理系统,避免手动导入产生的错误(首先需要确认已经安装了 Cocoapods,如果没有安装过Cocoapods,参考安装使用指南:https://www.cnblogs.com/wangluochong/p/5567082.html)。
sudo gem install cocoapods
pod setup
在 Xcode
项目的根目录下,新建一个空文件,命名为 Podfile
,向此文件添加以下行( Lite 版与 Full 版,根据自己是否需要实时音视频功能二选一添加即可):
#Lite版本(不带实时音视频通话功能)
pod 'HyphenateLite'
#Full版本(带实时音视频通话功能)
pod 'Hyphenate'
在 Podfile
目录下,执行以下指令:
pod install
执行完pod install,打开工程目录,找到.xcworkspace文件运行即可。
手动导入 SDK
- HyphenateFullSDK 开发使用(包含实时通话功能的 SDK)
- HyphenateSDK 开发使用(不包含实时通话功能的 SDK)
开发者最开始集成,如果选择手动导入文件集成的方式,只需要向工程中添HyphenateFullSDK
或者HyphenateSDK
文件就可以,下面会介绍具体的集成方式。
demo 中有两个 SDK 文件夹:
- HyphenateSDK 开发使用(不包含实时语音视频通话功能)
- HyphenateFullSDK 开发使用(包含实时语音视频通话功能)
两个 SDK 除了是否带有实时语音视频通话功能,其他功能都是相同的。
两者中选择一个 SDK 文件夹拖入到工程中,以导入 HyphenateSDK 为例,并勾选截图中标注的三项。
设置工程属性
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
环信的 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 需要您的同意,才能始终访问位置
添加SDK以及UI头文件
建议在 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];
集成动态库上传AppStore
由于 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/