文档中心

应用性能监控全链路版

iOS SDK 接入

应用接入 iOS SDK

应用性能监控全链路版的iOS SDK基本为无侵入式，App接入SDK后可以进行崩溃分析、错误分析、卡顿分析等各种监控指标的分析，帮助优化和定位问题。本文介绍产品形态为App的详细的接入步骤。

注意事项

iOS SDK有中国大陆（不包括港澳台地区）和海外两个版本，功能相同上报地址不同。

中国发布的应用：使用CN子库，上报到中国大陆服务器。

海外发布的应用：使用Global子库且SDK版本大于等于5.1.0，上报到马来西亚柔佛服务器。

调用SDK初始化接口不会采集用户信息，调用SDK启动接口会开始采集用户信息，请确保采集用户信息之前已经获得用户授权。详情请参见SDK隐私政策。

Demo说明

APMPlus_iOS

Demo已经接入了SDK的所有能力。

您可以通过Demo制造一些崩溃和性能数据。

可以修改Demo中的AppID和AppToken，把性能数据上报到控制台以查看。

Demo中提供了各功能模块的子库，子库和模块的对应关系如下表所示：

子库	说明	对应平台模块	开始支持版本
Crash	崩溃监控：捕获CPP Exception、Mach Exception、NSException Exception 和 Signal Exception	崩溃分析	0.0.5
WatchDog	卡死监控：监控主线程长时间卡住被系统 watchdog给强杀的情况	崩溃分析	0.0.5
OOM	Out of memory监控	崩溃分析内存优化-OOM趋势	0.0.5
LAG	卡顿监控：监控主线程短时间内无法响应的情况	卡顿分析	0.0.5
UserException	自定义错误，需要业务方手动打点	错误分析-自定义错误	0.0.5
Monitors	启动分析：流畅性：	用户体验-启动分析用户体验-页面体验内存优化-OOM趋势-扩展指标	0.0.7
UITrackers	页面分析：	用户体验-页面体验-页面响应	0.0.7
Hybrid	WKWebView H5 页面监控，推荐接入 HybridPro 模块	页面监控	0.0.8
MemoryGraph	内存分析，获取某一时刻APP的内存状态	内存优化	0.0.8
Network	网络分析：网络错误，Http、DNS分析，推荐接入 NetworkPro 模块	网络分析错误分析-网络错误	1.0.0
NetworkPro	网络分析：网络错误，Http、DNS分析，推荐接入本模块，相比 Network 更加完善	网络分析错误分析-网络错误	2.5.2
EventMonitor	事件分析，记录自定义事件，需要手动埋点	事件分析	2.0.0
SessionTracker	PV/UV统计，接入后会自动上报数据	各模块异常率、异常用户比例等	2.3.0
APMLog	APM日志库，可以手动打点记录APP运行日志	日志回捞崩溃分析-崩溃详情-自定义日志	2.4.0
CrashProtector	崩溃防护	异常防护-崩溃防护	2.5.2
CPUException	CPU异常监控	CPU监控-CPU异常	2.7.3
MetricKit	MetricKit 的稳定性	MetricKit-稳定性	2.12.1
MetricKit		MetricKit 的性能	MetricKit-性能	3.5.3
Disk	磁盘监控	磁盘监控	3.0.0
GWPASan	GWPASan	崩溃分析	3.1.0
Coredump	Coredump	崩溃分析	3.2.0
BootingProtect	连续崩溃保护	-	2.10.0
BootingProtectLite	连续崩溃保护Lite版（不依赖OOM，如果接入了 OOM 模块，推荐使用 BootingProtect）	-	2.10.0
Zombie	线上Zombie分析	崩溃分析	2.8.0（不支持白名单） 2.10.0（支持白名单）
CloudCommand	回捞功能	单点追查-回捞	3.5.3
HybridPro	新版 WKWebView H5 页面监控，推荐接入本模块，相比 Hybrid 更加完善	新H5监控	3.10.0
CN	上报域名，适用于国内数据上报，如果使用的是华北服务，请接入本模块	-	0.0.5
Global	上报域名，适用于海外数据上报，如果使用的是柔佛服务，请接入本模块	-	5.1.0
BytePlus	上报域名，适用于 BytePlus 站点，如果使用火山引擎站，请勿接入	-	5.2.0

步骤一：获取SDK包

说明

如果您未使用 Cocoapods 进行包管理或者需要使用支持 arm 模拟器的版本，可以参考 APMPlus_SPM 使用 SPM 方式接入 SDK。SPM 方式相比文档中默认的 Cocoapods 方式，在包引入形式和头文件上存在差异，这部分可以查看 SPM 仓库的说明文档；模块划分和接入代码是统一的，可以直接参考本文档其他部分内容。

在Podfile中，添加如下示例代码，获取SDK包。

platform :ios, '10.0'
source 'https://github.com/volcengine/volcengine-specs.git'

pod 'RangersAPM', '5.2.14', :subspecs => [
'Crash',
'WatchDog',
'OOM',
'LAG',
'UserException',
'Monitors',
'UITrackers',
'HybridPro',
'MemoryGraph',
'NetworkPro',
'EventMonitor',
'SessionTracker',
'APMLog',
'CrashProtector',
'CPUException',
'MetricKit',
'Disk',
'GWPASan',
'Coredump',
'CloudCommand',
# 'CN'
# 'Global'
]

说明

添加上述代码会引入SDK的所有功能，如果不想引入全部功能，请按需引入子库，具体请参见Demo说明。

APMPlus从3.10.0版本起支持苹果在WWDC 23要求的Privacy manifest功能。

CN 与 Global 用来指明数据上报的域名，默认情况下必须且只能接入其一，如果有特殊使用场景，可以参考上报域名配置。

CN：上报到国内服务器

Global：上报到国外服务器

执行以下命令，安装SDK。

pod install

步骤二：初始化SDK

说明

初始化SDK阶段，不获取用户个人信息。

建议在AppDelegate.m的application didFinishLaunchingWithOptions:方法中，或者在用户同意隐私政策之后的合适时机，进行初始化SDK的操作。

添加以下示例代码，初始化SDK。

说明

{{app_id}}和{{app_token}}须替换为您创建的应用对应的AppID和AppToken，具体请参见如何查询AppID和AppToken？。

步骤三：启动SDK并开启数据采集

注意

建议启动代码调用时机尽量靠前，否则可能出现启动阶段（启动SDK代码调用之前）发生的崩溃无法捕获，或者启动分析数据产生误差。

建议在AppDelegate.m的application didFinishLaunchingWithOptions:方法中，或者在用户同意隐私政策之后的合适时机，完成启动SDK的操作。

添加以下示例代码，启动SDK并开启数据采集。

说明

如果需要使用自定义deviceID，需修改apmConfig的相关参数，具体请参见获取设备数与用户数。

步骤四：上传符号表

符号表可以解析崩溃堆栈的内容，将日志里的堆栈信息由原始堆栈转化成经过符号化之后的解析堆栈。符号表支持手动上传和自动上传两种方式。

手动上传

验证符号表满足以下格式。

把符号表压缩为zip文件。

Mac中zip需要执行以下命令，去除默认生成的DS_Store__MACOSX文件。

zip -r test.app.dSYM.zip test.app.dSYM -x "*.DS_Store" -x "__MACOSX"

说明

将test.app.dSYM.zip和test.app.dSYM替换为您的符号表名称。

上传符号表。

在符号表管理页面上传符号表。详情请参见iOS符号表管理。

使用curl命令上传。

APMPlus_Upload_DSYM_Domain=""
APMPlus_APPID=""
APMPlus_Upload_DSYM_API_Key=""
APMPlus_Upload_DSYM_API_Token=""
APMPlus_DSYM_File_Path=""

APMPlus_CURRENT_TIMESTAMP=$(date "+%s")000
APMPlus_Signature=$(md5 -s "${APMPlus_CURRENT_TIMESTAMP}${APMPlus_Upload_DSYM_API_Token}" | cut -d ' ' -f1)
curl ${APMPlus_Upload_DSYM_Domain}/apmplus_api/eue/guest/app/mapping/upload -F "file=@${APMPlus_DSYM_File_Path}" -F "type=Dwarf" -F "os=iOS" -F "aid=${APMPlus_APPID}" -F "script-version=3.0" -H "Content-Type: multipart/form-data" -H "X-OpenApi-Timestamp: ${APMPlus_CURRENT_TIMESTAMP}" -H "X-OpenApi-AppID: ${APMPlus_Upload_DSYM_API_Key}" -H "X-OpenApi-Token: ${APMPlus_Signature}" -H "x-app-ids: ${APMPlus_APPID}" -w %{http_code}

注意

将变量APMPlus_Upload_DSYM_Domain的值设置为您想上报的域名。

国内域名：https://open.apmplus.cn-beijing.volces.com。接入 CN subspec 时，请使用这个域名。

国外域名：https://open.apmplus.ap-southeast-1.volces.com。接入 Global subspec 时，请使用这个域名。

将变量 APMPlus_APPID的值设置为您的 AppID。

将变量 APMPlus_Upload_DSYM_API_Key的值设置为 API Key。可以从平台的全部功能->符号表管理->系统选择 iOS->下面可以看到API Key。

将变量 APMPlus_Upload_DSYM_API_Token的值设置为 API Token。从平台的全部功能->符号表管理->系统选择 iOS->下面可以看到API Token。

将变量 APMPlus_DSYM_File_Path的值设置为需要上传的符号表文件路径。

执行完成后，返回如下即说明上传成功。

自动上传

通过在Xcode中对应Target下，配置Build Phases，添加Run Script，可以实现APP打包时自动上传符号表。

说明

默认Debug模式和模拟器编译不会上传符号表。如果需要在这两种情况下上传符号表，请参见手动上传。

选择Build Settings > Debug Infomation Format下，检查工程配置是生成符号表。

选择Build Phases > New Run Script Phase，添加Run Script。

将添加的Run Script置于最后，防止脚本执行时符号表还没有生成。

在脚本中添加以下命令，在Debug模式和模拟器编译时不会上传符号表。

/bin/sh ${PODS_ROOT}/RangersAPM/RangersAPM/Core/APMPlus_DSYMUploader_v3.sh "APMPlus_APPID" "APMPlus_Upload_DSYM_API_Key" "APMPlus_Upload_DSYM_API_Token" "APMPlus_Upload_DSYM_Domain"

说明

APMPlus_APPID须替换为您创建的应用对应的AppID，具体请参见如何查询AppID和AppToken？。

将命令中APMPlus_Upload_DSYM_API_Key的值设置为 API Key。可以从平台的全部功能->符号表管理->系统选择 iOS->下面可以看到API Key。

将命令中 APMPlus_Upload_DSYM_API_Token的值设置为 API Token。从平台的全部功能->符号表管理->系统选择 iOS->下面可以看到API Token。

将命令中的APMPlus_Upload_DSYM_Domain的值设置为您想上报的域名。

国内域名：https://open.apmplus.cn-beijing.volces.com。接入 CN subspec 时，请使用这个域名。

国外域名：https://open.apmplus.ap-southeast-1.volces.com。接入 Global subspec 时，请使用这个域名。

接入的SDK版本需要大于等于5.1.6。若接入早期版本的SDK，请使用步骤5 的方案。

（可选）修改脚本内容。

如果您接入的SDK为较低版本且不想升级为更高版本，或者需要Debug模式和模拟器编译才能自动上传符号表，请执行以下操作：

下载脚本文件。

APMPlus_DSYMUploader_v3.sh

将下载的脚本文件内容复制到Run Script中。

将变量 APMPlus_APPID替换为您的 AppID。

将变量 APMPlus_Upload_DSYM_API_Key设置为 API Key。

将变量 APMPlus_Upload_DSYM_API_Token设置为 API Token。

修改APMPlus_UPLOAD_DOMAIN为您想要上报的域名。

说明

国内域名：https://open.apmplus.cn-beijing.volces.com。接入 CN subspec 时，请使用这个域名。

国外域名：https://open.apmplus.ap-southeast-1.volces.com。接入 Global subspec 时，请使用这个域名。

#!/bin/sh
################################################################################
# 自定义配置
###############################################################################
# Debug模式编译是否上传，1＝上传 0＝不上传，默认不上传
UPLOAD_DEBUG_SYMBOLS=0

# 模拟器编译是否上传，1＝上传，0＝不上传，默认不上传
UPLOAD_SIMULATOR_SYMBOLS=0

# APMPlusID：应用在APMPlus平台的ID
APMPlus_APP_ID="XXX"

# APMPlusUploadDSYMAPIKey：从平台的全部功能->符号表管理->系统选择 iOS->下面可以看到API Key。
APMPlus_Upload_DSYM_API_Key="XXX"

# APMPlusUploadDSYMAPIToken：从平台的全部功能->符号表管理->系统选择 iOS->下面可以看到API Token。
APMPlus_Upload_DSYM_API_Token="XXX"

# APMPlusUploadDomain：应用上报的域名，请在 [平台 - 应用接入iOS SDK](https://www.volcengine.com/docs/6431/68850#%E6%AD%A5%E9%AA%A4%E5%9B%9B%EF%BC%9A%E4%B8%8A%E4%BC%A0%E7%AC%A6%E5%8F%B7%E8%A1%A8) 查询映射表。
APMPlus_UPLOAD_DOMAIN="XXX"

根据需要，修改脚本中的UPLOAD_DEBUG_SYMBOLS和UPLOAD_SIMULATOR_SYMBOLS字段。

参数	说明
UPLOAD_DEBUG_SYMBOLS	Debug模式编译是否上传。 1：上传 0（默认）：不上传
UPLOAD_SIMULATOR_SYMBOLS	模拟器编译是否上传。 1：上传 0（默认）：不上传