====== iOS SDK开发指南 ======
说明：本指南以iOS为开发平台的接入说明，方便有iOS研发基础的开发者快速了解整合云之讯通讯服务接口。其中本部分指南只包含通讯服务的接入方式和基于平台提供的Demo为蓝本进行在线体验。如需开发出针对企业和开发者所需的个性化应用，仍然需要具备一定经验的iOS开发经验（例如界面控件的开发以及与应用服务器配合调试的基础）
本指南一共包含两块信息：
1、
快速体验：编译官方提供的Demo源码，并即时体验
2、
快速上手：集成指南和集成注意事项
云之讯开放平台为方便开发者立即体验平台提供的各项通讯服务，提供基于iOS平台的简易功能的Demo iPA安装包以及Demo 源码。因Apple 官方开发政策限制原因，我们强烈建议您使用我们的源码并且配置您自有的开发者证书进行编译安装体验（相关开发政策请至Apple官网了解）。
=====1. 常规准备工作（必须）=====
* 注册云之讯平台开发者帐号（不必完成开发者认证）:[[http://www.ucpaas.com|云之讯开放平台官网]]
* 至官方网站下载Demo源码及安装包：[[http://www.ucpaas.com/freetrial/VoiceVerificationCode_demo#demo|下载地址]]
* 整体了解我们的测试Demo体验规则：[[:demo使用说明|Demo使用说明]]
=====2. 环境搭建（必须）=====
Mac OS X 10.8 (Lion)及以上版本; XCode5.0及以上版本。
=====3. Demo介绍 =====
**默认官方提供的iOS Demo 源码最新版是基于最新版本Xcode 和 Ucpaas官方发布的最新库 编译通过。**
Demo功能介绍，Demo演示了UCSSDK的API接口调用，主要实现的功能：\\
* 语音通话：需要对方的userId账号，免费通话 \\
* 视频通话：需要对方的userId账号，视频通话 \\
Demo工程文件结构说明： \\
* Product：应用生成的app; \\
* Framework：包含工程需要依赖的资源项，主要是系统和需要依赖的库资源; \\
* Demo：包含整个工程需要完成的代码文件：视图控制类的实现文件、resource文件夹(账号文件，图片资源文件等)、UCS_VOIPSDK文件夹(Video SDK库文件)、UCS_TCPSDK文件夹（Tcp SDK库文件）、UCS_IMSDK（IM SDK库文件）、Supportting Files文件夹。\\
=====4. 导入DEMO工程=====
* 导入DEMO工程：解压下载UCS_IM&VOIP_Demo.zip(此名字取决于官网)文件，在解压缩的文件夹中，双击Demo.xcodeproj文件，在XCode中打开工程，即可对Demo进行其他操作。
=====5. DEMO登陆方式=====
* 体验Demo前，请先Demo的登陆界面输入手机号，并获取手机短信验证码，使用获取到的短信验证码登陆相关Demo（如果该手机号没有登陆或者没有注册过，则会跳到填写昵称的页面，按照步骤填写昵称即可），并体验Demo相关能力。
======第二节. 快速上手======
快速上手主要介绍以SDK为核心，加入简单代码实现通讯服务功能。包括SDK介绍、SDK引入、以及开发一个简易通讯服务：音视频通话功能。如需更好的开发其他通讯服务，请阅读开发文档内的其他章节。
======1. 注册账号======
=====1.1 注册云之讯开发者账号======
成为云之讯平台开发者，并创建后台应用，详细步骤见注册[[:新手指引|云之讯开发者账号]]和[[:管理中心使用指南]]。如果你已经是平台开发者，并且对云之讯平台非常熟悉，那么你可以跳过这一步继续往下看。
======2. 下载SDK======
下载相应版本的SDK：[[http://www.ucpaas.com/product_service/download|官方下载地址]] （本示例中默认使用视频版最新SDK和TCP最新SDK）
======3. SDK介绍=======
SDK文件包含两个部分：
* Video SDK ：提供音视频功能
* TCP SDK ：提供连接云平台功能
Tcp SDK 文件说明：其中包含五个头文件：
* UCSTCPSDK.h ：包含TCPSDK所有头文件，使用时import这个文件就行
* UCSTcpClient.h ：包含TCPSDK的核心能力接口，比如登陆云平台、注销云平台等
* UCSTcpClientDelegate.h ：包含TCPSDK的事件回调接口
* UCSTcpDefine.h ：TCP相关的一些定义
* UCSError SDK ：错误信息定义类
* libucstcplib.a ：整个TCPSDK的静态库文件
Video SDK文件说明：其中包含三个头文件：
* UCSService.h ：为应用调用的函数头文件
* UCSEvent.h ：为SDK的代理函数头文件
* UCSCommonClass.h : 为SDK声明相应的实体
* libucsapisdk.a ：为整个videoSDK的静态库文件
======4. 工程配置======
这一节是为了让开发者能够用正确的导入sdk文件，以及正确配置工程信息。
=====4.1 环境要求=====
Mac OS X 10.8 (Lion)及以上版本; XCode5.0及以上版本。
=====4.2 创建工程=====
创建一个iPhone工程需要在Mac系统下面安装Xcode的软件，Xcode安装完成后可以在桌面的快速启动栏中的"Launchpad"中或者应用程序中找到xcode的图标，看到后单击或者双击即可打开软件，Xcode版本最小需要5.0。
打开Xcode后的界面可以看到几个选项，创建工程需要选择"Create a newXcode project",如下图所示：
{{ :图片20.png |}}
也可以根据菜单创建工程，依次选择XCode菜单栏中的FiLe→New→Project，如下图所示：
{{ :图片21.png |}}
选择完后弹出的界面中选择左边的"iOS"下面的"Application",然后选择右边的"SingLeViewAppLication"进行双击或者点击右下角"Next", 如下图所示：
{{ :图片22.png |}}
在完成后弹出的界面中的"ProductName"中填写你的工程名，如下图所示:
{{ :图片23.png |}}
添加完成后点击右下角的”Next”，在弹出的对话框中选择你需要把工程放置的位置。这样一个工程就初步的创建完成。
=====4.3 导入SDK头文件=====
创建完成工程后，把SDK包里面的videosdk文件夹和tcpsdk拷贝到新创建的工程路径下面，然后在工程目录结构中，右键选择Add Files to “云之讯Demo”(工程名称，在弹出的对话框中选择新创建的工程文件夹下的sdk这个文件夹，即前面拷贝的文件夹)。或者将这个文件夹拖入XCode 工程目录结构中，(此过程暂时不需要添加.a库，只需要添加.h的头文件)
{{ :图片24.png |}}
在弹出的界面中勾选Copy items into destination group’s folder(ifneeded),并确保Add To Targets勾选相应的target。 相应的操作请看下图中所示：
{{ :图片25.png |}}
=====4.4 导入SDK静态库=====
添加步骤:展开LinkBinary With Libraries后点击展开后下面的"+"来添加下面的依赖项,
如图所示
{{ :图片27.png |}}
{{ :图片27.1.png |}}
点击Add Other 后，找到libucstcplib.a和libucsvideosdk.a存放的地方，先添加libucstcplib.a，再添加libucsvideosdk.a。
=====4.5 配置工程信息=====
* 添加依赖框架(Frameworks) UCSSDK的实现，依赖了一些系统框架，在开发应用时，要在工程里加入这些框架。开发者首先点击工程右边的工程名,然后在工程名右边 依次选择TARGETS→BuiLd Phases→Link Binary With Libraries, (注：xcode7.0以上的需要将后缀为.dylib的库替换成后缀为.tbd的库，同时删除掉SenTextingKit.framework库的引用)
{{ :图片26.png |}}
添加步骤:展开LinkBinary With Libraries后点击展开后下面的"+"来添加下面的依赖项,
如图所示
{{ :图片27.png |}}
{{ :图片28.png |}}
* 编译器设置
在xcode环境下，首先点击工程右边的工程名,然后在工程名右边依次选择TARGETS、“Build Settings LLVM 6.1- Language C++(注：根据xcode的版本差异，名称中的6.1会根据版本变动)”中的"C++ Standard Library"，从后面的选择框中选择“libc++(LLVM C++ standard Library with C++11 support)”选项，如果默认是这个选项则不需要修改。步骤如下图所示：
{{ :图片29.png |}}
（注：xcode7.0以上的环境下）由于平台SDK暂时没有支持Bitcode功能，所以需要开发者将工程Bitcode功能关闭。 在工程名右边依次选择TARGETS、Build Options中的“Enable Bitcode”，在后面的选择框中选择NO，如果默认是，则不需要修改。步骤如下图所示：
{{ :图片29.1.png |}}
* 编译器链接设置
在xcode环境下，首先点击工程右边的工程名,然后在工程名右边依次选择TARGETS、Build Settings Linking中的Other Linker Flags. 中填入-ObjC。 如下图所示：
{{ :图片30.png |}}
* 工程属性设置 一般的iOS程序进入后台后会被系统挂起，就会停止执行，不能执行任何操作。
A. 从iOS4开始，苹果增加了特性，很好的支持了免费通话功能：
- 苹果支持应用可以在后台播放和录制声音；
- 苹果支持网络托管，保证应用在后台时，还能保持网络连接，能接收到来电；
- 应用可以设置一个超时处理，程序在后台运行时，周期性地唤醒应用，保证客户端和服务器有长连接，使网络不断开。
B. UCSSDK封装了这些特性，保证了在iOS平台上。
C. 开发者需要修改配置文件，这样iOS工程才能支持这些特性。
Tip：
1. 调用SDK文件要以.mm为后缀,要包含头文件UCSCommonClass.h、 UCSService.h和UCSEvent.h。
2. 在使用语音通话、视频通话等相关能力前需要做的三步：
2.1 TCP SDK初始化 ，参考节点：5.1 TCP SDK初始化
2.2 VIDEO SDK初始化 ，参考节点：5.2 VIDEO SDK初始化
2.3 云之讯账号连接云平台，参考节点：5.3 云之讯帐号连接云平台
3.介绍关于 语音通话 能力所需要的完整代码.参考节点：5.1- 6.8 ；
如果此时你已经开发好了一套免费通话 UI 就可以将它们进行一个整合、编译、运行.
=====5.1 TCP SDK初始化=====
遵循协议，实现代理方法。设置TCPSDK的代理，首先要初始化一个UCSTCPClient类型的对象，因为这个对象全局通用，所以实例化为单例对象。实例化与设置代理的方法为:
/*!
* @brief 实例化UCSTcpClient的一个单例对象
* @discussion 这个方法是生成UCSTcpClient的唯一方法，请不要使用init()等其他初始化方法，否知会出现未知的错误
* @return UCSTcpClient类型的单例对象
*/
+ (instancetype)sharedTcpClientManager;
如果需要监听TCP连接状态，则必须要设置TCP的代理，TCP连接状态回调包括，TCP连接成功，连接失败，重连成功，重连失败，账号在其他地方登录被踢线等。
/*!
* @brief 设置代理.
* @discussion 如果需要通过回调监控tcp连接状态之类的,就必须设置这个代理
* @param delegate tcp事件回调代理
*/
- (void)setTcpDelegate:(id ) delegate;
代理对象需要遵守的协议为：UCSTCPDelegateBase
初始化代码参考：
{
//获取到tcp sdk的UCSTcpClient对象，并传入代理实现的类实例
UCSTcpClient * ucsTcpClient = [UCSTcpClient sharedTcpClientManager];
[ucsTcpClient setTcpDelegate:self];
}
监听TCP连接状态回调代码参考:
- (void)didConnectionStatusChanged:(UCSConnectionStatus)connectionStatus error:(UCSError *)error
{
//TCP连接成功，连接失败，重连成功，重连失败，账号在其他地方登录被踢线等
}
=====5.2 Video SDK初始化=====
初始化SDK，该类提供拨打电话，接听以及拒接等方法。
#pragma mark - -------------------初始化函数-----------------------
//初始化实例
- (UCSService *)initWithDelegate:(id)delegate;
//设置代理方法
-(void)setDelegate:(id< UCSEventDelegate>)delegate;
云之讯Demo代码参考:
{
//注意：一定要设置代理
UCSService* ucsService = [[UCSService alloc] init];
[ucsService setDelegate:self];
// 另一种方式
UCSService* ucsService = [[UCSService alloc] initWithDelegate:self];
}
初始化成功回调(注：初始化成功后再调用tcp链接云平台)
：
- (void)onInitEngineSuccessful:(NSInteger)result{
//result为0的时候初始化成功，建议初始化成功后再调用tcp链接云平台
}
=====5.3 连接云平台=====
云之讯语音通话能力是建立在客户端和云平台连接成功的基础上，在连接断开的情况下，功能都不可用。云之讯语音通话能力是通过tcp长连接与云平台进行交互的，所以我们这里调用Tcp SDK中接口去连接云平台。请保证Video SDK的代理和Tcp SDK的代理已经设置正确。
如果是云平台的新账号体系则使用token的登陆方式，如果之前有使用过云之讯有关的能力，旧版本的账号体系，应该使用明文的登陆方式。
连接云平台，由UCSTcpClient的单例对象调用下面的方法
/*!
* @brief 连接云平台.
* @discussion (注意: 除非是为了兼容旧的IMSDK,否则请使用这个登陆方式)。
* @param token 加密的token
* @param success 成功回调
* @param failure 登陆失败回调，注意：登陆账号被踢线（在其他地方登录）也会回调这个block
*/
- (void)login_connect:(NSString *)token
success:(void (^)(NSString *userId))success
failure:(void (^)(UCSError *error))failure;
/*!
* @brief 连接云平台.
* @discussion (注意：这个登陆方式是为了兼容旧的IMSDK,后面可能会废弃)。使用这个接口的唯一场景是: 用户已经在现有的app中集成了我们旧的IMSDK,并且不希望更改成新的登陆方式(云之讯建议你更改成新的登陆方式)。其他场景下，请使用新的登陆方式。
* @param accountSid 账号sid
* @param accountToken 账号token
* @param clientNumber clientNumber
* @param clientPwd clientPwd
* @param success 成功回调
* @param failure 失败回调
*/
- (void)login_connect_old:(NSString *)accountSid
withAccountToken:(NSString *)accountToken
withClientNumber:(NSString *)clientNumber
withClientPwd:(NSString *)clientPwd
success:(void (^)(NSString *userId))success
注意：连接平台，我们提供了以上两个方法，但是我们建议你使用前一个方法。还有一点，每一次连接云平台前，我们都建议你先做一次断开操作。
你可以使用下面这个方法来执行断开操作：
/*!
* @brief 断开客户端和云平台的连接
* @param flag 是否关闭离线推送的bool值。YES关闭，NO不关闭。（单独使用Video sdk的时候设置为YES）
* @discussion 在客户端不需要继续与云平台保持连接的时候，调用这个方法断开连接。断开连接后，客户端将不会在收到与云平台的消息推送，也无法发送消息到云平台。
*
*/
- (void)login_uninitWithFlag:(BOOL)flag;
关于云之讯的重连机制：
当客户端和云平台的异常断开后，客户端处于Active的状态下，SDK会自动尝试重连云平台。
主动调用SDK提供的断开连接的方法不属于异常断开，SDK不会尝试重连。
云之讯Demo的参考代码：
{
//每次连接之前，先断开tcp连接。
[[UCSTcpClient sharedTcpClientManager] login_uninitWithFlag:0];
//使用token登陆。Token由用户的as服务器下发。这里不赘述。
[[UCSTcpClient sharedTcpClientManager] login_connect:im_token success:^(NSString *userId) {
// 连接云平台成功，业务自己处理
} failure:^(UCSError *error) {
// 连接云平台失败，业务自己处理
}];
}
======6. 集成VideoSDK基本功能======
下面以 语音通话 为案例，介绍如何在现有应用内添加通话服务。
=====6.1 创建语音通话连接=====
#pragma mark - -------------------呼叫控制函数-----------------------
/**
* 拨打电话
* @param callType 电话类型 0:语音电话 2:视频电话
* @param called userId号码
* @return
*/
- (void)dial:(NSInteger)callType andCalled:(NSString *)calledNumber andUserdata:(NSString *)callerData;
云之讯Demo代码参考:
{
//拨打语音通话(对方的云之讯账号，即userId)
[self.ucsCallService dial:callType andCalled:calledNumber andUserdata:callerData];
}
=====6.2 对方振铃回调=====
创建成功并连接被叫过程中代理函数（当发起呼叫后对方振铃时回调此函数）
- (void) onAlerting:(NSString*)callid;
=====6.3 对方接听时候回调=====
对方接听的代理函数（当接听成功后回调此函数）
-(void) onAnswer:(NSString*) callid;
=====6.4 呼叫失败回调=====
呼叫失败(被叫拒接，被叫忙等原因)的代理函数，可参考错误码查找失败原因
//呼叫失败，可根据reason查找错误原因 // TODO
- (void) onDialFailed:(NSString*)callid withReason:(UCSReason*)reason;
=====6.5 通话挂断回调=====
通话过程中，对方挂断的代理函数
//通话过程中，通话挂断，可以通过reason查看挂断原因 // TODO
- (void) onHangUp:(NSString*)callid withReason:(UCSReason*)reason;
=====6.6 通话呼入=====
//实现代理函数
-(void)onIncomingCall:(NSString*)callid withcalltype:(UCSCallTypeEnum) callType withcallerNumber:(NSString*)callerNumber {
//有免费电话呼入处理 //TODO
}
=====6.7 通话呼入=====
接听免费通话
- (void) answer: (NSString*)callid; {
//接听成功 //T0D0
}
=====6.8 挂断或者被叫拒绝通话=====
/**
* 挂断电话
* @param callid 电话id
*/
- (void) hangUp: (NSString*)callid;
======7. 编译运行及工程打包======
=====7.1 编译=====
在用Xcode打开工程后，看是需要用真机还是用模拟器运行应用，默认是模拟器下编译运行的，单击左上角的三角符号就可以进行应用运行， 如果是真机则需要你插上真机连接电脑，然后在最上面有单击"iPhone6.1SimuLator"(6.1为模拟器的版本)后可以看到显示你iPhone的机器 名字，并且选择后点击左上角的三角符号进行运行即可。如下图所示：
{{ :图片32.png |}}
=====7.2 查看工程日志=====
查看编译器日志。 选择xcode右上角区的的按钮
{{ :图片33.png |}}
=====7.3 工程打包=====
首先要从弹出的列表中选择第一项
{{ :图片34.png |}}
然后选择xcode的菜单Product→Archive项
{{ :图片35.png |}}
单击Export…按钮
{{ :图片36.png |}}
根据需要选择，测试请选择第二项，然后点击Next
{{ :图片37.png |}}
在下列窗口中请选择程序的签名证书
{{ :图片38.png |}}
点击Choose后，选择第一项，确认无误后点击Next
{{ :图片38.1.png |}}
点击Choose后，核对app的信息，确认无误后点击Next
{{ :图片39.png |}}
点击Next后结束打包，打包出来的.ipa文件，默认保存在桌面。
=====最后一步：关于错误码=====
[[video_sdk:iosv3returncode|错误码]]请参考平台文档说明。