集成和初始化

最近更新时间:2025-06-19 21:11:53

我的收藏
本文指导您使用 iOS SDK 的集成与初始化。
说明:
隐私合规相关配置请查看 合规使用指南

操作步骤

步骤1:SDK 集成

支持通过 CocoaPods 集成和手动集成两种方式集成 SDK。

CocoaPods 集成

在 podfile 文件中增加如下操作,然后执行 pod install 指令。
pod 'QAPM',:source => 'https://github.com/TencentCloud/QAPM-iOS-CocoaPods.git'

手动集成

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 Linker Flags 中添加-ObjC参数。
5. 导入配置文件:
5.3.5之前的版本将 framework 里面的 js_sdk.js 文件导入到工程根目录。
5.3.5及以后的版本将 framework 里面的 QAPMResourceFile.bundle 文件导入到工程根目录。
说明:
iOS SDK 最低兼容系统版本 iOS 8.0。从5.4.6版本开始支持大模型 SSE 监控,该功能和原网络监控功能同时开启。
在正确获取到 appkey 后可先体验 Demo,快速触发终端性能监控的各功能数据上报。
常见接入 FAQ 请参见 常见问题

步骤2:Web 端环境配置

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





步骤3: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 合规使用指南》:https://cloud.tencent.com/document/product/683/70827
[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
//法兰克福站:https://eu-frankfurt.rumapp.tencentcs.com
[QAPMConfig getInstance].host = @"https://app.rumt-zh.com";
[QAPMConfig getInstance].customerAppVersion = @"自定义版本号";

//根据实际情况设置 userid 和 deviceID,为了快速验证数据上报,请在研发流程内通过设置用户或者设备白名单进行验证,添加其中一项白名单即可,白名单设置规则请参照下面的注意项进行添加,

#ifdef DEBUG
[QAPMConfig getInstance].userId = @"123456789";
[QAPMConfig getInstance].deviceID = @"11223344";
#else
//设备唯一标识 deviceID,例如使用 IDFV 配合 Keychain 使用
[QAPMConfig getInstance].userId = @"自定义userId";
[QAPMConfig getInstance].deviceID = @"自定义deviceId";
#endif

//启动 QAPM
[QAPM startWithAppKey:@"产品唯一的appKey"];
return YES;
}
注意:
研发流程内,可以将设置的用户 ID /设备 ID 添加成白名单,确保指定设备的功能上报不会被采样影响,可登录 终端性能监控控制台,进入应用管理 > 白名单管理 > 白名单配置页面,单击添加完成操作。
以上述初始化代码为例,在 debug 模式下用户 ID 为123456789,设备 ID 为11223344,那么配置的白名单如下图所示,配置其中一种类型白名单即可。


步骤4:监控功能启用

初始化后需开启监控功能,支持使用推荐配置一键开启监控功能和自定义开启某个功能。

推荐使用

使用 QAPMModelStableConfig.h 文件中的接口:
- (void)setupModelAll:此接口可开启全部监控功能。
使用 QAPMModelStableConfig.h 文件中的接口:
- (void)setupModelStable:此接口可开启除了原生层网络监控、大模型 SSE 监控和用户行为监控之外的所有监控功能。原生层网络监控、大模型 SSE 监控和用户行为监控按照工信部26号文要求划分为扩展业务功能,您可根据自身需要选择是否开启。

自定义使用

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