# iOS SDK接入 APM iOS SDK具备采集上报App启动性能、崩溃、卡顿、错误、网络请求、终端设备、自定义上报等应用监控能力。 #### 使用前提 使用SDK前，您需要注册华为云账号，并在App监控控制台创建移动端iOS App。 #### 传输协议 HTTPS #### 版本更新说明 表1版本更新说明 | 版本号 | SDK下载地址 | 检验信息下载地址 | 更新说明 | 系统 | |:---|:---|:---|:---|:---| | 2.1.1 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.1.1.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.1.1.zip.sha256) | 支持传入多个dSYM文件。 | iOS10、Xcode11及以上。 | | 2.1.0 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.1.0.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.1.0.zip.sha256) | 兼容APM Flutter SDK。 | iOS10、Xcode11及以上。 | | 2.0.12 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.12.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.12.zip.sha256) | 修复网络请求监控问题。 | iOS10、Xcode11及以上。 | | 2.0.11 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.11.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.11.zip.sha256) | 修复类名冲突。 | iOS10、Xcode11及以上。 | | 2.0.10 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.10.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.10.zip.sha256) | 修复冷启动应用加载耗时数据异常。 | iOS10、Xcode11及以上。 | | 2.0.9 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.9.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.9.zip.sha256) | 修复自定义事件上报问题。 | iOS10、Xcode11及以上。 | | 2.0.8 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.8.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.8.zip.sha256) | 支持采样率。 | iOS10、Xcode11及以上。 | | 2.0.7 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.7.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.7.zip.sha256) | 支持远程配置功能。 | iOS10、Xcode11及以上。 | | 2.0.6 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.6.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.6.zip.sha256) | 修复配置引起的SDK启动失败问题。 | iOS10、Xcode11及以上。 | | 2.0.5 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.5.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.5.zip.sha256) | 修复网络请求、错误监控系统兼容性问题。 | iOS10、Xcode11及以上。 | | 2.0.1 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.1.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.1.zip.sha256) | 修复系统兼容性问题。 | iOS10、Xcode11及以上。 | | 2.0.0 | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.0.zip) | 单击[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-ios-sdk-2.0.0.zip.sha256) | 提供采集上报App启动性能、崩溃、卡顿、错误、网络请求、终端设备、自定义上报等应用监控能力。 | iOS10、Xcode11及以上。 | #### 操作步骤 1. 集成接入SDK。 - 方法1：通过CocoaPods集成。 1. 在Podfile中添加CocoaPods官方仓库 ``` source 'https://github.com/CocoaPods/Specs.git' ``` 2. 在Podfile中添加依赖 ``` pod 'APMSDK', '2.1.0' ``` 3. 在终端执行 ``` pod install --repo-update ``` - 方法2：手动集成。 1. 下载SDK，解压到指定目录。 ![](https://support.huaweicloud.com/usermanual-apm2/public_sys-resources/note_3.0-zh-cn.png) 直接解压即可，不需要额外操作。 2. 将解压后的xcframework静态库添加到您的项目工程中。请注意，待导入的xcframework静态库必须和工作空间在相同的磁盘空间里。如果不在，您可以选择注意勾选"Copy items if needed"和"Create groups"，将待导入的xcframework库工程文件复制到工作空间。 2. 添加配置文件。 在创建移动端iOS App过程中，会生成名为apm-sdk-config.json的配置文件，下载并拖拽至Xcode工程根目录，如下图所示： ![](https://support.huaweicloud.com/usermanual-apm2/zh-cn_image_0000002549695927.png "点击放大") 表2配置参数说明 | 参数名称 | 是否必填 | 默认值 | 描述 | |:---|:---|:---|:---| | appId | 是 | - | 移动端AppID。 | | authorization | 是 | - | 用于App的匹配。 | | region | 是 | - | 上报APM所处的region，目前支持cn-north-4。 | | uid | 否 | - | 用户自定义ID。 | | tag | 否 | - | 用户自定义标签，多个时使用英文逗号隔开。 | | url | 否 | - | 要上报APM的公网地址域名。 | | networkWhiteList | 否 | - | 网络监控白名单，排除监控。 | | cacheThreshold | 否 | 200条 | 当本地数据库存储条数达到该值会触发上报，取值范围为30-1000条。 | | timeInterval | 否 | 60秒 | 定时器每隔该值会触发上报，取值范围为60-1800秒。 | | reportBackground | 否 | true | 是否开启APP切后台上报功能。 | | reportLaunch | 否 | false | 是否开启APP启动时上报功能。如需开启，请在UIApplicationDidFinishLaunchingNotification通知发送前启动SDK。 | | enableNetwork | 否 | false | 是否开启网络采集。 | | enableCrash | 否 | false | 是否开启崩溃采集。 | | enableLaunch | 否 | false | 是否开启启动采集。 | | enableANR | 否 | false | 是否开启卡顿采集。 | | enableError | 否 | false | 是否开启错误采集。 | | enableDevice | 否 | false | 是否开启终端设备采集。 | | enableEvent | 否 | false | 是否开启用户自定义上报。 | | traceType | 否 | apm | 链路追踪类型。 - 开启：otel。 - 关闭：apm。 | | logLevel | 否 | off | 调试日志等级。 - debug - info - warn - error - off | | samplingRate | 否 | 1.0 | 采样率，取值范围0\~1.0。 | 3. 启动SDK。 - Objective-C代码示例。 ``` @import APMSDK; // 根据apm-sdk-config.json配置文件启动SDK [APMSDK start]; // 设置自定义ID，也可以在配置文件中添加 [APMSDK setUid:@"自定义ID"]; // 设置自定义标签，也可以在配置文件中添加 [APMSDK addTag:@"自定义标签1,自定义标签2,自定义标签3"]; ``` - Swift代码示例。 ``` import APMSDK // 根据apm-sdk-config.json配置文件启动SDK APMSDK.start() // 设置自定义ID，也可以在配置文件中添加 APMSDK.setUid("自定义ID") // 设置自定义标签，也可以在配置文件中添加 APMSDK.addTag("自定义标签1,自定义标签2,自定义标签3") ``` 4. 自定义上报统计。 | 方法名称 | 参数说明 | |:---|:---| | + (BOOL)event:(NSString \*)key value:(id)value; | key：事件名称，最大长度为2048个字符。value：事件内容，支持NSString，NSArray，NSDictionary，NSNumber等有效JSON对象，转JSON字符串最大长度为30720个字符。 | Objective-C代码示例： ``` // 事件统计 [APMSDK event:@"User Information" value:@{@"name":@"XXX"}]; [APMSDK event:@"Error Description" value:@"The request timed out."]; [APMSDK event:@"Call Stack" value:@[@"0x0000000101ee9c6c", @"0x0000600000e61d80"]]; // 数值统计 [APMSDK event:@"Custom Load Time" value:@(0.238)]; [APMSDK event:@"Purchase Statistics" value:@(1)]; ``` Swift代码示例： ``` // 事件统计 APMSDK.event("User Information", value: ["name": "XXX"]) APMSDK.event("Error Description", value: "The request timed out.") APMSDK.event("Call Stack", value: ["0x0000000101ee9c6c", "0x0000600000e61d80"]) // 数值统计 APMSDK.event("Custom Load Time", value: 0.238) APMSDK.event("Purchase Statistics", value: 1) ``` 5. 网络请求身份认证（仅适用开启网络请求监控）：当请求访问服务器受保护的资源时，会触发身份认证质询流程，App需实现APMURLProtocolDelegate协议，完成身份认证质询。 Objective-C代码示例： ``` @interface AppDelegate : UIResponder @end @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // 先设置网络请求身份认证质询代理 [APMURLProtocol setDelegate:self]; // 再启动SDK [APMSDK start]; } #pragma mark -- APMURLProtocolDelegate - (BOOL)APMURLProtocol:(APMURLProtocol *)protocol canAuthenticateAgainstProtectionSpace:(NSURLProtectionSpace *)protectionSpace { // 对服务端身份进行认证：本例子为简单示例，请根据App原认证方式处理 return [[protectionSpace authenticationMethod] isEqual:NSURLAuthenticationMethodServerTrust]; } - (void)APMURLProtocol:(APMURLProtocol *)protocol didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge { // 信任服务端身份：本例子为简单示例，请根据App原认证方式处理 NSURLCredential *credential = [NSURLCredential credentialForTrust:challenge.protectionSpace.serverTrust]; [protocol resolveAuthenticationChallenge:challenge withCredential:credential]; } - (void)APMURLProtocol:(APMURLProtocol *)protocol didCancelAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge { } @end ``` Swift代码示例： ``` class AppDelegate: UIResponder, UIApplicationDelegate, APMURLProtocolDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // 先设置网络请求身份认证质询代理 APMURLProtocol.setDelegate(self) // 再启动SDK APMSDK.start() } func apmURLProtocol(_ `protocol`: APMURLProtocol, canAuthenticateAgainstProtectionSpace protectionSpace: URLProtectionSpace) -> Bool { // 对服务端身份进行认证：本例子为简单示例，请根据App原认证方式处理 return protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust } func apmURLProtocol(_ `protocol`: APMURLProtocol, didReceive challenge: URLAuthenticationChallenge) { // 信任服务端身份：本例子为简单示例，请根据App原认证方式处理 if let serverTrust = challenge.protectionSpace.serverTrust { let credential = URLCredential(trust: serverTrust) `protocol`.resolve(challenge, with: credential) } else { `protocol`.resolve(challenge, with: nil) } } func apmURLProtocol(_ `protocol`: APMURLProtocol, didCancel challenge: URLAuthenticationChallenge) { } } ``` #### 数据上报策略 SDK支持四种上报策略：阈值上报、定时上报、应用切后台和启动时上报，根据场景选择合适的值配置cacheThreshold、timeInterval、reportBackground、reportLaunch等参数。 #### 开启调试日志 在开发过程中可以开启调试日志，借助控制台实时查看SDK运行状况，观察日志并根据需要进行调整，日志级别有：debug、info、warn、error、off（关闭）。 请开发者在App上线前关闭调试日志功能，即设置为off。 示例：在配置文件apm-sdk-config.json中设置日志级别。 ``` { "logLevel": "debug" } ```