CocoaPods trunk is moving to be read-only. Read more on the blog, there are 17 months to go.

MeChatSDK 1.1.7

MeChatSDK 1.1.7

×

TestsTested ✗
LangLanguage Obj-CObjective C
License Commercial
ReleasedLast Release Jun 2015

Maintained by YaoBiDa.

MeChatSDK 1.1.7

  • By
  • meiqia

[toc]

美洽移动应用 SDK for iOS 开发文档

在您阅读此文档之前，我们假定您已经具备了基础的 iOS 应用开发经验，并能够理解相关基础概念。 如有疑问，欢迎加入 美洽 SDK 开发 QQ 群：295646206

1. SDK 工作流程

美洽SDK的工作流程如下图所示。

说明：

  • 自定义用户数据将会在客服平台显示；
  • 当 SDK 服务被关闭后，美洽会发送推送，推送消息将会发送至开发者的服务器。设置服务器地址，请使用美洽管理员帐号登录美洽，在入口设置菜单中设置。

2. 使用准备

文件介绍

| 文件名|说明| |--|--| |MeChat.a|美洽SDK核心静态库| |MCCore.h|连接客户端到美洽服务器，该文件提供主要功能| |MCDelegate.h|包含所有的回调代理函数，提供即时消息、请求结果、异常报告等| |MCDefination.h|枚举分类| |MCService.h|实体类：客服| |MCTextMessage.h|实体类：文本消息| |MCImageMessage.h|实体类：图片消息| |MCAudioMessage.h|实体类：语音消息| |MCEvent.h|实体类：事件| |MCChatViewController.h|美洽提供的UI| |MeChatSDK.bundle|资源文件| |libopencore|美洽SDK需要的第三方模块|

美洽 SDK 导入

把美洽 SDK 文件夹拷贝到新创建的工程路径下面，然后在工程目录结构中，右键选择 Add Files to “工程名” 。或者将这个文件夹拖入 XCode 工程目录结构中。

引入依赖库

美洽 SDK 的实现，依赖了一些系统框架，在开发应用时，要在工程里加入这些框架。开发者首先点击工程右边的工程名,然后在工程名右边依次选择 TARGETS -> BuiLd Phases -> Link Binary With Libraries ，展开 LinkBinary With Libraries 后点击展开后下面的 + 来添加下面的依赖项:

  • libsqlite3.dylib
  • Accelerate.framework
  • CoreTelephony.framework
  • SystemConfiguration.framework
  • AVFoundation.framework
  • AudioToolbox.framework

3. 快速应用 SDK

使用美洽提供的 UI，可以免去 UI 部分的开发，便能快速应用 SDK。使用美洽 SDK 提供的 UI，必须执行初始化 SDK 和调出视图两个步骤，其余接口都是可选项。

三分钟快速应用 SDK

如上所述，使用美洽SDK，必不可少的一步便是初始化SDK，完成初始化后便可操作SDK其他功能和接口，比如推出视图。美洽提供的UI简化了开发流程，使得为 APP 添加客服功能最低仅需2行代码：

//在程序启动时初始化
[MCCore initWithAppkey:@"appkey" expcetionDelegate:object];

//当用户需要使用客服服务时，创建并推出视图
[self.navigationController pushViewContronller:[MCCore createChatViewController] animated:YES];

至此，你已经为你的 APP 添加美洽提供的客服服务。而美洽 SDK 还提供其他强大的功能，可以帮助提高服务效率，提升用户使用体验。接下来为你详细介绍如何使用其他功能。

初始化 SDK

注意：

  1. 所有操作都必须在初始化 SDK 后才能正常执行
  2. 如果你是平台/渠道企业用户，请使用平台/渠道的初始化SDK接口

将 SDK 文件添加到工程，在AppDelegate中引用 MCCore.h 文件，然后在application: willFinishLaunchingWithOptions:函数中初始化 SDK 。初始化 SDK 必须填写美洽授权的 appkey 代码，而异常代理可以为空。

[MCCore initWithAppkey:@"appkey" expcetionDelegate:object];

如果您不知道 appkey ，请使用美洽管理员帐号登录美洽，在入口设置菜单中查看。如图：

添加自定义信息

功能效果展示：

为了让客服能更准确帮助用户，可以在初始化 SDK 之后，调用上线接口前添加用户数据，但这并不是必须的，你可以跳过这个步骤。示例如下：

//创建基本信息、用户资料、联系方式
NSDictionary* userInfo =  @{
                            @"realName"     : @"张三",
                            @"avatar"       : @"http://meiqia.com/avatar.jpg",
                            @"appUserName"  : @"loginName",
                            @"appUserId"    : @"10000",
                            //可以只添加部分信息
                            };
//创建自定义信息
NSDictionary* otherInfo = @{
                            @"角色名称" : @"阿尔萨斯",
                            @"金币"    : @"12322金币",
                            @"角色等级" : @"18",
                            //省略...
                            };

[MCCore addUserInfo:userInfo addOtherInfo:otherInfo];

userInfo 和 otherInfo 为 NSDictionary 类型，也可以为nil。userInfo 中的键为美洽已经罗列的常量(详见下表)，otherInfo 则可以添加你想让客服看到的任何数据。这两个参数的键值必须是 NSString 类型。 注意：该方法需要在让用户上线前调用，而MCChatViewController已经实现了用户上线操作，所以使用MCChatViewController的开发者，需要再推出MCChatViewController前使用该方法。

用户信息常量表

Key 说明 备注
realName 真实姓名
sex 性别
birthday 生日
age 年龄
job 职业
avatar 头像URL
comment 备注
appUserId 用户识别符 设置后可实现消息漫游
appUserName 登录名
appNickName 昵称
tel 电话
email 邮箱
address 地址
QQ QQ
weibo 微博ID
weixin 微信号

指定分配客服

美洽默认会按照管理员设置的分配方式智能分配客服，但如果需要让来自 app 的顾客指定分配给某个客服或者某组客服，需要在上线前添加以下代码：

//分配到指定组里面的客服
[MCCore specifyAllocGroup:groupId];

//分配到指定客服，但不强制分配
[MCCore specifyAllocServer:serverId isForce:NO];

该选项需要在用户上线前设置。isForce 为是否强制分配到该客服。如果不强制，若该客服不在线，会分配给其他客服。

注：组 id 和客服 id 可以通过管理员帐号在后台查看。查看获取方法

调出视图

美洽提供的视图，完成了一整套MCCore中的接口。让开发者免去 UI 开发工作。并在MCChatViewController类中添加其他自定义选项和功能扩展，稍后将介绍部分自定义选项。 你只需要在用户需要客服服务的时候，推出美洽UI。如下：

//创建视图
MCChatViewController* viewController = [MCCore createChatViewController];
//弹出视图
[self.navigationController pushViewContronller:viewController animated:YES];

美洽已经在视图中实现了 SDK 几乎所有接口，包括离线推送，但如果需要让推送生效，但需要在弹出视图前添加设备唯一标示符：deviceToken:

viewController.deviceToken = @"deviceToken";

deviceToken 的获取，此处暂不详解，请自行查找资料。

推送会在用户退出界面时触发，但为避免用户在与客服聊天过程中将 APP 退出到后台也能收到推送，您需要在AppDelegate中的applicationDidEnterBackground:方法中添加以下代码：

[MCCore letUserOffOnlineIsSynchronizationWithDeviceToken:deviceToken];

如果您没有为 deviceToken（设备唯一标示符）赋值，可能无法锁定消息的设备来源。

UI自定义

自定义 UI 可以让美洽的视觉与你的 APP 风格融为一体，甚至可以根据你的需求，添加更多功能。我们为你介绍以下两种修改UI的途径，详细介绍可以在代码和资源中查看。

通过参数修改

在MCChatViewController.h中有部分界面 UI 参数，可以在创建视图之后，弹出视图之前修改这些参数，例：

MCChatViewController* viewController = [MCCore createChatViewController];
//替换自定义TitleView
viewController.titleView = 你的UIView对象;
//修改footerBar背景颜色
viewController.footerBar.backgroundColor = [UIColor grayColor];
//为TextView添加边框
viewController.textView.layer.borderColor = [UIColor grayColor].CGColor;
viewController.textView.layer.borderWidth = 1;
//推出视图
[self.navigationController pushViewController:viewController animated:YES];

这里只列出了部分自定义选项作为参考，更多自定义选项，查看MCChatViewController类。

通过素材修改

美洽提供的 SDK 中有名为MeChatSDK.bundle的素材包，将相同尺寸的素材替换即可修改相应显示效果。

4. 直接使用接口开发客服功能

此项适合需要自行定制 UI 的客户使用。配合以下接口，完成APP上客服系统的开发。使用以下接口前，别忘了 初始化SDK。

接口描述

平台或渠道用户初始化

如果你是美洽的平台/渠道用户，你旗下有不同的企业，那么就需要使用 平台/渠道客户 专用的初始化SDK接口。

[MCCore initWithAppkey:@"yourappkey" innerName:@"yourInnerName" expcetionDelegate:object];

该接口的 appkey 是平台/渠道企业的 appkey。innerName 是平台/渠道旗下，需要使用客服的企业的 innerName。 注：innerName 由平台/渠道提供（需保证贵方平台内的唯一性），并在调用美洽开放平台接口创建企业时，传递到美洽以记录此信息。

添加自定义信息

添加自定义信息操作和上述相同，跳至 添加自定义信息

指定客服分配

指定分配客服和上述相同，跳至 指定分配客服

获取历史消息

[MCCore getMessageWithNumber:length startIndex:startIndex];

此接口使用分页的形式获取历史消息，startIndex 为获取的起始位置，length 为需要获取的消息长度。使用[MCCore getAllMessageAndServeEvents]可以获取所有消息和事件。事件包含客服的分配、客服间转接事件。

用户上线

在用户上线前，不可以使用收发消息等操作，只能使用留言。开发者调用上线接口后，即可开始其他操作。当用户没有分配到客服，如果用户发送消息，消息将会以留言的方式发送。当用户上线成功，可以通过代理方法获取到客服对象。

[MCCore letUserOnlineWithDelegate:id];

接收即时消息

在用户成功上线后，开发者设置接收消息的代理类，接收消息和服务事件。设置代理后，实现MCMessageDelegate中的receiveMessage:和receiveEvent:，即可通过这两个代理函数接收消息和事件。

[MCCore handleReceiveMessageAndEventWithDelegate:id];

事件包括：分配接待客服事件、客服转接事件

发送消息

当前消息类型有文字消息和图片消息。发送不同消息使用不同的接口，接口示例如下：

//发送文字消息，并获得消息实体
MCTextMessage* message = [MCCore sendTextMessageWithContent:@"content" delegate:(id)self]

//发送图片消息，并获得消息实体
MCImageMessage* message = [MCCore sendImageMessageWithFile:image delegate:(id)self]

调用MCCore中发送相应类型消息的接口，传入参数即可发送。调用发送消息接口后，接口会返回一个消息实体，但此时消息实体中的消息状态为SentStatus_Sending（发送中）。消息发送结果的代理函数，会返回消息是否发送成功。

语音发送

开始录音

美洽提供的语音发送接口可以实现实时上传，开始录音须调用接口：

//开始录音并设置代理，同时接收语音消息对象
MCAudioMessage* message= [MCCore startRecordingAndSendAudioMessage:(id)self delegate:delegate];

实现该代理函数，可以接收到录音时的声音大小和录音状态。

结束录音和发送

在用户完成录音后，结束录音并发送消息则调用：

[MCCore stopRecordingAudioMessage];
取消发送和结束录音

如果用户取消发送，或者在录音过程中出现来电、APP退出到后台等特殊情况，需要终止录音：

[MCCore cancelSendAudioMessage];

用户离线和推送

当用户执行某些特定操作，开发者应该让该用户离线，并发送“开启推送”的请求。例如当应用程序即将退出到后台时就应该使用离线和推送接口。详见开启推送并离线。

消息推送

设置接收推送的服务器地址

推送消息将会发送至开发者的服务器，设置服务器地址，请使用美洽管理员帐号登录美洽，在入口设置 -> inApp SDK菜单中设置。

推送消息结构

当有消息需要推送时，美洽服务器会向开发者设置的服务器地址发送推送消息，类型为 POST ，参数有：

|参数|说明| |--|--| |_id|消息ID| |content|消息内容| |fromName|客服名称| |status|消息状态| |createdTime|消息创建时间| |metadata|开发者自定义的用户数据| |deviceToken|设备唯一标识符| |unReadMsgNum|该用户的未读消息数量| |os|系统版本| |device|设备型号| |from|渠道| |appUserId|用户ID| |tel|手机号码| |IM|QQ号等信息| |email|电子邮箱| |appkey|AppKey|

开启推送并离线

使用该接口，将会让顾客离线，并且开启推送。开启推送后，消息将会发送至开发者服务器，SDK 将不会再收到即时消息。如需让 SDK 接收消息，重新调用上线请求即可。

SDK 中开启推送的接口有两个，但作用相同：

//同步请求
+(BOOL)letUserOffOnlineIsSynchronizationWithDeviceToken:(NSString*)_deviceToken;

//异步请求
+(void)letUserOffOnlineIsAsynchronousWithDeviceToken:(NSString*)_deviceToken delegate:(id<MCConnectDelegate>)delegate;

同步请求常用于 AppDelegate 中的 applicationDidEnterBackground: 方法。

网络连接状态监控

功能介绍

美洽 SDK 提供网络连接监控模块可以实时监测网络连接的类型：

  • MCNetworkType_None
  • MCNetworkType_WiFi
  • MCNetworkType_2G
  • MCNetworkType_3G
  • MCNetworkType_4G

网络连接类型改变时，会触发通知中心（KVO），开发者可添加观察者进行监测，通知名称为字符串常量：kMCNetworkStatusChang。

添加观察者

在需要网络监控的类中添加观察者，例：

[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(networkStatusChange:) name:kMCNetworkStatusChange object:nil];

实现网络提醒方法

如上例中，我们添加了一个名为 networkStatusChange: 的带参方法。该方法的参数类型为 NSNotification ，我们可以使用 NSNotification 获取到当前网络类型 kMCNetworkType ，但因为 kMCNetworkType 为枚举类型，不能直接通过参数传输，所以需要使用包装类 NSNumber 进行转换，详细代码示例如下：

-(void)networkStatusChange:(NSNotification*)notification
{
//获取并转换为网络类型
kMCNetworkType networkType = [((NSNumber*)[notification object]) intValue];
}

获取当前网络状态

初始化 SDK 成功后，可以通过 +(kMCNetworkType)getNetworkStatus 接口获取当前网络状态。

kMCNetworkType networkStatus = [MCCore getNetworkStatus];

5. SDK中嵌入美洽SDK

如果你的开发项目也是SDK，那么在了解常规APP嵌入美洽SDK的基础上，还需要注意其他事项。

与App嵌入美洽SDK的步骤相同，需要 导入美洽SDK -> 引入依赖库 -> 初始化SDK -> 使用美洽SDK。但是完成以上操作后，并不能让美洽正常工作，还需要公开素材包：

开发者点击工程右边的工程名,然后在工程名右边依次选择 TARGETS -> BuiLd Phases -> Copy Files ，展开 Copy Files 后点击展开后下面的 + 来添加美洽素材包MeChatSDK.bundle。

在之后发布你的SDK时，将MeChatSDK.bundle一起打包即可。

更新日志

v1.1.6 2015年3月30日

  • 【修改】URL、电话号的正则表达式
  • 【修复】超链接无法点击
  • 【新增】App退出后台后顾客立即下线

v1.1.5 2015年3月20日

  • 【修复】1.1.4在未初始成功又使用了消息同步时，无法进入对话
  • 【移除】Appkey失效检查。现在删除Appkey后SDK将继续正常工作

V1.1.4 2015年03月12日

  • 【新增】获取网络消息接口
  • 【新增】UI添加同步网络消息功能
  • 【修复】更换设备可能出现消息排序不对

V1.1.3 2015年03月02日

  • 【新增】自定义是否显示提醒视图（通过设置 hideTipView 属性）
  • 【新增】允许在未初始化成功的情况下获取历史消息
  • 【新增】可禁用 LOG 输出
  • 【优化】点击消息列表隐藏键盘
  • 【修复】无法进入和退出 SDK 的问题

V1.1.2 2015年01月29日

  • 【优化】顶部提示不受 putFrame 影响的问题
  • 【修复】部分游戏不能放大图片的问题
  • 【修复】部分 iPad 不能打开相册的问题

V1.1.1 2015年01月13日

  • 【新增】footerBar 等多个自定义选项（详见 MCChatViewController.h ）
  • 【修复】iOS7 以下系统切换网络 crash

V1.1.0 2014年12月31日

  • 【新增】留言发送语音和图片
  • 【新增】MCChatViewController 支持自定义 TitleView
  • 【优化】兼容 iOS5
  • 【优化】将美洽的缓存文件从 Document 移至 Caches 文件夹
  • 【修复】取消录音后无法滑动聊天记录
  • 【修复】切换语音时布局可能会混乱

V1.0.9 2014年12月11日

  • 【新增】支持横屏
  • 【新增】可禁用语音功能（见 MCChatViewController.h）

V1.0.8 2014年12月04日

  • 【新增】支持发送语音消息
  • 【修复】使用某些渠道导致的游戏 Crash
  • 【优化】修正 putFrame

V1.0.6 2014年11月11日

  • 【修复】大屏下消息气泡会置低
  • 【修改】可能出现 bug 的算法

V1.0.5 2014年11月04日

  • 【新增】支持多设备消息同步
  • 【新增】添加事件显示开关
  • 【新增】支持多用户
  • 【优化】兼容 iOS 6
  • 【优化】事件显示机制
  • 【优化】数据改为使用数据库储存
  • 【优化】支持大屏 iPhone

V1.0.4 2014年10月22日

  • 【新增】指定客服分配添加是否强制分配选项
  • 【新增】网络实时监控
  • 【优化】为避免名称冲突，MCDefination 中的枚举名添加「MC」前缀
  • 【删除】弃用之前添加用户信息的借口，添加新的设置用户信息的接口

V1.0.3 2014年10月14日

  • 【新增】MCChatViewController 增加自定义正则表达式匹配、消息和事件文字颜色修改
  • 【新增】重发消息接口