====== VEC iOS SDK集成 ====== 环信客服云(Customer Engagement Cloud, CEC)现已推出专属 iOS SDK!您只需在客服云创建 APP 关联,并按照本文档的步骤集成 iOS SDK,即可轻松实现 iOS 版 APP 接入。 ===== SDK介绍 ===== **iOS SDK 支持以下功能:** * 发送文本消息、语音消息、图片消息、位置消息、视频消息。 * 接收文本消息、语音消息、图片消息、位置消息、视频消息、文件消息、机器人菜单等。 * 显示客服头像和昵称、显示机器人转人工按钮。 * 发送消息附带访客信息,指定客服、指定技能组(参考[[#第4步_集成更多业务功能|第4步:集成更多业务功能]])。 * 支持留言功能,包括文字、图片和语音留言(参考[[#第5步_集成更多扩展功能|第5步:集成更多扩展功能]])。 **客户端与服务端连接方式:** 客户端与服务端的连接方式包含[[cs:300visitoraccess:persistent-connection|长连接(永久)和长连接(24小时)]]。长连接(永久)包含Socket通道,能够保证客户端无论是否在线,都能够收到消息和通知;长连接(24小时)是仅有24小时时效的长连接,同样包含Socket通道,在时效内与长连接拥有相同的通信能力。 环信客服云默认采用“长连接(24小时)”方式与Android/iOS客户端对接。“长连接(永久)”方式为增值服务,如需开通,请联系环信商务经理。 **如果您是im和客服一起使用,也需要联系环信商务经理进行开通。** ===== 集成方式 ===== CEC iOS SDK已集成双通道功能,确保不丢消息;并提供会话相关内置UI,集成客服云通用功能,只需5分钟。如果您使用内置UI,请参考本文档集成;如果您不使用环信提供的内置UI,请参考:[[cs:300visitoraccess:iossdk-customui|CEC iOS SDK集成(自定义UI)]] ===== 第1步:创建APP关联 ===== 客服云的“APP关联”对应即时通讯云(IM)后台的应用。在客服云创建关联后,可直接登录IM后台管理该关联对应的应用。 * 如果您还没有环信即时通讯云的账号,可以打开[[http://kefu.easemob.com/mo/login|环信客服云]],进入“管理员模式 > 渠道管理 > 手机APP”,快速创建一个“APP关联”; * 如果您已有环信即时通讯云的账号并创建了应用,可以打开[[http://kefu.easemob.com/mo/login|环信客服云]](并使用客服云账号登录),进入“管理员模式 > 渠道管理 > 手机APP”,关联您的IM账号。 关于创建APP关联的分步骤演示,请参考:[[cs:300visitoraccess:createappchannel|创建APP关联]]。 ===== 第2步:环境准备 ===== 开发工具:Xcode。 === 客服SDK 下载 === 集成CEC iOS SDK时,可参考“商城”demo源码和HelpDeskUI源码。 首先要下载环信提供的客服SDK,下载地址:[[http://www.easemob.com/download/cs]](下载"iOS客服访客端SDK") === 客服SDK 介绍 === 下载的客服SDK目录包括HelpDesk、Hyphenate、kefu-ios-demo 三个文件夹: * **HelpDesk** 访客端sdk,HelpDesk.framework * ** HyphenateChat** 访客sdk的依赖库,HyphenateChat.framework(版本号: 3.8.9.1,不包含实时音视频 如需要音视频需要集成声网sdk )使用时可以根据实际需求自行选择,使用时要与HelpSDK目录中的sdk配对使用。 * **kefu-ios-demo** 访客端demo,下载后可直接双击CustomerSystem-ios.xcworkspace运行。 ===== 第3步:集成基础功能 ===== 完成该步骤可以实现用户注册、登录、退出,向客服云系统发送文本、语音、图片、文件消息功能。 ==== 准备工作 ==== 1、在工程中导入 HelpDesk.framework、HyphenateChat.framework文件,两种方式 * 将上述文件夹拖入工程,在弹出对话框中勾选“Copy items if needed”和“Create groups”,并点击“Finish”; * 或者,选择“File > Add Files to”,从本地选择上述文件夹,点击“Options”,勾选“Copy items if needed”和“Create groups”,并点击“Add”。 2、选中当前的TARGET,向 General → Frameworks,Libraries,and Embedded Binaries 中添加依赖库。要将'Do Not Embed'改成'Embed & Sign'。 {{:cs:300visitoraccess:文件名称.jpg?nolink&800|}} 3、在工程info.plist文件中,增加隐私权限: * Privacy - Photo Library Usage Description 需要访问您的相册 * Privacy - Microphone Usage Description 需要访问您的麦克风 * Privacy - Camera Usage Description 需要访问您的摄像机 4、将HelpDeskUI目录拖入到您的工程中; 5、在pch文件或全局.h文件中添加如下代码: #ifdef __OBJC__ #import "HelpDeskUI/HelpDeskUI.h" 注: * 如果工程中没有pch文件,需要新建一个,并在Build Settings中设置Prefix Header为该pch文件,例如:HelloiOS/PrefixHeader.pch。 * HelpDeskUI是环信提供的一个ui库,在kefu-ios-demo/CustomerSystem-ios/HelpDeskUI路径中,集成环信HelpDeskUI的时候,由于HelpDeskUI内部使用了第三方库,如果与开发者第三方库产生冲突,可将HelpDeskUI中冲突的第三方库删除,如果第三方库中的接口有升级的部分,请酌情进行升级。 ==== 初始化 ==== 在 ''AppDelegate.m'' 文件的系统回调 ''didFinishLaunchingWithOptions'' 中,调用初始化接口。 HDOptions *option = [[HDOptions alloc] init]; option.appkey = @"Your appkey"; // 必填项,appkey获取地址:kefu.easemob.com,“管理员模式 > 渠道管理 > 手机APP”页面的关联的“AppKey” option.tenantId = @"Your tenantId";// 必填项,tenantId获取地址:kefu.easemob.com,“管理员模式 > 账户 > 账户信息 > 租户ID一栏的数据” //推送证书名字 option.apnsCertName = @"your apnsCerName";//(集成离线推送必填) //Kefu SDK 初始化,初始化失败后将不能使用Kefu SDK HDError *initError = [[HDClient sharedClient] initializeSDKWithOptions:option]; if (initError) { // 初始化错误 } 注:私有部署场景下,需要在初始化方法中额外配置服务器IP地址和端口,请参考:[[cs:300visitoraccess:private-server|访客端SDK私有部署集成]] ==== APNs离线推送 ==== 推送证书制作和上传,请参考[http://docs-im.easemob.com/im/ios/apns/deploy] {{:cs:300visitoraccess:easemobapp.jpg?600|}} 您可以直接从渠道管理中对应的app直接进入对应的im关联后台。 //注册APNs推送 [application registerForRemoteNotifications]; UIUserNotificationType notificationTypes = UIUserNotificationTypeBadge | UIUserNotificationTypeSound | UIUserNotificationTypeAlert; UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:notificationTypes categories:nil]; [application registerUserNotificationSettings:settings]; 您注册了推送功能,iOS 会自动回调以下方法,得到 deviceToken,您需要将 deviceToken 传给 SDK。 // 将得到的deviceToken传给SDK - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{ [[HDClient sharedClient] bindDeviceToken:deviceToken]; } // 注册deviceToken失败 - (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error{ NSLog(@"error -- %@",error); } ** APNs注册失败,一般是由于使用了通用证书或者是模拟器调试导致,请检查证书并用真机调试。此处是 iOS 系统报的错,如仍不能确定,请从网上查找相关资料。** ==== 注册 ==== 注册建议在服务端创建,而不要放到APP中,可以在登录自己APP时从返回的结果中获取环信账号再登录环信服务器。 HDError *error = [[HDClient sharedClient] registerWithUsername:@"username" password:@"password"]; error.code: HDErrorNetworkUnavailable 网络不可用 HDErrorUserAlreadyExist 用户已存在 HDErrorUserAuthenticationFailed 无开放注册权限(后台管理界面设置[开放|授权]) HDErrorUserIllegalArgument 用户名非法 ==== 登录 ==== 由于HDClient有一个isLoggedInBefore(BOOL),登录操作前可以先做个判断。 HDClient *client = [HDClient sharedClient]; if (client.isLoggedInBefore != YES) { HDError *error = [client loginWithUsername:@"username" password:@"password"]; if (!error) { //登录成功 } else { //登录失败 return; } } // 进入会话页面 HDMessageViewController *chatVC = [[HDMessageViewController alloc] initWithConversationChatter:@"IM 服务号"]; // 获取地址:kefu.easemob.com,“管理员模式 > 渠道管理 > 手机APP”页面的关联的“IM服务号” [self.navigationController pushViewController:chatVC animated:YES]; ==== 退出 ==== 登出后则无法收到客服发来的消息。 //参数为是否解绑推送的devicetoken HDError *error = [[HDClient sharedClient] logout:YES]; if (error) { //登出出错 } else {//登出成功 } ==== 获取会话 ==== **注意:** ServiceIMNumber(IM服务号)由于服务器忽略大小写,IM服务号必须是小写,**在配置界面的IM服务号请使用小写**。 //获取一个会话 HDConversation *conversation = [[HDClient sharedClient].chatManager getConversation:@"IM 服务号"]; //获取地址:kefu.easemob.com,“管理员模式 > 渠道管理 > 手机APP”页面的关联的“IM服务号” ==== 判断登录状态 ==== if([HDClient sharedClient].isLoggedInBefore) { //已经登录 }else{ //未登录 } ==== 添加网络监听 ==== 添加网络监听,可以显示当前是否连接服务器。 //添加网络监控,一般在app初始化的时候添加监控,第二个参数是执行代理方法的队列,默认是主队列 [[HDClient sharedClient] addDelegate:self delegateQueue:nil]; //移除网络监控 [[HDClient sharedClient] removeDelegate:self]; /* 有以下几种情况, 会引起该方法的调用: * 1. 登录成功后, 手机无法上网时, 会调用该回调 * 2. 登录成功后, 网络状态变化时, 会调用该回调*/ - (void)connectionStateDidChange:(HConnectionState)aConnectionState { switch (aConnectionState) { case HConnectionConnected: {//已连接 break; } case HConnectionDisconnected: {//未连接 break; } default: break; } } // 当前登录账号已经被从服务器端删除时会收到该回调 - (void)userAccountDidRemoveFromServer { } //当前登录账号在其它设备登录时会接收到此回调 - (void)userAccountDidLoginFromOtherDevice { } ==== 添加消息监听 ==== //添加消息监控,第二个参数是执行代理方法的队列,默认是主队列 [[HDClient sharedClient].chatManager addDelegate:self delegateQueue:nil]; //移除消息监控 [[HDClient sharedClient].chatManager removeDelegate:self]; - (void)messagesDidReceive:(NSArray *)aMessages{ //收到普通消息,格式: } - (void)cmdMessagesDidReceive:(NSArray *)aCmdMessages{ //收到命令消息,格式:,命令消息不存数据库,一般用来作为系统通知,例如留言评论更新, //会话被客服接入,被转接,被关闭提醒 } - (void)messageStatusDidChange:(HDMessage *)aMessage error:(HDError *)aError{ //消息的状态修改,一般可以用来刷新列表,显示最新的状态 } - (void)messageAttachmentStatusDidChange:(HDMessage *)aMessage error:(HDError *)aError{ //发送消息后,会调用,可以在此刷新列表,显示最新的消息 } ====上传AppStore以及打包ipa注意事项 ==== 为了方便广大开发者开发测试,Demo中提供的framework文件支持x86_64 i386 armv7 arm64平台,上传AppStore(xcode10打包ipa)时需要剔除不需要的CPU架构支持,只剩余armv7、arm64 平台即可,命令如下: 包含实时音视频版本HelpDesk.framework 【首先进入HelpDesk.framework所在目录】 // 移除支持x86_64,i386的二进制文件 lipo HelpDesk.framework/HelpDesk -remove x86_64 -remove i386 -output HelpDesk //替换framwork内部二进制文件[记得备份] mv HelpDesk HelpDesk.framework/HelpDesk //查看剥离后的二进制文件支持的CPU架构,如果显示armv7 arm64,就完成剥离,可上传AppStore lipo -info HelpDesk.framework/HelpDesk 依赖库Hyphenate.framework 【首先进入Hyphenate.framework所在目录】 // 移除支持x86_64,i386的二进制文件 lipo Hyphenate.framework/Hyphenate -remove x86_64 -remove i386 -output Hyphenate //替换framwork内部二进制文件[记得备份] mv Hyphenate Hyphenate.framework/Hyphenate //查看剥离后的二进制文件支持的CPU架构,如果显示armv7 arm64,就完成剥离,可上传AppStore lipo -info Hyphenate.framework/Hyphenate 不包含实时音视频版本HelpDeskLite.framework 【首先进入HelpDeskLite.framework所在目录】 // 移除支持x86_64,i386的二进制文件 lipo HelpDeskLite.framework/HelpDeskLite -remove x86_64 -remove i386 -output HelpDeskLite //替换framwork内部二进制文件[记得备份] mv HelpDeskLite HelpDeskLite.framework/HelpDeskLite //查看剥离后的二进制文件支持的CPU架构,如果显示armv7 arm64,就完成剥离,可上传AppStore lipo -info HelpDeskLite.framework/HelpDeskLite 依赖库HyphenateLite.framework 【首先进入HyphenateLite.framework所在目录】 // 移除支持x86_64,i386的二进制文件 lipo HyphenateLite.framework/HyphenateLite -remove x86_64 -remove i386 -output HyphenateLite //替换framwork内部二进制文件[记得备份] mv HyphenateLite HyphenateLite.framework/HyphenateLite //查看剥离后的二进制文件支持的CPU架构,如果显示armv7 arm64,就完成剥离,可上传AppStore lipo -info HyphenateLite.framework/HyphenateLite ===== 第4步:集成更多业务功能 ===== 完成该步骤可以实现将用户资料传递到客服云,将用户发起的会话直接分配给客服或技能组。 ==== 传访客属性 ==== 传访客属性到客服云,访客属性将显示在“会话”页面的“资料”页签。 管理员模式 >设置 > 功能设置 >允许访客端修改客户信息 要打开,nickName不能为空。 //属性可以缺省 HDVisitorInfo *visitor = [[HDVisitorInfo alloc] init]; visitor.name = @"小明儿"; visitor.qq = @"12345678"; visitor.phone = @"13636362637"; visitor.companyName = @"环信"; visitor.nickName = @"风口上的猪";//不可为空 visitor.email = @"abv@126.com"; visitor.desc = @"环信客服云"; HDMessage *message = [....];//构造相关消息 [message addContent:visitor]; //传访客的属性 ==== 指定某个客服 ==== 当用户点击“联系客服”按钮时,发起的会话直接分配给指定的客服。 客服账号为客服的登录邮箱地址。 HDMessage *message = [....];//构造文字消息 [message addContent:[[HDAgentIdentityInfo alloc] initWithValue:@"客服账号"]]; ==== 指定某个技能组 ==== 当用户点击“联系客服”按钮时,发起的会话直接分配给指定的技能组。 技能组名称须和客服系统设置的技能组名称完全一致,中英文均可。 HDMessage *message = [....];//构造文字消息 [message addContent:[[HDQueueIdentityInfo alloc] initWithValue:@"技能组名称"]]; ==== 开启第二通道获取消息 ==== 第二通道是保证消息投递的第二道保障,即使长连接失效后也会通过轮训的方式获取到最新消息数据。 1、第二通道开启方式: [[HDClient sharedClient].chatManager bindChatWithConversationId:<#会话id#>]; ==== 剔除实时音视频 ==== "商城"Demo包含实时音视频功能,如果不需要实时音视频,可以自行剔除,操作步骤:\\ 1、将HelpDesk.framework从项目中移除。\\ 2、导入HelpDeskLite.framework。\\ 3、在pch文件中 将 #ifdef __OBJC__ #import #import "HelpDeskUI.h" #endif 替换为 #ifdef __OBJC__ #import #import "HelpDeskUI.h" #endif 更多实时音视频API请参考[[cs:300visitoraccess:iossdkapi|CEC iOS SDK API]]。 ===== 第5步:集成更多扩展功能 ===== 更多扩展功能(发送轨迹消息、发送订单消息、留言相关功能等),请参考[[cs:300visitoraccess:iossdkapi|CEC iOS SDK API]]。 ===== SDK更新日志 ===== 版本更新信息请查看更新日志。 [[cs:releasenote:iossdk|iOS SDK(访客端)更新日志]]