移动客服 iOS SDK 集成


移动客服现已推出专属 iOS SDK!您只需在移动客服系统创建 APP 关联,并按照本文档的步骤集成 iOS SDK,即可轻松实现 iOS 版 APP 接入。

移动客服 iOS SDK 已集成双通道功能,确保不丢消息;并提供会话相关内置 UI,集成移动客服通用功能,只需5分钟。

iOS SDK 支持以下功能:

  • 发送文本消息、语音消息、图片消息。
  • 接收文本消息、语音消息、图片消息、文件消息、机器人菜单等。
  • 显示客服头像和昵称、显示机器人转人工按钮。
  • 发送消息附带访客信息,指定客服、指定技能组(参考第4步:集成更多业务功能)。
  • 支持留言功能,包括文字、图片和语音留言(参考第5步:集成更多扩展功能)。

第1步:创建APP关联

移动客服系统的“APP关联”对应即时通讯云(IM)后台的应用。在移动客服系统创建关联后,可直接登录IM后台管理该关联对应的应用。

  • 如果您还没有环信即时通讯云的账号,可以打开环信移动客服,进入“管理员模式 > 渠道管理 > 手机APP”,快速创建一个“APP关联”;
  • 如果您已有环信即时通讯云的账号并创建了应用,可以打开环信移动客服(并使用移动客服账号登录),进入“管理员模式 > 渠道管理 > 手机APP”,关联您的IM账号。

关于快速创建APP关联的分步骤演示,请参考:快速创建APP关联

第2步:环境准备

开发工具:Xcode。

集成移动客服iOS SDK时,可参考“商城”demo源码和EaseUI源码。

下载地址:https://github.com/easemob/helpdeskdemo-ios

KefuSDK基于IM SDK 3.x,如同时使用环信IM功能(非音视频),需使用此文档中的初始化、登录、登出操作,不需要添加IM的SDK,其IMSDK-API正常使用。

第3步:集成基础功能

完成该步骤可以实现用户注册、登录、退出,向移动客服系统发送文本、语音、图片、文件消息功能。

准备工作

1、在工程中导入 HelpDeskSDK 和 HelpDeskUI 文件夹。两种方式:

  • 选择“File > Add Files to”,从本地选择上述文件夹,点击“Options”,勾选“Create groups”,并点击“Add”;
  • 或者,直接将上述文件夹拖入工程,在弹出对话框中勾选“Create groups”,并点击“Finish”。

2、向Build Settings → Linking → Other Linker Flags 中增加-ObjC.

3、向Build Phases → Link Binary With Libraries 中添加依赖库

  • CoreMedia.framework
  • MobileCoreServices.framework
  • ImageIO.framework
  • AudioToolbox.framework
  • AVFoundation.framework
  • libc++.dylib
  • libz.dylib
  • libstdc++.6.0.9.dylib
  • libsqlite3.dylib
  • (Xcode 7 及以上版本,后缀为tbd)

4、SDK 不支持 bitcode,在 Build Settings → Build Options → Enable Bitcode 中设置 NO。

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

  • Privacy - Photo Library Usage Description 需要访问您的相册
  • Privacy - Microphone Usage Description 需要访问您的麦克风
  • Privacy - Camera Usage Description 需要访问您的摄像机

6、在pch文件或全局.h文件中添加如下代码

#ifdef __OBJC__
 #import "helpdesk_sdk.h"
 #import "HelpDeskUI.h"
 #endif

注:如果工程中没有pch文件,需要新建一个,并在Build Settings中设置Prefix Header为该pch文件,例如:HelloiOS/PrefixHeader.pch。

上传AppStore注意事项

为了方便广大开发者开发测试,Demo中提供的.a文件支持x86_64 armv7 arm64等平台,上传AppStore需要剔除不需要的CPU架构支持,只剩余armv7、arm64 平台即可,命令如下:

// 剥离出支持arm64的.a
lipo ……/libhelpdesk_sdk.a -thin arm64 -output ……/libhelpdesk_sdk_arm64.a 
// 剥离出支持armv7的.a
lipo ……/libhelpdesk_sdk.a -thin armv7 -output ……/libhelpdesk_sdk_armv7.a 
// 合并.a,支持真机 
lipo -create ……/libhelpdesk_sdk_arm64.a  ……/libhelpdesk_sdk_armv7.a -output ……/libhelpdesksdk_appstore.a 
//查看合并后的.a支持的CPU架构,如果显示armv7 arm64,就完成剥离,可上传AppStore
lipo -info ……/libhelpdesksdk_appstore.a  

初始化

AppDelegate.m 文件的系统回调 didFinishLaunchingWithOptions 中,调用初始化接口。

HOptions *option = [[HOptions 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
HError *initError = [[HChatClient sharedClient] initializeSDKWithOptions:option];
if (initError) { // 初始化错误
}

注册

注册建议在服务端创建,而不要放到APP中,可以在登录自己APP时从返回的结果中获取环信账号再登录环信服务器。

HError *error = [[HChatClient sharedClient] registerWithUsername:@"username" password:@"password"];
error.code:
HErrorNetworkUnavailable 网络不可用
HErrorUserAlreadyExist 用户已存在
HErrorUserAuthenticationFailed 无开放注册权限(后台管理界面设置[开放|授权])
HErrorUserIllegalArgument 用户名非法

登录

由于HChatClient有一个isLoggedInBefore(BOOL),登录操作前可以先做个判断。

HChatClient *client = [HChatClient sharedClient];
    if (client.isLoggedInBefore != YES) {
        HError *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
HError *error = [[HChatClient sharedClient] logout:YES];
if (error) { //登出出错
} else {//登出成功
}

获取会话

//获取一个会话
HConversation *conversation = [[HChatClient sharedClient].chat getConversation:@"IM 服务号"]; //获取地址:kefu.easemob.com,“管理员模式 > 渠道管理 > 手机APP”页面的关联的“IM服务号”

判断登录状态

if([HChatClient sharedClient].isLoggedInBefore) {
     //已经登录
}else{
     //未登录
}

添加网络监听

添加网络监听,可以显示当前是否连接服务器。

//添加网络监控,一般在app初始化的时候添加监控,第二个参数是执行代理方法的队列,默认是主队列
[[HChatClient sharedClient] addDelegate:self delegateQueue:nil];
//移除网络监控
[[HChatClient sharedClient] removeDelegate:self];
/* 有以下几种情况, 会引起该方法的调用:
* 1. 登录成功后, 手机无法上网时, 会调用该回调
* 2. 登录成功后, 网络状态变化时, 会调用该回调*/
- (void)connectionStateDidChange:(HConnectionState)aConnectionState {
    switch (aConnectionState) {
        case HConnectionConnected: {//已连接
            break;
        }
        case HConnectionDisconnected: {//未连接
            break;
        }
        default:
            break;
    }
}
// 当前登录账号已经被从服务器端删除时会收到该回调
- (void)userAccountDidRemoveFromServer {
    
}
//当前登录账号在其它设备登录时会接收到此回调
- (void)userAccountDidLoginFromOtherDevice {
    
}

添加消息监听

//添加消息监控,第二个参数是执行代理方法的队列,默认是主队列
[[HChatClient sharedClient].chat addDelegate:self delegateQueue:nil];
//移除消息监控
[[HChatClient sharedClient].chat removeDelegate:self];

- (void)messagesDidReceive:(NSArray *)aMessages{
     //收到普通消息,格式:<HMessage *>
}

- (void)cmdMessagesDidReceive:(NSArray *)aCmdMessages{
     //收到命令消息,格式:<HMessage *>,命令消息不存数据库,一般用来作为系统通知,例如留言评论更新,
     //会话被客服接入,被转接,被关闭提醒
}

- (void)messageStatusDidChange:(HMessage *)aMessage error:(HError *)aError{
     //消息的状态修改,一般可以用来刷新列表,显示最新的状态
}

- (void)messageAttachmentStatusDidChange:(HMessage *)aMessage error:(HError *)aError{
    //发送消息后,会调用,可以在此刷新列表,显示最新的消息
}

第4步:集成更多业务功能

完成该步骤可以实现将用户资料传递到移动客服系统,将用户发起的会话直接分配给客服或技能组。

传访客属性

传访客属性到移动客服系统,访客属性将显示在“会话”页面的“资料”页签。

//属性可以缺省
VisitorInfo *visitor = [[VisitorInfo alloc] init];
visitor.name = @"小明儿";
visitor.qq = @"12345678";
visitor.phone = @"13636362637";
visitor.companyName = @"环信";
visitor.nickName = @"风口上的猪";
visitor.email = @"abv@126.com";
visitor.desc = @"环信移动客服";
HMessage *message = [....];//构造相关消息
[message addContent:visitor]; //传访客的属性

指定某个客服

HMessage *message = [....];//构造文字消息
[message addContent:[[AgentIdentityInfo alloc] initWithValue:@"客服名称"]];

指定某个技能组

HMessage *message = [....];//构造文字消息
[message addContent:[[QueueIdentityInfo alloc] initWithValue:@"分组名称"]];

实时音视频

集成音视频功能,需要:

  1. 在基本功能上增加依赖库:libiconv.dylib
  2. 在Bulid Phases → LINK Binary With Libraries 中导入libhelpdeskfull_sdk.a
  3. 由于github 文件限制,音视频的库只能在环信官网下载,如果之前集成了基本版的客服sdk,需要将引入HelpDeskSDK→HelpDeskSDKFull下的文件(夹):include、lib、helpdeskfull_sdk.h导入工程,替换之前的include、lib以及helpdesk_sdk.h
  4. 接着引入相关头文件,将在pch文件或全局.h文件中添加的代码修改为:
#ifdef __OBJC__
 #import "helpdeskfull_sdk.h"
 #import "HelpDeskUI.h"
 #endif

更多实时音视频API请参考移动客服 iOS SDK API

第5步:集成更多扩展功能

更多扩展功能(发送轨迹消息、发送订单消息、留言相关功能等),请参考移动客服iOS SDK API

SDK更新日志

版本更新信息请查看更新日志。

iOS SDK(访客端)更新日志