iOS SDK 4.x 开发指南

微客服致力于为开发者提供极致用户体验的多渠道在线客服系统,包括 App、微信、web/h5等. 官网SDK下载.

重要

注:最新版sdk支持https, 支持ipv6, 兼容iOS 10

注解

个别地区会因为移动运营商的原因造成域名解析错误, 从而无法连接普通服务器, 所以需要使用ip服务器. SDK端需要开启ipServer模式, 同时客服也需要登录ip服务器. 开始ipServer模式: [[AppKeFuLib sharedInstance] enableIPServerMode:true]; 登录普通服务器: [[AppKeFuLib sharedInstance] enableIPServerMode:false];

一. 创建App

  1. 登录 管理后台,到 我的应用 页面,点击 创建应用 并保存
  2. App创建成功后,获取 Appkey, 填写到App的相应位置
  3. 创建工作组, 并将相应的客服工作组ID填写到 App 中相应的位置
  4. 分配客服,使用分配的客服账号登录 PC客服端下载

小技巧

说明:在新的应用创建过程中,请尽量填写准确的信息,便于我们为您提供更加周到的服务

二. 下载SDK

在这里 SDK下载, 内含SDK和Demo, iOS SDK支持发送 文字、表情、图片、语音
_images/chat_list1.png _images/chat_buy1.png _images/chat_face.png _images/chat_voice1.png _images/chat_robot1.png _images/chat_rate1.png _images/chat_faq1.png _images/chat_tag.png

三. 开发步骤

  1. 添加客服库文件:

    1. 添加库文件:libAppKeFuLib.a
    2. 添加资源文件:AppKeFuResources.bundle
    3. 添加头文件:AppKeFuLib.h
  2. 添加依赖库文件:

    1. libxml2.dylib(或者Xcode7: libxml2.tbd)
    2. libresolv.dylib(或者Xcode7: libresolv.tbd)
    3. SystemConfiguration.framework
    4. CoreLocation.framework
    5. CoreData.framework
    6. AVFoundation.framework
    7. AudioToolbox.framework
    8. libiconv.dylib(或者Xcode7: libiconv.tbd) (仅模拟器运行时需要)
  3. Building Settings:

    选中target中的Build Settings:

    1. Other Linker Flags 添加 -all_load -lstdc++

      小技巧

      注:或者使用 -force_load “libAppKeFuLib.a的路径” 代替-all_load,例如demo中:-force_load $(SRCROOT)/AppKeFuDemo2/AppKeFuLib/libAppKeFuLib.a

    2. (可选).Header Search Paths 添加 “/usr/include/libxml2”

  4. 国际化

    1. 首先请对项目做国际化设置,具体步骤可以百度 ios 国际化设置
    2. 拷贝Demo中的 Localizable.strings文件内容,到项目相应文件内
  5. 离线消息推送

    1. 生成.pem文件
    2. 在管理后台应用的详情页面上传.pem文件(pem生成步骤请参考文档最下方:五.pem生成步骤)
    3. 注册离线消息推送代码配置
  6. 常见问题FAQ模块:

    此模块位于SDK会话页面,”发送照片的旁边”,其中的内容需要在管理后台添加

    1. 进入工作组详情页面
    2. 找到 常见问题类别 模块
    3. 首先添加”常见问题类别”,然后为每个类别添加”常见问题”
  7. 自定义菜单:

    后台随时设定自定义菜单,方便用户通过SDK内嵌的浏览器跳转到指定的网页,为用户提供更加便捷的服务

    1. 在管理后台“工作组详情”页面创建 自定义菜单
    2. 在SDK设置相应的参数
  8. 机器人自动应答:

    通过添加机器人自动应答问题,可以有效的提高客服的工作效率

    1. 在管理后台“工作组详情”页面找到“机器人自动应答”
    2. 添加相应的问题和答案
  9. 针对iOS9 http访问:(最新版本已经支持https, 可忽略此步骤)

    在ios9中需要在Info.plist中如下配置:

    1. 在Info.plist中添加NSAppTransportSecurity类型Dictionary
    2. 在NSAppTransportSecurity下添加NSAllowsArbitraryLoads类型Boolean,值设为YES或者添加白名单域名: www.appkefu.com
    _images/ios9_http_settings.jpg
  10. 针对iOS9-XCode7:Xcode setting ENABLE_BITCODE设置:

    Build Settings -> Build Options -> Enable Bitcode 设置为 No, 如下图所示:

    _images/ios9_bitcode.gif
  11. iOS 10 升级适配:

    在info.plist里面添加:

    1. 访问相册 key: NSPhotoLibraryUsageDescription, Type: String, Value: $(PRODUCT_NAME) 想要访问照片库
    2. 访问相机 key: NSCameraUsageDescription, Type: String, Value: $(PRODUCT_NAME) 想要使用摄像头
    3. 访问麦克风 key: NSMicrophoneUsageDescription, Type: String, Value:$(PRODUCT_NAME) 想要使用麦克风

    添加完毕后, 效果如图:

    _images/ios10.png
  12. 配置代码:

    第一步: 在AppDelegate.m中如下配置

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
           self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
           // Override point for customization after application launch.
           ViewController *sampleViewController = [[ViewController alloc] init];
           self.navigationController = [[UINavigationController alloc] initWithRootViewController:sampleViewController];
           self.window.rootViewController = self.navigationController;
           [self.window makeKeyAndVisible];
           //步骤一:初始化操作
           [[AppKeFuLib sharedInstance] loginWithAppkey:APP_KEY];
           //步骤二:注册离线消息推送
           [[UIApplication sharedApplication] registerForRemoteNotificationTypes: UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound | UIRemoteNotificationTypeAlert];
           return YES;
    }
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    #pragma mark 离线消息推送
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
           //步骤三:同步deviceToken便于离线消息推送, 同时必须在管理后台上传 .pem文件才能生效
           [[AppKeFuLib sharedInstance] uploadDeviceToken:deviceToken];
    }
    - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo{
           NSLog(@"收到推送消息。这里主要起到通知的作用,用户进入应用后,服务器会再次推送即时通讯消息");
    }
    - (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
           NSLog(@"注册推送失败,原因:%@",error);
    }
    - (void)applicationDidEnterBackground:(UIApplication *)application
    {
           // Use this method to release shared resources, save user data, invalidate timers, and store enough application state information to restore your application to its current state in case it is terminated later.
           // If your application supports background execution, this method is called instead of applicationWillTerminate: when the user quits.
           //苹果官方规定除特定应用类型,如:音乐、VOIP类可以在后台运行,其他类型应用均不得在后台运行,所以在程序退到后台要执行logout登出,
           //离线消息通过服务器推送可接收到
           //在程序切换到前台时,执行重新登录,见applicationWillEnterForeground函数中
           //步骤四:
           [[AppKeFuLib sharedInstance] logout];
    }
    - (void)applicationWillEnterForeground:(UIApplication *)application
    {
           // Called as part of the transition from the background to the inactive state; here you can undo many of the changes made on entering the background.
           //步骤五:切换到前台重新登录
           [[AppKeFuLib sharedInstance] loginWithAppkey:APP_KEY];
    }
    

四. API接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//请在使用前务必阅读README.md文件
//详细使用文档: http://admin.weikefu.net/AppKeFu/tutorial-iOS3.html
//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//登录成功通知
#define APPKEFU_LOGIN_SUCCEED_NOTIFICATION          @"appkefu_login_succeed_notification"
//客服工作组在线状态
#define APPKEFU_WORKGROUP_ONLINESTATUS              @"appkefu_workgroup_online_status"
@interface AppKeFuLib : NSObject
//1. 获取AppKeFuLib单例
+(AppKeFuLib *)sharedInstance;
//2.登录, appkey需要开发者到 http://admin.weikefu.net 申请
-(void)loginWithAppkey:(NSString *)appkey;
//2.1第二种登录方式. 开发者可自定义username,其中:username长度>=6
-(void)loginWithUsername:(NSString *)username withAppkey:(NSString *)appkey;
//3. 注销,退出登录
-(void)logout;
//4. 显示会话窗口
- (void)pushChatViewController:(UINavigationController *)navController
withWorkgroupName:(NSString *)workgroupName   //1. 需要填写 工作组名称,需要到管理后台申请,注意:不是客服用户名,而是工作组名称,支持多客服
hideRightBarButtonItem:(BOOL)hideRightBarButtonItem //2. 隐藏会话页面右上角按钮, 隐藏: YES, 显示: NO
rightBarButtonItemCallback:(void (^)())rightBarButtonTouchUpInsideCallback  //3. 会话页面右上角按钮回调函数;注意:VIP接口,需要另行开通
showInputBarSwitchMenu:(BOOL)shouldShowInputBarSwitchMenu               //4. 在会话窗口显示自定义菜单, 类似于微信的自定义菜单;
//      如果需要显示自定义菜单,请首先到管理后台分配自定义菜单,请分配且只分配三个自定义菜单,多于三个的自定义菜单将不予显示。
//      显示: YES, 不显示: NO
withTitleView:(UILabel *)titleView  //5. 自定义会话窗户标题
withProductInfo:(NSString *)productInfo//6. 成功连接客服之后,自动将此消息发送给客服,如果不需要发送此信息, 可将其设置为 nil 或者 ""
withLeftBarButtonItemColor:(UIColor *)color   //7. 导航左上角“结束会话”按钮颜色
hidesBottomBarWhenPushed:(BOOL)shouldHide  //8. 从具有Tabbar的viewController打开的时候,隐藏tabbar
showHistoryMessage:(BOOL)isShow     //9. 是否显示历史聊天记录,显示:YES, 不显示:NO
defaultRobot:(BOOL)defaultRobot//10. 默认机器人自动应答, 亦可呼叫人工客服,开启机器人: YES, 人工客服: NO
withKefuAvatarImage:(UIImage *)kefuAvatarImage //11. 替换默认客服头像, 设为nil则保留默认头像
withUserAvatarImage:(UIImage *)userAvatarImage;//12. 替换默认用户头像, 设为nil则保留默认头像
//4.1
-(void)presentChatViewController:(UIViewController *)navController
withWorkgroupName:(NSString *)workgroupName
hideRightBarButtonItem:(BOOL)hideRightBarButtonItem
rightBarButtonItemCallback:(void (^)())rightBarButtonTouchUpInsideCallback
showInputBarSwitchMenu:(BOOL)shouldShowInputBarSwitchMenu
withTitleView:(UILabel *)titleView
withProductInfo:(NSString *)productInfo
withLeftBarButtonItemColor:(UIColor *)color
hidesBottomBarWhenPushed:(BOOL)shouldHide
showHistoryMessage:(BOOL)isShow
defaultRobot:(BOOL)defaultRobot
withKefuAvatarImage:(UIImage *)kefuAvatarImage
withUserAvatarImage:(UIImage *)userAvatarImage;
//5.查询工作组当前在线状态,如果工作组内客服至少有一个客服账号在线,则显示在线。否则,显示离线
-(void) queryWorkgroupOnlineStatus:(NSString *)workgroupname;
//5.1 发送消息,会话页面聊天记录可见
-(void) sendTextMessage:(NSString *)content toWorkgroupname:(NSString *)workgroupName;
//5.2 发送消息,但不会显示在会话页面聊天记录里面
-(void) sendBackgroundMessage:(NSString *)content toWorkgroupname:(NSString *)workgroupName;
//函数6:设置用户标签昵称
- (NSString *)getTagNickname;
//函数7:获取用户标签昵称
- (void) setTagNickname:(NSString *)nickname;
//函数8:设置用户标签性别
- (NSString *)getTagSex;
//函数9:获取用户标签性别
- (void) setTagSex:(NSString *)sex;
//函数10:设置用户标签语言
- (NSString *)getTagLanguage;
//函数11:获取用户标签语言
- (void) setTagLanguage:(NSString *)language;
//函数12:设置用户标签城市
- (NSString *)getTagCity;
//函数13:获取用户标签城市
- (void) setTagCity:(NSString *)city;
//函数14:设置用户标签省份
- (NSString *)getTagProvince;
//函数15:获取用户标签省份
- (void) setTagProvince:(NSString *)province;
//函数16:设置用户标签国家
- (NSString *)getTagCountry;
//函数17:设置用户标签国家
- (void) setTagCountry:(NSString *)country;
//函数18:设置用户标签其他
- (NSString *)getTagOther;
//函数19:获取用户标签其他
- (void) setTagOther:(NSString *)other;
//函数20:上传DeviceToken,用于离线消息推送
- (void) uploadDeviceToken:(NSData *)deviceToken;
@end

五. pem生成步骤

六. 其他

提示

更新日期:2017/11/22, 技术交流QQ群:474794719