用户工具

im_ios_ui组件开发指南

这是本文档旧的修订版!


1、IM iOS UIKitSDK简介

UI界面组件UCSIMKit 是集成云之讯的IM会话列表、聊天界面、邀请好友界面等。可快速集成和高度自定义界面的SDK 在使用 IOS SDK之前,您可以先体验一下相关DEMO能力演示,帮助您快速了解和实现相关的能力

2、集成前的准备

成为云之讯平台开发者,并创建后台应用,详细步骤见注册云之讯开发者账号和管理中心使用指南。如果你已经是平台开发者,并且对云之讯平台非常熟悉,那么你可以跳过这一步继续往下看。 使用云之讯UI组件登陆云平台,需要使用token登陆,在实际的开发中,token 一般由开发者自己的服务器下发。如果开发者对token概念不理解,请点击云之讯token。

3、下载UIKit组件的SDK

如果您还未下载UIKit SDK或者想获取最新的SDK,请点击下载云之讯UIKIT SDK(下载地址

3.1、SDK目录讲解

从官网上下载下来的包中分为如下四部分:

1、USCIMkit.a        UI组件的使用的静态库,是对界面组件的封装包 
2、UCSIMKit.bundle:  包含静态库中要使用的图片、语音资源
3、Lib:              包含录音功能相关文件和emoj表情的plist文件和地图坐标信息转换的db文件
4、3rdParty:         UIKIT使用的第三方文件(避免重复引用冲突)
5、头文件说明:
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错误类型的定义类

4、SDK配置工程

4.1、新建工程

新建工程,为了方便演示,请选择创建一个 Empty Application 。如图所示:

4.2、导入UIKIT SDK

将下载好的UCSUIKit_SDK_v3.0.0.zip包解压到任意目录。在你的项目中中加入libucsimkit.a和头文件,在你的Resource目录中加入ucsimkitBundel.bundel(资源包),将lib文件夹和3rdParty文件夹 也拖到工程中。 生成的效果如图 2 导入UIKit SDK效果图所示:

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

生成的效果如下图所示: 注意:在Xcode7以上的编译器上,添加库时找不到以.dylib为后缀的库,将.dylib替换成.tdb就OK了。

4.4、配置编译选项

向Targets →Build Settings → Linking → Other Linker Flags 中添加【-ObjC】(注意大小写)

在工程的info.plist文件中,增加项 【Required background modes】,将该项的任意一个Item字段的值修改为 【App provides Voice over IP services】如图:

4.5、预编译SDK

新建一个预编译文件,将UCSUIKITSDK.h引入预编译文件中。如果工程中已经存在预编译文件,那么将UCSUIKITSDK.h引入该文件中。 预编译文件中需要加入以下两句代码:

#import <UIKit/UIKit.h>
#import <Foundation/Foundation.h>

编译整个工程,如果出现错误,请返回检查编译选项。

5、IOS UIKit SDK快速集成

5.1、初始化SDK

给核心单例传送root的控制器(root控制器是你设置管理IM通讯的控制,在选择好友页面,创建讨论组和单聊后的页面跳转)

MainVC = [[HomeViewControlleralloc] init];
_nav = [[BaseNavigationViewControlleralloc] initWithRootViewController:_MainVC];
_loginVC = nil;
[[UCSUIKitManagershareUCSUIKit] registeNotificationsWithRootController:_nav];

5.2、连接服务器

云之讯UIKit SDK的消息收发必须在和平台保持连接的情况下进行(离线推送除外),连接平台代码如下:

[[UCSUIKitManager shareUCSUIKit] connectWithToken:im_token success:^(NSString *userId) {
   [self connectionSuccessful:0];
} error:^(UCSConnectErrorCode status) {
   [self connectionFailed:-1];
}];

5.3、启动会话列表界面

启动会话的主要类是 ChatListViewController

ChatListViewController *chatList = [[ChatListViewControlleralloc]init];
[chatListsetNavigationTitle:@"会话列表" textColor:[UIColorwhiteColor]];
[self.navigationControllerpushViewController:chatListanimated:YES];

5.4、启动单聊会话界面

启动单聊的主要类是 ChatViewController (在demo中默认一个固定的chatter)

ChatViewController *chat= [[ChatViewController alloc]initWithChatter:@"15502019128" type:1];
[self.navigationController pushViewController:chat animated:YES];

5.5、启动邀请好友界面

邀请好友的主要类是 MultiSelectViewController (开发者可以自定义联系人,但如果需要聊天,改联系人必须经过云之讯鉴权)

MultiSelectViewController *multiSel= [[MultiSelectViewControlleralloc]initWithType:UCSelectTypeCreatetargetId:[[InfoManagersharedInfoManager]phone ]];

6、显示用户头像和昵称以及好友联系人

云之讯不维护和管理用户的基本信息(头像 id 、 昵称)的获取、缓存、变更和同步。所有的好友联系人的个人信息(比如昵称、头像)需要用户自己维护,UIKit SDK提供了相应的接口回调用户信息。

设计的原理: 设置用户的信息是通过代理协议来设置数据源(类似TableView的代理方式),开发者只要实现2个代理就能设置数据源(可参考Demo)。

/*!
 @protocol UCSIMUserInfoFetcherDelegagte
 用户信息的获取器。
 如果在聊天中遇到的聊天对象是没有登录过的用户(即没有通过云之讯服务器鉴权过的),IM 是不知道用户信息的,IM 将调用此 Delegagte 获取用户信息。
 */
@protocol UCSIMUserInfoFetcherDelegagte <NSObject>
/*!
 *  获取用户信息。
 *  @param userId     用户 Id。
 *  @param completion 用户信息
 */
- (void)getUserInfoWithUserId:(NSString *)userId completion:(void(^)(UCSUserInfo* userInfo))completion;
@end
 
/*!
 好友列表的获取器。
 云之讯 本身不保存 App 的好友关系,如果在聊天中需要使用好友关系时(如:需要选择好友加入群聊),UCSIMkit 将调用此 Delegagte 获取好友列表信息。
 */
@protocol UCSIMUserInfoDataSource <NSObject>
/*!
 获取好友信息列表。
 @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);
}

7、群信息头像和名称的自定义

云之讯群信息头像的的自定义和用户头像的自定义原理是一样的,需要开发者自己根据获取群的ID设置群的头像和名称。

设计的原理: 设置群信息是通过代理协议来设置数据源(类似TableView的代理方式),开发者只要实现2个代理就能设置数据源(可参考Demo)。

/*!
 @protocol UCSIMUserInfoFetcherGroupDelegagte
 群信息的代理
 */
@protocol UCSIMGroupInfoFetcherDelegagte <NSObject>
/*!
 *  获取某个群信息。
 *
 *  @param groupId     群 Id。
 *  @param completion  群信息
 */
- (void)getGroupInfoWithGroupId:(NSString *)groupId completion:(void(^)(UCSGroupInfo *groupInfo))completion;
@end
/*!
 群信息数据获取器。
 */
@protocol UCSIMGroupInfoDataSource <NSObject>
/*!
 获取群信息列表。
 @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);
 
}

8、UI的自定义

通过子类的继承的方式,重写父类方法来达到UI的自定义。从而自定义内容更广,形式更加简单。

会话列表界面、会话界面、邀请好友界面、聊天设置界面都继承BaseViewController。 可以被重写的方法如下:

/*!
 @brief  配置导航栏上
 */
-(void)configureNavigationBar;
 
/*!
 *  导航左面按钮点击事件
 */
- (void)leftBarButtonItemPressed:(id)sender;
 
/*!
 *  导航右面按钮点击事件
 */
- (void)rightBarButtonItemPressed:(id)sender;
 
/*!
 @brief  设置导航栏的标题的颜色和文字
 */
- (void)setNavigationTitle:(NSString *)title textColor:(UIColor*)textColor;

注意:BaseViewController中只有-(void)configureNavigationBar;这个方法。聊天界面、邀请好友界面以上方法都存在。

9、常见问题

Q:集成SDK后,头像不显示

A:检查是否正确实现了-(NSArray*)getFriends;这个代理方法。


页面工具