前言
本章节介绍移动用户反馈 iOS SDK的接入方法。
推荐工程使用cocoapods管理依赖。
当前SDK最新版本支持
iOS Deployment Target 7.0
及以上。用户反馈SDK支持 bitcode(bitcode仅在 Xcode7及以上显示并默认开启)。
用户反馈SDK及其依赖库均使用HTTPS协议进行加密传输。
准备工作
已创建项目和应用。具体操作请参见创建项目和应用。
第一步 将SDK集成到您的应用
我们提供了cocoapods引入依赖和本地依赖两种集成方式,方便您根据需要将SDK添加到您的应用中。
1. cocoapods引入依赖
1.1 指定Master仓库和阿里云仓库
移动用户反馈 iOS SDK和其他EMAS产品的iOS SDK,都是发布到阿里云EMAS官方维护的github仓库中,因此,您需要在您的Podfile文件中包含该仓库地址。
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/aliyun/aliyun-specs.git'
1.2 添加依赖
为您需要依赖HTTPDNS iOS SDK的target添加如下依赖。
target 'yourProjetName' do
# Comment the next line if you don't want to use dynamic frameworks
use_frameworks!
pod 'AlicloudFeedback', 'x.x.x'
end
示例依赖中的SDK版本号请以发布说明文档中的最新版本号为准。
1.3 安装依赖
在您的Terminal中进入Podfile所在目录,执行以下命令安装依赖。
pod install --repo-update
安装完成后,注意使用.xcworkspace
文件重新打开工程。
2. 本地手动集成依赖
2.1 下载依赖文件
从EMAS SDK列表选择移动用户反馈 iOS版本进行下载,解压得到多个framework
文件,如图示。
2.2 将framework文件添加到工程中
在Finder
中选中上述文件,拖入需要使用移动用户反馈 iOS SDK的target下,并在弹出框中勾选Copy items if needed
。
如果遇到 UTDID 冲突可参考:阿里云-云产品SDK UTDID冲突解决方案。
确认目的目录中包含YWFeedbackBundle.bundle
,以免造成返回箭头丢失的问题。
2.3 添加系统库依赖
在工程项目中(Build Phases -> Link Binary With Libraries)添加以下库依赖。
libz.tbd
libresolv.tbd
libsqlite3.tbd
CoreMotion.framework
CoreTelephony.framework
SystemConfiguration.framework
在Xcode7之前的版本,没有.tbd
的库,而是.dylib
。
最终效果如图示。
2.4 ObjC配置
iOS端集成SDK时需要做-ObjC
配置,即应用的 TARGETS -> Build Settings -> Linking -> Other Linker Flags ,需添加上 -ObjC
这个属性,如图示。
请注意 -ObjC
的大小写。
第二步 设置隐私权限
iOS 10及其以上版本对隐私权限更加严格,需要添加权限说明(privacy description)。如果不做设置,可能会导致崩溃、审核不通过等情况。设置如下:
在info plist中增加字段:
<key>NSCameraUsageDescription</key>
<string>使用相机</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>使用相册</string>
<key>NSMicrophoneUsageDescription</key>
<string>使用麦克风</string>
配置完后如图所示:
上图中的使用相机/使用相册/使用麦克风可修改。
如出现点击录音、拍照、相册闪退的情况,确认是否已添加权限说明。
第三步 使用SDK
1.下载SDK配置文件
在控制台应用管理页面,单击应用配置按钮,打开编辑配置右侧栏;在编辑配置右侧栏,单击下载Android/iOS应用配置按钮,下载App的配置文件
AliyunEmasServices-Info.plist
,如下图所示:Xcode中,把下载的
AliyunEmasServices-Info.plist
文件拖入对应App Target下即可,在弹出框勾选Copy items if needed
。
2.初始化SDK
在需要使用移动用户反馈的代码文件中引入头文件。
#import <YWFeedbackFMWK/YWFeedbackKit.h>
#import <YWFeedbackFMWK/YWFeedbackViewController.h>
调用自动初始化方法:
// 无需配置信息的初始化方法
- (instancetype)autoInit;
YWFeedbackKit *feedbackKit = [[YWFeedbackKit alloc] autoInit];
不要将YWFeedbackKit实例设置为局部变量,请持有YWFeedback实例,以免被提前释放。
由于YWFeedbackKit是个宏,实际上是BCFeedbackKit,所以在Swift中,请使用BCFeedbackKit。
3.打开反馈页面
调用 YWFeedbackKit 实例如下接口创建反馈界面:
/// @brief 创建反馈页面回调Block
/// @params viewController 反馈页面
/// @return error 调用失败返回错误
typedef void (^YWMakeFeedbackViewControllerCompletionBlock) (YWFeedbackViewController * viewController, NSError *error);
/// @brief 创建反馈页面,默认为不显示弹出错误信息
- (void)makeFeedbackViewControllerWithCompletionBlock:(YWMakeFeedbackViewControllerCompletionBlock)completionBlock;
创建成功后将会返回
YWFeedbackViewController
,你可以根据你App的实际结构,使用Present等不同的方式将其展示。如果不使用系统默认alert展示错误提示,或者想自行进行错误提示的多语言化,可以自定义提示方式,只需要实现这个block即可。具体可参考Demo。
/// @brief 反馈页面对外抛出Error的回调block。不设置此属性时,将使用默认Alert方式进行错误提示
/// @params viewController 反馈页面
/// @return error 失败error
@property (nonatomic, copy) void (^YWFeedbackViewControllerErrorBlock) (YWFeedbackViewController *viewController, NSError *error);
4.关闭用户反馈页面
在成功执行打开反馈页面后将获取到YWFeedbackViewController,设置属性closeBlock,当用户关闭用户反馈,将调用该block进行dismiss或pop。具体可参考 Demo 。
[viewController setCloseBlock:^(UIViewController *aParentController){
// 进行 dismiss 或者 pop,以及一些相关设置
[aParentController dismissViewControllerAnimated:YES completion:nil];
}];
5.获取反馈未读消息数
调用如下接口获取未读消息数:
/// @brief 反馈未读消息数回调Block
/// @params unreadCount 未读消息数
/// @return error 调用失败返回错误
typedef void (^YWGetUnreadCountCompletionBlock) (NSInteger unreadCount, NSError *error);
/// @brief 请求反馈未读消息数
- (void)getUnreadCountWithCompletionBlock:(YWGetUnreadCountCompletionBlock)completionBlock;
调用成功后返回反馈未读数,如果返回有未读反馈消息,可在反馈入口添加未读数等方式提醒用户进行查看。
6.设置业务方扩展的反馈信息和用户昵称(可选配置)
移动用户反馈SDK初始化后,可根据需要设置业务方扩展的反馈数据:
/// 业务方扩展反馈数据,可设置任意字段,在创建反馈页面前设置,可在后台扩展信息中查看
@property (nonatomic, strong, readwrite) NSDictionary *extInfo;
self.feedbackKit.extInfo = @{***:***};
设置用户昵称后,用户反馈信息时携带该昵称,最终会在反馈控制台会话中显示。
v3.3.5版本及以后可用。
/**
设置反馈用户名,请于SDK初始化完成后,在创建反馈页面前设置
(该用户名,可以在移动反馈控制台反馈会话中查看,用于标识用户)
@param nickName 反馈用户名
*/
- (void)setUserNick:(NSString *)nickName;
[self.feedbackKit setNickName:@"***"];
7.自定义UI
从v3.1.0版本开始增加了自定义UI的接口,包括导航栏字体、导航栏返回按钮的图标。
修改导航栏字体的API如下:
//YWFeedbackKit.h
/// @brief 如果不设置,默认为:`[UIFont boldSystemFontOfSize:13]`
@property (nonatomic, strong) UIFont *defaultCloseButtonTitleFont;
/// @brief 如果不设置,默认为:`[UIFont boldSystemFontOfSize:13]`
@property (nonatomic, strong) UIFont *defaultRightBarButtonItemTitleFont;
修改导航栏返回按钮图标的具体方法如下:
如果是手动集成,直接修改YWFeedbackBundle.bundle
里的图片即可,如果是通过CocoaPods方式集成,那么需要将YWFeedbackBundle.bundle
命名为Customized.YWFeedbackBundle.bundle
,并修改Customized.YWFeedbackBundle.bundle
内部的图片,然后拖拽到您自己的工程项目中即可。
SDK Demo
移动用户反馈 iOS SDK接入工程样例参见Demo
常见错误码
错误码 | 含义 |
103 | 没有加-ObjC,Category没有加载上来。 |