====== 1、IM iOS UIKit SDK简介 ====== 云之讯IM UIKit是在原子SDK的基础上封装了IM相关的上层业务和UI，开发者无须处理复杂IM业务及UI，只需启动已封装好的界面就能拥有IM功能。包括：IM会话列表界面、好友列表界面、聊天界面等。 ====== 2、集成前的准备 ====== 您需要成为云之讯平台的开发者，然后在平台创建应用，详细步骤见注册云之讯开发者账号和管理中心使用指南。如果您已经是平台开发者，并且对云之讯平台非常熟悉，那么您可以跳过这一步继续往下看。 使用云之讯UIKIt组件登陆云平台，需要使用到token，token是需要服务器向云平台申请，然后下发给用户登录。 ======3、下载UIKit组件的SDK ====== 您想下载云之讯UI组件最新的SDK，请点击UIKIT SDK连接（[[http://www.ucpaas.com/product_service/im#item4|下载地址]]） =====3.1、SDK目录讲解 ===== 从官网上下载的SDK包含的主要四部分： 1、USCIMkit.a UI组件使用的静态库，界面组件的封装包 2、UCSIMKit.bundle: 包含静态库中要使用的图片、语音资源 3、Lib: 包含录音功能相关文件、emoj表情的plist文件、地图坐标信息转换的db文件 4、头文件说明： UCSUIKitManager.h SDK的核心类，单例类 ChatListViewController.h 会话列表类 ChatViewController.h 聊天界面类 InfoManager.h 文件的处理类 Singleton.h、SynthesizeSingleton.h 生成单例的类 MultiSelectItem.h 选择好友的model类 MultiSelectViewController.h 选择好友的页面 SingelChatDeltailViewController.h 单聊设置界面 BaseViewController SDK的基础视图控制器类 UCConst.h 通知的枚举类 UCSIMDefine.h IM消息相关枚举类 UCSUserInfo.h 用户model类 UCSGroupInfo.h 群的model类 UCSUIKITSDK.h 包含所有的头文件 UCSTcpDefine.h TCP相关枚举类 UCSError.h SDK错误类型类 注意事项：添加的Lib文件成功的标志是在工程文件中的Copy Bundle Resource配置栏有相应的显示。 ======4、SDK配置工程 ====== ===== 4.1、新建工程 ===== 新建工程，为了方便演示，请选择创建一个 Empty Application 。如图所示： {{ :无标题1.png |}} =====4.2、导入UIKIT SDK ===== 将下载好的UCSUIKit_SDK（版本号）.zip包解压到任意目录。在您的项目中加入libucsimkit.a、头文件、ucsimkitBundel.bundel(资源包)，lib文件夹。 导入UIKit SDK后工程界面如下图所示: {{ :屏幕快照_2016-03-07_下午5.21.44.png |}} =====4.3、添加依赖库 ===== 您需要添加以下依赖库： libc++.dylib libstdc++.dylib Libz.1.1.3.dylib Libsqlite3.0.dylib libicucore.A.dylib MessageUI.framework MediaPlayer.framwork AssetsLibrary.framework CoreLocation.framework CFNetworking.framework CoreFoundation.framework MobileCoreServices.framework。 CoreMedia.framework ImageIO.framework CoreVideo.framework AudioToolbox.framework AVFoundation.framework SystemConfiguration.framework 生成的界面如下图所示： {{ :屏幕快照_2016-01-20_下午2.17.16.png |}} 注意事项：在Xcode7以上的编译器上，添加库时找不到以.dylib为后缀的库，将.dylib替换成.tdb就OK了。 =====4.5、预编译SDK ===== 新建一个预编译文件，将UCSUIKITSDK.h引入预编译文件中。如果工程中已经存在UCSUIKITSDK.h预编译文件，直接将文件导入工程。 如果新建预编译文件需要导入下面2个头文件： #import #import 编译整个工程，如果出现错误，请返回检查编译选项。 ====== 5、IOS UIKit SDK快速集成 ====== ===== 5.1、初始化SDK ===== 调用核心单例设置推送的类型 //通过单例的方法来调用核心类的能力接口 [UCSUIKitManager shareUCSUIKit] /** * 设置开发环境 * 参数 parameter UCSPushEnvironment 是枚举类型 开发环境和发布环境 */ [[UCSUIKitManager shareUCSUIKit]setPushEnvironment:UCSPushEnvironment_Production]; - 注意事项： 首先必须设置deviceToken，模拟器是无法获取devicetoken，也就没有推送功能。 - 当使用"开发／测试环境"的appkey测试推送时，必须用Development的证书打包，并且在后台上传"开发／测试环境"的推送证书，证书必须是development的。 当使用"生产／线上环境"的appkey测试推送时，必须用Distribution的证书打包，并且在后台上传"生产／线上环境"的推送证书，证书必须是distribution的。 ===== 5.2、设置推送开发环境 ===== 推送的环境要根据上传的证书的类型来匹配，证书是发布证书，对应设置为发布环境。同理，如果证书是开发型证书，对应设置为开发环境。（证书的类型可以在钥匙串访问中查找） //设置推送的环境 1为开发 其他为发布 eg： [[UCSUIKitManager shareUCSUIKit]setPushEnvironment:UCSPushEnvironment_Develop]; 在Appdelegate相应的系统方法中，保存推送的Token - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { NSString *deviceToken1 = [[[[deviceToken description] stringByReplacingOccurrencesOfString:@"<"withString:@""] stringByReplacingOccurrencesOfString:@">" withString:@""] stringByReplacingOccurrencesOfString: @" " withString: @""]; [[NSUserDefaults standardUserDefaults] setObject:deviceToken1 forKey:@"DeviceToken"]; [[NSUserDefaults standardUserDefaults] synchronize]; } 注意事项： NSUserDefaults设置的DeviceToken的名字一定要是"DeviceToken",这样才能被SDK识别。 ===== 5.3、连接服务器 ===== 云之讯UIKit SDK的消息收发必须在和平台保持连接的情况下进行(离线推送除外)，连接平台示例代码如下： /** * 连接服务器 @param token 从服务端获取的用户身份令牌（Token）。 @param successBlock 调用完成的处理。 @param errorBlock 调用返回的错误信息。 @param tokenIncorrectBlock token错误或者过期。需要重新换取token，但需要注意避免出现无限循环。 @return 无 */ [[UCSUIKitManager shareUCSUIKit] connectWithToken:im_token success:^(NSString *userId) { [self connectionSuccessful:0]; } error:^(UCSConnectErrorCode status) { [self connectionFailed:-1]; }]; ===== 5.4、启动会话列表界面 ===== 启动会话的主要类是 ChatListViewController ChatListViewController *chatList = [[ChatListViewControlleralloc]init]; [self.navigationControllerpushViewController:chatListanimated:YES]; ===== 5.5、启动单聊会话界面 ===== 启动单聊的主要类是 ChatViewController (在demo中默认一个固定的chatter) ChatViewController *chat= [[ChatViewController alloc]initWithChatter:@"15502019128" type:1]; [self.navigationController pushViewController:chat animated:YES]; ===== 5.6、启动邀请好友界面 ===== 邀请好友的主要类是 MultiSelectViewController （开发者可以自定义联系人，但联系人必须经过云之讯鉴权） MultiSelectViewController *multiSel= [[MultiSelectViewControlleralloc]initWithType:UCSelectTypeCreatetargetId:[[InfoManagersharedInfoManager]phone ]]; [self.navigationController pushViewController:multiSel animated:YES]; ===== 5.8、SDK的其他接口 ===== UIKitSDK还提供了其他的接口，供开发者自由选择搭配。示例代码如下： /** 获取所有未读信息的数量 @return 返回的具体数据 */ - (NSInteger)getTotalUnreadCount; /** 查询帐号与服务器连接状态 @return Yes 为是连接状态 NO 离线状态 */ - (BOOL)isConnected; ======6、UI的自定义====== ===== 6.1、用户头像和昵称以及好友联系人的自定义 ===== 云之讯不维护和管理用户的基本信息（头像 id 、 昵称）的获取、缓存、变更和同步。所有的好友联系人的个人信息（比如昵称、头像）需要开发者自己维护，UIKit SDK提供了相应的接口回调用户信息。 设计的原理： 通过UCSUIKitManager的代理设置数据源的参数，然后调用代理方法参数的Block来回调数据，完成SDK从外部数据的获取。 设置用户的信息是通过代理协议来设置数据源（类似TableView的代理方式），开发者只要实现2个代理就能设置数据源（可参考Demo）。 /** @protocol UCSIMUserInfoFetcherDelegagte 用户信息的获取器。 IM 是不知道用户信息的,IM 将调用此 Delegagte 获取用户信息。 */ @protocol UCSIMUserInfoFetcherDelegagte /** * 获取用户信息。 * @param userId 用户 Id。 * @param completion 用户信息 */ - (void)getUserInfoWithUserId:(NSString *)userId completion:(void(^)(UCSUserInfo* userInfo))completion; @end /** 好友列表的获取器。 云之讯 本身不保存 App 的好友关系，如果在聊天中需要使用好友关系时（如：需要选择好友加入群聊），UCSIMkit 将调用此 Delegagte 获取好友列表信息。 */ @protocol UCSIMUserInfoDataSource /** 获取好友信息列表。 @return 好友信息列表。 */ -(NSArray*)getFriends; @end 在提供的用户信息的类中实现2个代理，组件的SDK就能获取到用户的信息数据 getFriend是获取用户的联系人 在试图控制器里设置一个代理然后实现参数的传递 //设置代理 [UCSUIKitManager setIMUserInfoDataSource:self]; [UCSUIKitManager setUserInfoFetcherWithDelegate:self isCacheUserInfo:NO]; #pragma mark - UCSIMUserInfoDataSource method -(NSArray*)getFriends { return self.allFriendsArray; } #pragma mark - RCIMUserInfoFetcherDelegagte method -(void)getUserInfoWithUserId:(NSString *)userId completion:(void(^)(UCSUserInfo* userInfo))completion { UCSUserInfo *user = nil; if([userId length] == 0) return completion(nil); for(UCSUserInfo *u in self.allFriendsArray){ if([u.userId isEqualToString:userId]){ user = u; break; } } return completion(user); } ===== 6.2、群信息头像和名称的自定义 ===== 云之讯群信息头像的的自定义和用户头像的自定义原理是一样的，需要开发者自己根据获取群的ID设置群的头像和名称。 设计的原理： 通过UCSUIKitManager的代理设置数据源的参数，然后调用代理方法参数的Block来回调数据，完成SDK从外部数据的获取。 设置群信息是通过代理协议来设置数据源（类似TableView的代理方式），开发者只要实现2个代理就能设置数据源（可参考Demo）。 /** @protocol UCSIMUserInfoFetcherGroupDelegagte 群信息的代理 */ @protocol UCSIMGroupInfoFetcherDelegagte /** * 获取某个群信息。 * * @param groupId 群 Id。 * @param completion 群信息 */ - (void)getGroupInfoWithGroupId:(NSString *)groupId completion:(void(^)(UCSGroupInfo *groupInfo))completion; @end /** 群信息数据获取器。 */ @protocol UCSIMGroupInfoDataSource /** 获取群信息列表。 @return 群信息信息列表。 */ -(NSArray*)getGroupData; @end 在提供的用户信息的类中实现2个代理，组件的SDK就能获取到用户的信息数据 getGroupDat是开发者根据群ID设置群的消息 #pragma mark -UCSIMGroupInfoDataSource - (NSArray*)getGroupData { UCSGroupInfo *group = [[UCSGroupInfo alloc]init]; group.userId = @"2"; group.name = @"体验群"; group.portraitUri = @"http://pica.nipic.com/2007-11-09/2007119124413448_2.jpg"; UCSGroupInfo *group1 = [[UCSGroupInfo alloc]init]; group1.userId = @"10"; group1.name = @"我的群"; group1.portraitUri = @"http://pica.nipic.com/2007-11-09/2007119124413448_2.jpg"; [self.allGroupArray addObject:group]; [self.allGroupArray addObject:group1]; return self.allGroupArray; } #pragma mark --UCSIMGroupInfoFetcherDelegagte - (void)getGroupInfoWithGroupId:(NSString *)groupId completion:(void (^)(UCSGroupInfo *))completion { UCSGroupInfo *user = nil; if([groupId length] == 0) return completion(nil); for(UCSGroupInfo *u in self.allGroupArray) { if([u.userId isEqualToString:groupId]) { user = u; break; } } return completion(user); } ===== 6.3、导航栏的自定义 ===== 通过子类的继承的方式，重写父类方法来达到UI的自定义。从而自定义内容更广，形式更加简单。 会话列表界面、会话界面、邀请好友界面、聊天设置界面都继承BaseViewController。 能够被重写的方法如下所示: /** @brief 配置导航栏上 */ -(void)configureNavigationBar; /** * 导航左面按钮点击事件 */ - (void)leftBarButtonItemPressed:(id)sender; /** * 导航右面按钮点击事件 */ - (void)rightBarButtonItemPressed:(id)sender; 注意事项： 1、如果需要替换聊天界面的背景图片，可以在ucsimkitBundle.bundle资源库文件中替换对应chat_backgroud_sky名字的图片 2、自定义的聊天界面需要开发者新建一个类，继承chatviewController。 ======7、常见问题 ====== **Q：集成SDK后，头像不显示** A：检查是否正确实现了-(NSArray*)getFriends；这个代理方法。 **Q：集成SDK后，如果自定义了聊天页面（chatViewController），然后需击会话页面的cell，进入聊天页面，聊天页面的风格需要和自定义的聊天页面相同。 ** A：请联系我们的技术支持，有相应的定制版本。 **Q：集成SDK后，编译的过程fail，bug工作台出现----x86的字样。 ** A：请选择真机调试，SDK库文件暂不支持模拟器编译。