文档

iOS SDK接入

更新时间:

前言

本章节介绍移动用户反馈 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文件,如图示。

文件.png

2.2 将framework文件添加到工程中

Finder中选中上述文件,拖入需要使用移动用户反馈 iOS SDK的target下,并在弹出框中勾选Copy items if needed

image

如果遇到 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

最终效果如图示。

yinru.png

2.4 ObjC配置

iOS端集成SDK时需要做-ObjC配置,即应用的 TARGETS -> Build Settings -> Linking -> Other Linker Flags ,需添加上 -ObjC 这个属性,如图示。

image.png

重要

请注意 -ObjC的大小写。

第二步 设置隐私权限

iOS 10及其以上版本对隐私权限更加严格,需要添加权限说明(privacy description)。如果不做设置,可能会导致崩溃、审核不通过等情况。设置如下:

在info plist中增加字段:

<key>NSCameraUsageDescription</key>
<string>使用相机</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>使用相册</string>
<key>NSMicrophoneUsageDescription</key>
<string>使用麦克风</string>

配置完后如图所示:

权限.png

重要

  • 上图中的使用相机/使用相册/使用麦克风可修改。

  • 如出现点击录音、拍照、相册闪退的情况,确认是否已添加权限说明。

第三步 使用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没有加载上来。