集成和初始化

Recent Pages

集成和初始化

最后更新时间：2024-05-20 10:47:31
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 {
//为响应工信部工业和信息化部关于进一步提升移动互联网应用服务能力的通知要求，提供该设置用于告知SDK是否可以进行可选个人信息的采集，默认可以采集。设置为NO则不采集。该设置需要最先配置，一旦设置则全局生效
//可选个人信息包括但不限于以下信息：设备制造商、系统、运营商等等
//该设置默认设置是YES，代表允许可采集，示例代码如下：
[QAPMConfig getInstance].collectOptionalFields = YES;
﻿
// 特别说明： 若上述该设置置为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. 为响应工信部 工业和信息化部关于进一步提升移动互联网应用服务能力的通知 要求，我们依据工信部对性能监控类 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 为准。
﻿
﻿
﻿
说明：
更多高级功能配置请参见 GitHub - TencentCloud/qapm-sdk-ios: 主要用来更新 qapm 性能监控组件，以及 shell 脚本及相关文档文件夹中的文档。