腾讯客户端性能分析
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 腾讯客户端性能分析 > 操作指南 > iOS SDK 接入

iOS SDK 接入

最近更新时间：2024-01-02 17:28:24

我的收藏

本页目录：

SDK 集成

手动集成
1.1 下载 SDK。
1.2 拖拽 QAPM.framework 文件到 Xcode 工程内（请勾选Copy items if needed 选项）。
1.3 在 TARGETS > Build Phases-Link Binary Libraries 添加依赖库：
libc++.dylib (libc++.tbd)。
libz.dylib (libz.tbd)。
1.4 在工程的 Other LinkerFlags 中添加-ObjC参数。
1.5 将 framewor k里面的js_sdk.js文件导入到工程根目录。
cocoaPods 集成
在 podfile 文件中增加如下操作：
pod 'QAPM',:source => 'https://github.com/TencentCloud/QAPM-iOS-CocoaPods.git'，然后执行 pod install 指令。
注意：
iOS SDK 最低兼容系统版本 iOS 8.0。

SDK 启动

SDK 初始化

1. 进入 QAPM 页面的配置 > 产品配置，可以查看到AppKey，该key在初始化接入中需要使用。


2. 在工程的 AppDelegate.m 文件导入头文件：#import <QAPM/QAPM.h>，如果是 Swift 工程，请在对应bridging-header.h中导入。
3. 初始化 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是否可以进行可选个人信息的采集，默认可以采集。设置为NO则不采集。该设置需要最先配置，一旦设置则全局生效
//可选个人信息包括但不限于以下信息：设备制造商、系统、运营商等等，详见《QAPM SDK 合规使用指南》
//该设置默认设置是YES，代表允许可采集，示例代码如下：
[QAPMConfig getInstance].collectOptionalFields = YES;

// 特别说明： 若上述该设置置为NO，部分信息将不再获取，可能会影响到前端的搜索、展示等，请知悉。

/// 设置QAPM 日志输出
NSLog(@"qapm sdk version : %@", [QAPM sdkVersion]);    
[QAPM registerLogCallback:loggerFunc];
    
//私有云用户根据实际情况配置。
   [QAPMConfig getInstance].host =@"自定义host";
    // appconfigHost内外网用户为默认值，私有云用户需要自定义设置。
[QAPMConfig getInstance].appconfigHost = @"私有云设置";
    [QAPMConfig getInstance].customerAppVersion = @"设置app自定义版本号";
//根据实际情况设置userid 和deviceID
//设备唯一标识deviceID，例如IDFV配合Keychain使用
[QAPMConfig getInstance].userId = @"设置userId";
    [QAPMConfig getInstance].deviceID = @"自定义deviceId";
    /// 启动QAPM
    [QAPM startWithAppKey:@"产品唯一的appKey"];
    return YES;
}
注意：
1. AppKey 请到移动监控的配置页 > 产品配置页获取。
2. 研发流程内，可以将设置的用户 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 基础功能的定义，将网络监控与用户行为监控划分为
扩展业务功能
，这意味着为了避免采集网络日志信息、用户操作记录等个人信息，您可以选择性开启这两个功能。操作层面您可以在自定义性能模块开启配置中避免填入QAPMMonitorTypeHTTPMonitor、QAPMMonitorTypeWebViewNetWork两个参数，以关闭网络监控功能；以此类推，您可以在自定义性能模块开启配置中避免填入QAPMMonitorTypeIUPMonitor、QAPMMonitorTypeWebViewIUPMonitor两个参数，以关闭用户行为监控功能，或直接使用 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];
}

用户隐私协议

隐私合规政策： 因隐私合规要求，在用户同意隐私合规之前请确保不调用 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 为准。



中国站