首页 帮助中心 听云App iOS平台

听云iOS平台SDK安装

1 简介

iOS SDK探针支持如下数据采集：
  • Http/Https协议数据收集
  • 崩溃/ANR异常数据收集
  • 事件性能数据收集
  • 视图性能数据收集
  • 进程内存和CPU使用率
iOS SDK探针支持如下协议类库：
  • NSURLConnection / NSURLSession(目前SDK支持iOS 8以上的系统)
  • ASI
  • AFN(基于NSURLConnection)
  • WebView
  • WKWebView（支持iOS 11及其以上系统）
iOS SDK探针支持如下系统版本：
  • iOS 7.0版本及其以上版本
iOS SDK通过在指定的方法中嵌码的方式来采集下列指标数据：
  • 应用响应时间
  • DNS解析时间
  • TCP建连时间
  • SSL握手时间
  • 首包时间
iOS SDK探针也可以采集线程堆栈，数据库、自定义参数和HTTP请求参数。
iOS SDK 2.7.0版本不支持iOS 10.2(不含10.2)以下的Webview页面性能数据采集。
iOS SDK 2.8.1版本appStarts启动时间性能数据采集只支持在main函数中嵌码。

1.1 iOS SDK目录结构

  • tingyunApp.framework

1.2 iOS SDK Theory

/*
 * swizzle过后，imageName指向的是nbs_imageName函数的实现，当在调用imageName这个函数时，会首先调用nbs_imageNamed的实现，
 * 而此时nbs_imageName指向的是原函数imageName的实现，所以在nbs_imageNamed的实现中通过[self nbs_imageNamed:name]回调回原函数
 */
+ (UIImage *)nbs_imageNamed:(NSString *)name
{
nbs_embedIn_start(nil,category_image,classNameOf(self),NSStringFromSelector(_cmd),currentViewController, timeNow());//SDK开始数据采集
    id rtn= [self nbs_imageNamed:name];//调用原函数实现
    nbs_embedIn_finish(argsHelper);//SDK完成数据采集
    return rtn;
}

利用objective-c的runtime特性,通过Method swizzle技术,可以实现在运行时替换 selector 对应的方法实现,达到 给方法挂钩的目的。也就是说,嵌入基调的 SDK 后,在程序启动之初，基调的SDK会对相应的方法执行swizzle操作，从而在调用一个被swizzle过后的函数时，将会首先调用SDK相应的自定义函数，在SDK的函数中会执行一些数据采集的操作，然后SDK的函数会再调回原函数的实现,不会影响原程序逻辑。

iOS SDK 体积增量

三种指令架构增加 2.31M

  • Armv7 增加 0.72M
  • Armv7s 增加0.72M
  • Arm64增加0.86M

2、iOS SDK 部署

2.1、安装 iOS SDK

2.1.1、通过Framework 部署 iOS SDK

1、下载听云App iOS SDK：

nbs-newlens-ios.zip

2、在解开的文件夹中，选择“tingyunApp.framework”文件夹，并将其拖动到需要进行监测的iOS App的Xcode项目中

3、在Xcode中，选择Project Navigator窗口，将拖动的文件夹图标放到“HelloWorld”文件夹组下。

4、当Xcode弹出提示时，选择“Copy items into destination group’s folder”和“Create folder references for any added folders”选项，并确认。

5、选择Build Setting，搜索Other Linker Flags，增加编译标志-ObjC

6、在待监测的iOS App项目的链接设置中增加以下5个库，在Xcode的Project Navigator窗口中选中待监测App项目：
a) 在Target中选中对应的App；
b) 切换到“Build Phases”设置页面；
展开“Link Binary With Libraries”设置项，点击“+”号进入增加库的窗口

增加以下五个库：
库名 作用
libz.tbd 解压缩
WebKit.framwork 浏览器内核
Security.framework 访问钥匙链
CoreTelephony.framework 获取运营商
SystemConfiguration.framework 获取网络状态

2.1.2、通过CocoaPods 部署iOS SDK

在待检测项目工程目录的Podfile文件中添加如下命令：

pod 'tingyunApp'

2.1.3、通过Carthage 部署iOS SDK

在待检测项目工程目录的Cartfile文件中添加如下命令：

github "TingYunAPM/TingYunApp"

2.2、插入初始化SDK代码

注释：Xcode 6之后，创建工程时不会自动创建pch文件，需要自己创建。
Swift工程请在对应的Bridging-Header.h文件中导入头文件。

1、在待监测App的pch文件中引入听云App探针的头文件：

 #import <tingyunApp/NBSAppAgent.h>

2、Swift引入头文件

 #ifndef testswift__Bridging_Header_h
 #define testswift__Bridging_Header_h
 #import <tingyunApp/NBSAppAgent.h>
 #endif /* testswift__Bridging_Header_h */

3、在嵌码项目工程Supporting Files/main.m文件的main函数中添加以下代码：

[NBSAppAgent startWithAppID:@"YOUR_AppKey"];

4、Swift工程请在AppDelegate.swift文件的application:didFinishLaunchingWithOptions函数中添加以下代码：

NBSAppAgent.startWithAppID("YOUR_APPKEY");

若项目并未创建pch文件，请按如下配置创建

（1）打开Xcode，依次选择File→New→File（或者⌘N）

（2）在弹出的对话框中选择Other，然后选择PCH File

（3）点击Next，然后输入“pch”的文件名，格式一般为“工程名-Prefix”

（4）选中工程→TARGETS→Build Settings，找到Apple LLVM 6.0-Language，其中有一项Prefix Header，双击它，然后输入“工程名/pch文件名”，到这里pch文件就设置完成了

2.3、添加URL Scheme

将URL Scheme添加到项目中，以便我们唤醒您的应用，进行可视化操作命名。

URL Scheme获取

登录控制台，进入APP概览页 –> 点击小齿轮 –> 点击修改设置，进入到修改设置详情页面，URL Scheme就在appkey下面，格式为：tingyun.appid。

URL Scheme配置


将获取到的URL Scheme添加到target –> info –> URL Types 。

2.4、嵌码完整性校验

　运行嵌码完成后的项目工程，连接电脑使用Devices查看log日志

　　出现如下log表示嵌码成功：

NBSAppAgent “TingYun_Version”
---->start!
Success to connect to NBSSERVER

3、高级功能

3.1 用户自定义ID

1、功能说明

用户自定义ID为当前用户设置唯一标示码，在任意位置均可设置UserID。

2、相关接口

[NBSAppAgent startWithAppID:@“Appkey"];
[NBSAppAgent setUserIdentifier:@“userID"];

3、代码示例

[NBSAppAgent setUserIdentifier:@“test_uid”];//空串代码示例

-(void)viewDidLoad{
[super viewDidLoad];
[NBSAppAgent setUserIdentifier:”UserIdentifier”];//设置自定义Id,可为邮箱等标识用户身份的信息，如xxx@tingyun.com
}

3.2 面包屑

1、功能说明

面包屑能够更好的协助用户调查崩溃发生的原因，可以知晓用户发生崩溃之前的代码逻辑与崩溃轨迹结合使用能够更好的复现用户崩溃场景。

2、相关接口

//最多包含100个字符，支持中文、英文、数字、下划线，但不能包含空格或其他的转义字符
[NBSAppAgent leaveBreadcrumb:@"keyPressed”];
[NBSAppAgent leaveBreadcrumb:@"loginDone"];

3、代码示例

-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOption:(NSDictionary *)launchOptions
{
[NBSAppAgent leaveBreadcrumb:@“didFinishLaunchingWithOptions”];设置面包屑
return YES;
}

3.3 自定义Event

1、功能说明

自定义事件用于统计App中的任意事件，开发者可以在SDK初始化后的任意位置添加自定义事件，并设置对应上传参数。如：真实用户操作时候点击某个功能按钮或触发了某个功能事件等。

2、相关接口

//EVENT_ID最多包含32个字符，支持中文、英文、数字、下划线，但不能包含空格或其他的转义字符
[NBSAppAgent trackEvent:@”EVENT_ID”];

3、代码示例

-(void)purchaseFailedCallback
{
[NBSAppAgent trackEvent:@“购买失败”]；
} 

3.4 自定义Trace

注意：

由于自定义Trace是成对出现的，请勿跨方法、跨进程以及在异步加载和递归调用中使用该接口。

1、功能说明

听云SDK默认采集系统类和方法的性能数据，无法采集开发者自定义类和方法的性能数据。使用“自定义Trace”接口就可以帮助开发者时刻了解所写代码的健壮性及其性能数据。如：开发者想要了解某个自定义方法的初始化耗时及性能消耗情况，就可以在该自定义方法前后添加“自定义Trace”接口即可。

2、相关接口

//Name 为当前方法所在方法名或自定义名称，支持中文、英文、数字、下划线，但不能包含空格或其他的转义字符
beginTracer(@“StringName")
endTracer(@“StringName")

3、代码示例

//用户可以在SDK初始化后的任意方法前后添加自定义Trace
- (void)doSomething
 {
  beginTracer(@“StringName")
 //write you code here
 
 endTracer(@“StringName")
}

3.5 自定义附加信息

1、功能说明

  用户可以在初始化之后任意位置配置该接口，最多可添加10条附加信息，每条附加信息最大支持100个字节随崩溃上传。

2、相关接口

NBSAppAgent setCustomerData:(NSString*)data forKey:(NSString*)key;

3、代码示例

-(void)sigabrtCrash{
    
    [NBSAppAgent setCustomerData:@"这里是sigabrt" forKey:@"sigabrt"];
    id obj = @"123";
    [obj addSubview:self.view];

}

4、Crash 符号化

　　为了更好的帮助用户解析崩溃信息,我们提供了符号化机制来帮助用户快速精准的定位崩溃发生位置。当您使用符号化制时,您需要上传当前版本的“dSYM”文件到听云服务器。

4.1、查找符号表

i. 打开已嵌码项目工程，点击菜单栏中的“Window”选择“Organizer”

ii. 选择“Archives”，找到目标工程右击选择“Show in Finder”进入文件目录

iii. 右击“.xcarchive”文件，选择“显示包内容”

iv. 选择对应的“.app.dSYM”文件，如：“HelloWorld.app.dSYM”，右击“显示包内容”

v. 找到项目的符号表文件，这里为“HelloWorld” 

注：上图标注部分为符号表文件，上传时请上传该文件而不是xxx.app.dSYM这个目录

4.2、上传对应版本的dSYM文件

4.2.1、通过Xcode + sh脚本上传dSYM文件

（1）将解压后SDK包中tingyun.sh的内容贴入到上图中第6步的位置。

（2）配置好对应的AUTH_KEY和APP_KEY。

4.2.2、通过报表手动上传dSYM文件

（1）登陆听云报表，在App概览中选择嵌对应的App名称，进入App后选择左侧菜单栏中的“崩溃”按钮：

（2）在右侧“崩溃历史记录列表”中选择并点击“dSYM / Mapping 文件管理”，如下图所示：

（3）在弹出窗口中选择上传平台类型，如：“iOS”。选择对应的应用版本号，并点击右侧上传按钮，手动上传符号表。如下图所示：

4.2.3、命令行上传符号表

（1）打开终端，进入“HelloWorld.app.dSYM”目录（目录位置见方法1的描述），输入如下命令：

curl -k -F upload=@HelloWorld
https://mobile-symbol-upload.tingyun.com/symbol/authkey/AUTH_KEY/appkey/APP_KEY

（2）命令行参数配置：

HelloWorld =符号表名称

AUTH_KEY: 听云API账号授权Key，由报表系统生成（参考附录1）

APP_KEY: 听云App授权Key（参考附录2）

（3）上传符号表

　　配置完成后即可通过命令行上传符号表到听云服务器，出现Success说明上传成功

{

"status" : "success",

"msg" : "success"

}

附录

1、配置AuthKey授权码

i. 登陆报表，选择用户名称，点击修改授权码

ii. 选择“当前授权码” 复制到上传URL中

2、配置AppKey

i.登陆报表，在App概览中选择嵌对应的App名称，如：iOS_SDK。点击左侧配置按钮，选择“修改设置”

ii. 进入“修改配置”后，找到“安装SDK”选择“App Key”复制到上传URL中