集成和初始化

最近更新时间:2024-06-28 17:59:51

我的收藏

SDK 集成

手动集成
1. 下载 SDK。
2. 拖拽 QAPM.framework 文件到 Xcode 工程内(请勾选Copy items if needed 选项)。
3. 在 TARGETS > Build Phases-Link Binary Libraries 添加依赖库:
libc++.dylib (libc++.tbd)
libz.dylib (libz.tbd)
libresolv.tbd
4. 在工程的 Other LinkerFlags 中添加-ObjC参数。
5. 导入配置文件:
5.3.5之前的版本将 framework 里面的 js_sdk.js 文件导入到工程根目录;
5.3.5及以后的版本将 framework 里面的 QAPMResourceFile.bundle 文件导入到工程根目录。
cocoaPods 集成
在 podfile 文件中增加如下操作,然后执行 pod install 指令:
pod 'QAPM',:source => 'https://github.com/TencentCloud/QAPM-iOS-CocoaPods.git'
注意:
iOS SDK 最低兼容系统版本 iOS 8.0。

Web 端环境配置

登录 腾讯云可观测控制台,在终端性能监控页面,选择应用管理 > 应用设置,进入应用设置后,获取 Appkey(上报 ID)。



SDK 初始化

1. 在工程的 AppDelegate.m 文件导入头文件:#import <QAPM/QAPM.h>,如果是 Swift 工程,请在对应bridging-header.h中导入。
2. 初始化 QAPM 在工程 AppDelegate.m 的 application:didFinishLaunchingWithOptions 方法中初始化

void loggerFunc(QAPMLoggerLevel level, const char* log) {

#ifdef RELEASE
if (level <= QAPMLogLevel_Event) { ///外发版本log
NSLog(@"%@", [NSString stringWithUTF8String:log]);
}
#endif
#ifdef GRAY
if (level <= QAPMLogLevel_Info) { ///灰度和外发版本log
NSLog(@"%@", [NSString stringWithUTF8String:log]);
}
#endif
#ifdef DEBUG
if (level <= QAPMLogLevel_Debug) { ///内部版本、灰度和外发版本log
NSLog(@"%@", [NSString stringWithUTF8String:log]);
}
#endif
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//为响应工信部 “26号文” 要求,提供该设置用于告知SDK是否可以进行可选个人信息的采集,该设置需要最先配置,一旦设置则全局生效。默认设置为YES,代表可以采集;设置为NO则不采集,可能会影响到前端的搜索、展示等
//可选个人信息包括但不限于以下信息:设备制造商、系统、运营商等等,详见 《QAPM SDK 合规使用指南》
[QAPMConfig getInstance].collectOptionalFields = YES;

//
该设置默认为NO
,若需要开启全链路监控功能请设置为YES,QAPM的SDK网络监控数据中的个例数据和腾讯云可观测平台的应用性能监控的全链路数据将会打通,另外业务方需要注意:
// 业务网络请求的requestHeader会增加sw8、traceparent相关协议下的value值,如果业务自行组建了全链路监控则可以设置为NO
[QAPMConfig getInstance].isOpenTrace = NO;

/// 设置QAPM 日志输出
NSLog(@"qapm sdk version : %@", [QAPM sdkVersion]);
[QAPM registerLogCallback:loggerFunc];


//上报地址
//国内站:https://app.rumt-zh.com //国际站:https://app.rumt-sg.com [QAPMConfig getInstance].host = @"https://app.rumt-zh.com";
[QAPMConfig getInstance].host = @"https://app.rumt-sg.com";
[QAPMConfig getInstance].customerAppVersion = @"设置app自定义版本号";
//根据实际情况设置userid 和deviceID
//设备唯一标识deviceID,例如IDFV配合Keychain使用
[QAPMConfig getInstance].userId = @"设置userId";
[QAPMConfig getInstance].deviceID = @"自定义deviceId";
/// 启动QAPM
[QAPM startWithAppKey:@"产品唯一的appKey"];
return YES;
}
注意:
研发流程内,可以将设置的用户 ID /设备 ID 添加成白名单,确保指定设备的功能上报不会被采样影响,可在 终端性能监控控制台 通过应用管理 > 白名单管理 > 白名单配置 > 添加完成操作。

监控功能启用

推荐使用:
QAPMModelStableConfig.h文件中的接口:- (void)setupModelAll; //此接口可开启全部监控功能。
QAPMModelStableConfig.h文件中接口:- (void)setupModelStable;//此接口可开启除了网络监控和用户行为监控之外的所有监控功能,网络监控与用户行为监控按照工信部26号文要求划分为扩展业务功能,您可根据自身需要选择是否开启。
自定义使用:
如果要自定义开启 QAPM 功能(包括卡顿、crash、原生网络、原生用户行为、启动、webview),可在QAPMConfig.h文件中的enableMonitorTypeOptions接口,设置组合的枚举值,添加多个参数枚举值完成一系列功能的开启,代码如下:
// 设置QAPM 开启的监控:
[QAPMConfig getInstance].enableMonitorTypeOptions =
QAPMMonitorTypeBlue |
QAPMMonitorTypeCrash |
QAPMMonitorTypeHTTPMonitor |
QAPMMonitorTypeIUPMonitor|
QAPMMonitorTypeLaunch |
QAPMMonitorTypeJSError |
QAPMMonitorTypeWebViewNetWork |
QAPMMonitorTypeWebViewIUPMonitor |
QAPMMonitorTypeWebMonitor;
接口说明:
接口:QAPMConfig.h类中@property (nonatomic, assign) QAPMMonitorType enableMonitorTypeOptions;
参数说明:QAPMMonitorType类型为功能类型,可选值为如下:

可选项说明
///检测卡顿功能
QAPMMonitorTypeBlue
/// Crash监控功能
QAPMMonitorTypeCrash
///原生网络监控
QAPMMonitorTypeHTTPMonitor
///原生用户行为监控
QAPMMonitorTypeIUPMonitor
/// 启动个例监控功能
QAPMMonitorTypeLaunch
/// webview的JS异常监控
QAPMMonitorTypeJSError
///webview的网络
QAPMMonitorTypeWebViewNetWork
///webview 用户行为监控
QAPMMonitorTypeWebViewIUPMonitor
/// webview页面性能监控
QAPMMonitorTypeWebMonitor
注意:
1. 使用或运算方式自定义开启所需监控功能,如卡顿:QAPMMonitorTypeBlue
2. 为响应工信部 “26号文” 要求,我们依据工信部对性能监控类 SDK 基础功能的定义,将网络监控与用户行为监控划分为
扩展业务功能
,这意味着为了避免采集网络日志信息、用户操作记录等个人信息,您可以选择性开启这两个功能。操作层面您可以在自定义性能模块开启配置中避免填入QAPMMonitorTypeHTTPMonitorQAPMMonitorTypeWebViewNetWork两个参数,以关闭网络监控功能;以此类推,您可以在自定义性能模块开启配置中避免填入QAPMMonitorTypeIUPMonitorQAPMMonitorTypeWebViewIUPMonitor两个参数,以关闭用户行为监控功能,或直接使用 ModelStable 功能开启模式以在确保关闭所有扩展业务功能的情况下自动开启其他推荐功能。

SDK 功能介绍

卡顿及流畅度监控功能

卡顿检测功能
QAPMMoniterType:QAPMMonitorTypeBlue 卡顿检测将在卡顿时,卡顿时间超过200ms阈值则采集堆栈进行立即上报。
流畅度监控功能
在滑动场景下相关页面进行如下代码的打点即可开始统计流畅度,日志会在下次启动 App 后上报数据。
#pragma mark - TableView Delegate
- (void)scrollViewWillBeginDragging:(UIScrollView *)scrollView {
[QAPMBlueProfile beginTrackingWithStage:NSStringFromClass([self class])];
}

- (void)scrollViewDidEndDragging:(UIScrollView *)scrollView willDecelerate:(BOOL)decelerate {
if(!decelerate){
[QAPMBlueProfile stopTrackingWithStage:NSStringFromClass([self class])];
}
}

- (void)scrollViewDidEndDecelerating:(UIScrollView *)scrollView {
[QAPMBlueProfile stopTrackingWithStage:NSStringFromClass([self class])];
}

Crash 监控功能

QAPMMonitorTypeCrash Crash 日志会在下次启动 SDK 后上报数据。
注意:
1. 业务方如果使用了第三方 SDK 收集普通崩溃的功能请卸载掉第三方监控软件,避免出现上报堆栈不准的问题。
2. 在 FOOM 与 deadlock 卡死退出后,将在下次启动上报上一次记录的相关堆栈信息。FOOM 在 debug 或者非 App Store 全量上报,App Store 环境下数据会有2%的采样抽样。

启动耗时监控功能

功能说明
使用启动耗时监控功能,可以统计出 App 进程创建时间到 App 第一帧 UI 上屏的时间。
当启动时间超过阈值(默认4000ms),则会上报个例详情。个例详情包括启动耗时、自动打点区间、自定义打点区间和启动过程堆栈。
相关接口
@interface QAPMLaunchProfile : NSObject
/**
设置自定义打点区间开始,该区间需要在启动时间区间内。begin与end的scene需要一致。
@param scene 场景名
*/
- (void)setBeginTimestampForScene:(NSString *)scene;
/**
设置自定义打点区间结束,该区间需要在启动时间区间内。begin与end的scene需要一致。
@param scene 场景名
*/
- (void)setEndTimestampForScene:(NSString *)scene;
@end
代码示例
在工程对应的类里面导入头文件#import <QAPM/QAPMLaunchProfile.h>
在 main 函数进行启动监控组件:
int main(int argc, char * argv[]) {

@autoreleasepool {
[QAPMLaunchProfile didEnterMain];

return UIApplicationMain(argc, argv, nil, NSStringFromClass([AppDelegate class]));
}
}

Web 监控功能

说明:
1. 目前 WKWebView 支持 iOS ≥ 11 。
2. 该功能能够监控 Web 网络资源加载耗时、jserror 监控。
功能配置
Web 端配置
注意:
如果使用手动集成的方式,需要将 framework 里面的 js_sdk 以 Add Files to 方式引入到工程中;如果是用的 cocoaPods 集成方式则不需要。如果用到 TMFWebOffline 离线包功能,工程里面的 wkwebview 相关页面的头文件需要引入#import <TMFQWebView/QBWKWebView.h>,且遵循TMFWebOfflineWebViewControllerProtocol 代理,wkwebview 继承 TMFWkWebView 如下设置:
#import <TMFQWebView/QBWKWebView.h>

@interface WKWebviewViewController ()<WKUIDelegate, WKNavigationDelegate, WKScriptMessageHandler,TMFWebOfflineWebViewControllerProtocol>
{
TMFWkWebView *wkWebView;
}
iOS SDK 配置
类文件中添加 #import <QAPM/QAPMLaunchProfile.h>导入 SDK 头文件。
在 WKWebView 的代理方法 webView:didFinishNavigation:中添加如下代码,以提供 Web 获取 native 相关信息接口。
- (void)webView:(WKWebView *)webView didFinishNavigation:(WKNavigation *)navigation
{
[webView evaluateJavaScript:[QAPMWebViewProfile qapmBaseInfo:@" "] completionHandler:nil];
[webView evaluateJavaScript:[QAPMWebViewProfile qapmJsStart] completionHandler:nil];
}

用户行为功能

QAPMMoniterType:QAPMMonitorTypeIUPMonitor 用户行为功能,将会在1min或者超过200条数据聚合上报。 自定义用户行为功能:在需要打点的页面加入 #import <QAPM/QAPMUBSMonitor.h> 头文件后,调用如下接口。
/**
用户自定义用户行为操作调用,外部用户接口,调用该接口时请完成QAPM的一系列初始化操作,设置完QAPM的appKey后调用。
@param category 事件名,建议全部用大写字母表示
@param tags 字符串的map标记,对应的key的值只能是d1~d30/info1~info10范围的值
@param values 数值的map标记,对应的key的值只能是v1~v30范围的值
@return 用户行为事件 uuid,如果返回为nil,则表示生成自定义用户行为事件失败
*/
- (NSString *)customEvent:(NSString *)category
tags:(NSDictionary<NSString *, NSString *> *)tags
values:(NSDictionary<NSString *, NSNumber *> *)values;
接口调用实例:
NSDictionary *tags = @{@"d1":@"iPhone 15 Pro",
@"d2":@"OLED显示屏",
@"d3":@"多摄像头系统",
@"info1":@"包括对专业应用的支持,如增强现实(AR)和专业摄影",
@"info2":@"Pro系列的iPhone通常使用更高级的材料,如不锈钢边框和陶瓷保护罩"
};
NSDictionary *values = @{@"v1":@512,
@"v2":@2048
};
[[QAPMUBSMonitor manager] generateUserEvent:@"CUSTOM_PERF_EVENT" label:@"" action:@"" value:@1 tags:tags values:values];

Webview 用户行为功能

QAPMMoniterType:QAPMMonitorTypeWebViewIUPMonitor Webview 用户行为功能,将会在1min或者超过200条数据聚合上报。 自定义用户行为功能:在 Web 页面代码中需要使用自定义事件的位置 (例如点击“购买基金”按钮的处理函数中) ,编写如下代码:
window.QAPM.customEvent(category, tags, values)
参数说明:
1)category:事件名称,字符串,值的长度不超过100
2)tags:事件辅助信息,json格式,key只能填写d1~d30和info1~info10,它们的值都是字符串,其中d1~d30的值的长度不超过100,info1~info10的值的长度不超过1024,超长的部分会被截断
3)values:事件辅助信息,json格式,key只能填写v1~v30,它们的值都是int
接口调用实例:
var event = {
    "category": "CLICK_BUY_BUTTON",
    "values": {
        "v1": 748,
        "v2": 1
    },
    "tags": {
        "d1": "FUJI mini7+",
        "d2": "package:1",
        "d3": "color:white",
        "info1": "Fuji novice recommends the king of cost-effective instant camera mini7+ one-time imaging cheap film machine for male and female students",
        "info2": "Package type: Package 1 [Official standard + 20 pieces of photo paper + new product gift package + 10-piece accessory gift package] Color classification: White"
    }
};
window.QAPM && typeof window.QAPM.customEvent==="function" && window.QAPM.customEvent(event.category, event.tags, event.values);

隐私合规

隐私合规政策: 因隐私合规要求,在用户同意隐私合规之前请确保不调用 QAPM 的任何接口,此外 QAPM 仍然需要设备级的唯一标识用于确定设备的唯一性,用于用户指标级的计算。
// 当用户授权后,方可正常初始化QAPM
if (isAgree) { }
//启动耗时函数的第一个打点
// 需要传入设备的唯一标识,如IDFV配合Keychain使用
[QAPMConfig getInstance].deviceID = @"自定义deviceId";
//用户user ID、第三方登录账号,此接口可以多次在代码位置使用
[QAPMConfig getInstance].userId = @"设置userId";
说明:
标识 deviceID 采集方式变更背景: 当前监管要求 SDK 不允许直接或间接采集 UDID 等信息,我们只能通过让用户自行传入标识符的方法去区分不同的设备,有效的降低 crash 率指标数据的失真。

符号表配置

利用已上报的数据个例上传符号表。根据个例页面的构建 ID 找到对应的符号表,可以使用官方 atos 命令翻译个例页面某行堆栈,确认符号表和翻译正常。
1. 在个例页面中有上传的入口,例如选择卡慢 > 卡慢分析 > 卡慢问题列表,进入详情页面。



2. 在详情页面中,单击上传 dSYM 文件。


3. 进入符号表上传页面,单击选择文件,然后选择该构建对应的 dSYM 文件即可。




查看 QAPM 工作日志

设置查看工作日志

在调用[QAPM startWithAppKey:]启动 QAPM SDK 前,设置日志输出函数, 可以根据不同发布版本情况进行输出日志控制:
void loggerFunc(QAPMLoggerLevel level, const char* log) {

#ifdef RELEASE
if (level <= QAPMLogLevel_Event) { ///外发版本log
NSLog(@"%@", [NSString stringWithUTF8String:log]);
}
#endif

#ifdef GRAY
if (level <= QAPMLogLevel_Info) { ///灰度和外发版本log
NSLog(@"%@", [NSString stringWithUTF8String:log]);
}
#endif

#ifdef DEBUG
if (level <= QAPMLogLevel_Debug) { ///内部版本、灰度和外发版本log
NSLog(@"%@", [NSString stringWithUTF8String:log]);
}
#endif
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

/// 设置QAPM 日志输出
[QAPM registerLogCallback:loggerFunc];

/// ...
/// 设置启动QAPM SDK
}

上报日志分析

在接入完成 SDK 后,通常情况下会通过分析日志来确定监控功能是否已经开启。
监控功能未开启时,日志如下:



监控功能开启时,日志如下:



通过初始化日志,可以看到初始化成功,各个监控功能开启,然后就是各功能上报成功的验证。
启动耗时的上报



卡顿个例的上报



FOOM个例上报



Deadlock个例上报



HTTP 监控上报



普通崩溃(normal crash)的上报
在触发 normal crash 的上报时,请不要将数据线连接 Xcode,触发完 normal crash 后,下次重启 App 的时候即可看到上报信息,该上报日志可通过 Mac 自带的控制台查看上报日志,日志如下:



Webview 和 JSerror 的上报
Webview 和 jserror 的上报,可在 xcode 查看日志,以 plugin:43 和 plugin:41 为准。



用户行为的上报
用户行为数据和自定义事件的数据可搜索 athena upload json is 关键字。






Webview 用户行为的上报
Webview 用户行为数据和自定义事件的数据可搜索 athena upload json is 关键字,同时关注 platform 为 web,topic 为3。



说明:
更多高级功能配置请参见 QAPM SDK GitHub主页,以及 shell 脚本及相关文档文件夹中的文档。