UCloud NetAnalysis SDK for iOS

README of Chinese

简介

本文档旨在帮助用户集成 UCloud NetAnalysis SDK for iOS。我们将介绍以下方面

• 关于 SDK 仓库
• 环境需求
• 安装
• 功能介绍
• F&A
• 联系我们

关于 SDK 仓库

该仓库包括 SDK 的源代码和示例项目。示例项目包含 "Objective-C" 和 `Swift" 两个版本。

环境要求

• IOS版本 >= 9.0
• UCloud客户已启用UCloud网分析服务

Xcode版本

UNetAnalysisSDK的《部署目标》为9.0，因此您可以使用XCode7.0及以上版本，并首先将《启用位码》设置为《否》

项目->构建设置->构建操作->启用位码

安装

Pod依赖

将以下依赖添加到项目的Podfile

pod 'UNetAnalysisSDK'

快速入门

将SDK头文件导入到项目中

#import <UNetAnalysisSDK/UNetAnalysisSDK.h>

此外，您还需要将-lc++、-ObjC、$( inherited )添加到项目的《构建设置》->《其他链接标志》。如下所示

函数介绍

网络诊断功能

• 您可以设置应用的服务器的IP地址，该地址用于网络诊断
• SDK会自动诊断网络状况并报告（触发条件：打开APP且网络正在切换[WWAN<=>WIFI]）
• 自动检测可以关闭。关闭后，您只能通过自己调用检测方法来触发网络检测。

其他功能

• 设置SDK日志级别
• 获取SDK版本

其主要操作类为UMQAClient.h。

代码示例

注册SDK

假设您已经在UCloud 控制台中注册了您的应用并打开了UCloud 网络分析服务，那么您将获得一对AppKey和PublicToken（公钥），在注册SDK时需要使用这些参数。

我们建议您尽早注册SDK，但不仅限于此，建议在应用启动时注册。您可以在AppDelegate中的- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions方法中注册。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[UMQAClient shareInstance] uNetSettingSDKLogLevel:UCSDKLogLevel_DEBUG];  // setting log level
    
        /*** Set custom report fields (optional configuration) ***/
    NSDictionary *userDefins = @{@"key1":@"value1",@"key2":@"value2"}; // User-defined field, which is a dictionary format with a limited length (detailed below)
     [[UMQAClient shareInstance] uNetSettingUserDefineFields:userDefins handler:^(UCError * _Nullable ucError) {
        if (!ucError) {
            NSLog(@"setting cus fields success....");
        }
    }];
    
    // Appkey and public token can be obtained from the ucloud console, or contact our technical support
    NSString *appKey = @""; //your AppKey
    NSString *appToken = @""; // your publick token
     [[UMQAClient shareInstance] uNetRegistSdkWithAppKey:appKey appSecret:appToken completeHandler:^(UCError * _Nullable ucError) {
        if (ucError) {
            NSLog(@"regist UNetAnalysisSDK error , error info: %@",ucError.error.description);
        }else{
            NSLog(@"regist UNetAnalysisSDK success...");
            NSArray *customerIps = @[@"220.181.112.244",@"221.230.143.58"]; // Fill in your application's main service address here (only support ip address, which is used for manual network diagnostics)
            [[UMQAClient shareInstance] uNetSettingCustomerIpList:customerIps];
        }
    }];
    
    return YES;
}

用户自定义字段

在注册SDK的方法中，用户自定义字段是可选字段。如果需要设置，则需要满足以下规则。

• NSDictionary的键值对形式为NSString-NSString
• 整个自定义字段将被转换为JSON字符串（如下所示）。转换后字符串的长度不能超过1024字节。如果未达到长度限制，将会抛出异常。

  [
   {
   "key":"",
   "val":""
   },
   {
   "key":"",
   "val":""
   },
   ....
  ]

设置自定义字段

在 'UMQAClient.h' 中定义方法

/**
 @brief Setting user-defined fileds 
 @discussion If the field you want to report can be obtained before registering the SDK, you need to call this method before registering the SDK; if the field you want to report is not obtained when registering the SDK, you can call this when you get the field. Method settings, but the data reported by the previous SDK diagnosis may not contain the custom fields you set.
 @param fields User-defined field. If there is no direct pass nil. This field has a length limit, and the total length converted to a string cannot exceed 1024.
 @param handler Use this `block` to tell the user if the setting was successful. If successful, `error` is empty.
 */
- (void)uNetSettingUserDefineFields:(NSDictionary<NSString*,NSString*> * _Nullable)fields
                            handler:(UCNetErrorHandler _Nonnull)handler;

设置自定义字段是一种可选方法。当您需要在报表数据中添加想要报告的字段时，可以调用此方法。

特别说明：如果要在注册SDK之前获取想要报告的字段，您需要在注册SDK之前调用“设置自定义字段”方法。如果注册SDK时未获取到想要报告的字段，可以随后获取。在获取到字段时调用自定义字段方法，但之前SDK诊断报告中报告的数据可能不包含您设置的定制字段。

自定义字段规则

自定义字段需要满足以下规则。

• NSDictionary的键值对形式为NSString-NSString

• 整个自定义字段将转换为JSON字符串（如下所示）。转换后的字符串长度不能超过1024字节。如果长度限制未满足，将抛出异常。

  [
  	{
  		"key":"",
  		"val":""
  	},
  	{
  		"key":"",
  		"val":""
  	},
  	....
  ]
  

关闭自动网络检测并触发网络检测

在 'UMQAClient.h' 中定义方法

/**
  @brief turns off automatic detection
 
  @discussion If you don't want to use the SDK's automatic trigger detection logic, then you can choose to turn it off. After turning off the automatic trigger detection logic, you need to manually call the execution diagnostic function to trigger the network detection.
  */
- (void)uNetCloseAutoDetectNet;

如果您不希望使用SDK的自动触发检测逻辑，可以在注册SDK之前选择将其关闭。关闭后，您只能手动调用触发网络检测的方法。

手动触发网络检测

/**
  @brief triggers network monitoring
 
  @discussion sdk will detect changes in the phone network and trigger network detection. You can also call this method to manually trigger network detection.
  */
- (void)uNetStartDetect;

停止网络数据收集

在 'UMQAClient.h' 中定义方法

/**
  @brief Stop network data collection
  @discussion When the app enters an inactive state, it can be stopped by calling this method. In this way, the APP flashback caused by part of `signal pipe` can be solved.
  */
- (void)uNetStopDataCollectionWhenAppWillResignActive;

当应用程序从活动状态即将转移到非活动状态时停止网络数据收集。这可以在AppDelegate中的- (void)applicationWillResignActive:(UIApplication *)application方法中完成。

- (void)applicationWillResignActive:(UIApplication *)application {
    [[UMQAClient shareInstance] uNetStopDataCollectionWhenAppWillResignActive];

}

适配iOS12（非必需）

在iOS 12（在iOS 12以下版本中没有发现此类问题）中，如果在执行诊断过程中按下锁屏按钮然后再次进入应用，应用将短时间内占用过多CPU。这个问题的原因是iOS 12中的NSURLSession。更多信息，请参阅[AFNetWorking---NSPOSIXErrorDomain Code=53: 软件导致连接中断] (https://github.com/AFNetworking/AFNetworking/issues/4279)和[Firebase Dynamic Links有时会收到错误NSPOSIXErrorDomain Code= 53 "软件导致连接中断"] (https://github.com/firebase/firebase-ios-sdk/issues/2303)，是类似的问题。

由于我们也在SDK内使用NSURLSession，我们添加了uNetAppDidEnterBackground方法来处理这个问题。该方法的内部实现逻辑已延迟到挂起状态。如果您的应用有后台模式或延迟待处理逻辑，您可以忽略此方法。

- (void)applicationDidEnterBackground:(UIApplication *)application {
    [[UMQAClient shareInstance] uNetAppDidEnterBackground];
}

常见问题

• iOS 9+中的应用被强制使用HTTPS。使用XCode创建的项目默认不支持HTTP，因此您需要在项目构建信息中添加NSAppTransportSecurity，并在NSAppTransportSecurity中添加NSAllowsArbitraryLoads，将其值设置为YES，如下所示：

联系我们

• UCloud官方网站
• 如果您有任何疑问，请提交问题或联系我们的技术支持，我们将第一时间解决问题。