App Center Analytics （iOS）

2025-05-05

重要

Visual Studio App Center 于 2025 年 3 月 31 日停用，但分析和诊断功能除外，这些功能将继续受支持，直到 2026 年 6 月 30 日。了解详细信息。

App Center Analytics 可帮助你了解用户行为和客户参与度，以改进你的应用。 SDK 会自动捕获会话计数和设备属性，例如模型、OS 版本等。可以定义自己的自定义事件来度量对你很重要的事情。捕获的所有信息都可在 App Center 门户中使用，以便分析数据。

注释

没有 SIM 卡的 iOS 设备不会将带有运营商国家/地区代码的报告发送到 App Center 门户。如果要提供国家/地区值，请使用 setCountryCode 方法覆盖设备位置的国家/地区代码。

注释

在 4.0.0 版本中引入了 App Center 的重大变更。请按照“迁移到 App Center SDK 4.0.0 及更高”部分的指引，将 App Center 从之前的版本迁移。

如果尚未在应用程序中设置 SDK，请按照 “入门 ”部分进行作。

会话和设备信息

将 App Center Analytics 添加到应用并启动 SDK 后，它将自动跟踪会话和设备属性，包括 OS 版本、模型等，而无需任何其他代码。

注释

在 Mac Catalyst 应用中，会话数量可能低于 iOS 应用。用于跟踪 Mac Catalyst 上的会话的生命周期事件与 iOS 上的会话的行为不同。

如果设备安装了移动数据调制解调器和 SIM 卡，SDK 会自动报告用户的国家/地区代码。默认情况下，仅 WiFi 设备不会报告国家/地区代码。若要设置这些用户的国家/地区代码，必须自行检索用户的位置并使用 setCountryCode: SDK 中的方法。我们的建议是注意跟踪用户位置，并使用低位置分辨率。以下示例使用 kCLLocationAccuracyKilometer。

请确保在设备上启用 Location Services 。
使用 CLLocationManager. 获取设备的当前位置。
使用 CLGeocoder.. 将位置转换为 ISO 国家/地区代码。
使用 SDK setCountryCode 的方法替代运营商国家/地区代码。

使用以下代码获取设备的位置并覆盖应用中的运营商国家/地区代码：

将 CLLocationManagerDelegate 协议添加到 AppDelegate，并添加 locationManager 属性：

@interface AppDelegate () <CLLocationManagerDelegate>
@property(nonatomic) CLLocationManager *locationManager;
@end

class AppDelegate: CLLocationManagerDelegate {
  private var locationManager: CLLocationManager = CLLocationManager()
}

在 didFinishLaunchingWithOptions: 方法中设置位置管理器：

  self.locationManager = [[CLLocationManager alloc] init];
  self.locationManager.delegate = self;
  self.locationManager.desiredAccuracy = kCLLocationAccuracyKilometer;
  [self.locationManager requestWhenInUseAuthorization];

  self.locationManager.delegate = self
  self.locationManager.desiredAccuracy = kCLLocationAccuracyKilometer
  self.locationManager.requestWhenInUseAuthorization()

注释

此方法 requestWhenInUseAuthorization 不适用于 macOS。在针对 macOS 进行开发时删除对该方法的调用。

添加委托方法：

- (void)locationManager:(CLLocationManager *)manager didChangeAuthorizationStatus:(CLAuthorizationStatus)status {
  if (status == kCLAuthorizationStatusAuthorizedWhenInUse) {
    [manager requestLocation];
  }
}

- (void)locationManger:(CLLocationManager *)manager didUpdateLocations:(NSArray<CLLocation *> *)locations {
  CLLocation *location = [locations lastObject];
  CLGeocoder *geocoder = [[CLGeocoder alloc] init];
  [geocoder reverseGeocodeLocation:location
                 completionHandler:^(NSArray *placemarks, NSError *error) {
                   if (placemarks.count == 0 || error)
                     return;
                   CLPlacemark *pm = [placemarks firstObject];
                   [MSACAppCenter setCountryCode:pm.ISOcountryCode];
                 }]
}

- (void)locationManager:(CLLocationManager *)manager didFailWithError:(NSError *)error {
  NSLog(@"Failed to find user's location: \(error.localizedDescription)");
}

func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
  if (status == kCLAuthorizationStatusAuthorizedWhenInUse) {
    manager.requestLocation()
  }
}

func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
  let userLocation:CLLocation = locations[0] as CLLocation
  CLGeocoder().reverseGeocodeLocation(userLocation) { (placemarks, error) in
    if error == nil {
      AppCenter.countryCode = placemarks?.first?.isoCountryCode
    }
  }
}
  
func locationManager(_ Manager: CLLocationManager, didFailWithError error: Error) {
  print("Failed to find user's location: \(error.localizedDescription)")
}

自定义事件

可以使用 最多 20 个属性 跟踪自己的自定义事件，以了解应用中发生的情况、了解用户作，并在 App Center 门户中查看聚合。

启动 SDK 后，使用trackEvent:withProperties方法通过属性来跟踪事件。最多可以发送 200 个不同的事件名称。此外，每个事件名称和事件属性值的最大限制为 256 个字符，每个事件属性名称和事件属性值限制为 125 个字符。

NSDictionary *properties = @{@"Category" : @"Music", @"FileName" : @"favorite.avi"};
[MSACAnalytics trackEvent:@"Video clicked" withProperties: properties];

Analytics.trackEvent("Video clicked", withProperties: ["Category" : "Music", "FileName" : "favorite.avi"])

事件的属性是完全可选的 – 如果只想跟踪事件，请改用此示例：

[MSACAnalytics trackEvent:@"Video clicked"];

Analytics.trackEvent("Video clicked")

事件优先级和持久性

可以跟踪比其他事件重要性更高的业务关键事件。

开发人员可以将事件优先级设置为 “正常 ”（FlagsNormal 在 API 中）或 “关键 ”（FlagsCritical 在 API 中）。
优先级设置为 “关键 ”的事件将首先从存储中检索，并在正常事件之前发送。
当本地存储已满并且需要存储新事件时。首先删除具有最低优先级的最旧事件，以便为新事件腾出空间。
如果存储充满了具有严重优先级的日志，则跟踪具有正常优先级的事件将失败，因为 SDK 在这种情况下无法腾出空间。
如果使用崩溃服务，崩溃日志将设置为 “严重 ”，并共享与事件相同的存储。
传输间隔仅适用于正常事件，关键事件将在 3 秒后发送。

可以使用以下 API 将事件跟踪为严重事件：

NSDictionary *properties = @{@"Category" : @"Music", @"FileName" : @"favorite.avi"};
[MSACAnalytics trackEvent:@"Video clicked" withProperties:properties flags:MSACFlagsCritical];

// If you're using name only, you can pass nil as properties.

let properties = ["Category" : "Music", "FileName" : "favorite.avi"];
Analytics.trackEvent("Video clicked", withProperties: properties, flags: .critical)

// If you're using name only, you can pass nil as properties.

暂停和恢复发送日志

当应用需要控制网络带宽以满足更多业务关键需求时，暂停事件传输非常有用。可以暂停将日志发送到 App Center 后端。暂停时，仍可以跟踪和保存事件，但不会立即发送事件。应用在暂停时跟踪的任何事件只有在调用 resume后才会发送。

[MSACAnalytics pause];
[MSACAnalytics resume];

Analytics.pause()
Analytics.resume()

在运行时启用或禁用 App Center Analytics

可以在运行时启用或禁用 App Center Analytics。如果禁用它，SDK 不会为应用收集更多分析信息。

[MSACAnalytics setEnabled:NO];

Analytics.enabled = false

若要再次启用 App Center Analytics，请使用相同的 API，但作为参数传递 YES/true 。

[MSACAnalytics setEnabled:YES];

Analytics.enabled = true

状态在应用程序启动时保留在设备的存储中。

注释

此方法只能在启动 Analytics 后使用。

检查是否已启用 App Center Analytics

还可以检查 App Center Analytics 是否已启用。

[MSACAnalytics isEnabled];

Analytics.enabled

注释

此方法必须在 Analytics 启动后才可使用，否则在启动之前，它将始终返回 NO 或 false。

管理启动会话

默认情况下，会话 ID 取决于应用程序的生命周期。如果要手动控制新会话的开始，请执行以下步骤：

注释

请注意 ，Analytics.StartSession（） API 的每个调用都会生成一个新会话。如果处于手动会话跟踪器模式，则不会调用此 API，则所有发送日志都将具有 null 会话值。

注释

请注意，新应用程序启动后，将重新生成会话 ID。

在 SDK 启动之前调用以下方法：

[MSACAnalytics enableManualSessionTracker];

Analytics.enableManualSessionTracker()

然后，可以在startSession之后使用 AppCenter.start API。

[MSACAnalytics startSession];

Analytics.startSession()

本地存储大小

默认情况下，SDK 将所有日志存储到 10 MB。开发人员可以使用 API 来增加存储大小，SDK 将一直存储日志，直到存储已满。

无 Internet 访问

当没有任何网络连接时，SDK 将最多 10 MB 的日志保存在本地存储中。存储完成后，SDK 将开始放弃旧日志，为新日志腾出空间。网络连接返回后，SDK 会在 50 秒或每 6 秒后发送一批日志（默认情况下）。

注释

超过 25 天的日志将被丢弃。

批处理事件日志

App Center SDK 在 50 批中上传日志，如果 SDK 没有 50 个要发送的日志，它仍将在 6 秒后（默认情况下）发送日志。最多可以并行发送三批。传输间隔可以更改：

// Change transmission interval to 10 seconds.
[MSACAnalytics setTransmissionInterval:10000];

// Change transmission interval to 10 seconds.
Analytics.transmissionInterval = 10000

传输间隔值必须介于 6 秒到 86400 秒（一天）之间，并且必须在服务启动之前调用此方法。

重试和退让逻辑

App Center SDK 支持对可恢复的网络错误进行回退重试。下面是重试逻辑：

每个请求最多尝试三次。
每个请求都有自己的重试状态机。
在一个请求耗尽所有重试后，所有传输通道都会被禁用，直到应用程序进入下一个处理阶段。

退让逻辑

50% 随机化，第一次重试 5 到 10 秒，第二次重试介于 2.5 到 5 分钟之间，最后尝试 10 到 20 分钟。
如果网络从关机切换到打开（或从 wi-fi 切换到移动设备），则重试状态将重置，并立即重试请求。

通过