适用于 macOS 的 App Center Analytics - Visual Studio App Center

会话和设备信息

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

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

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

请确保在设备上启用定位服务。

使用


    CLLocationManager

获取设备的当前位置。

使用


    CLGeocoder

将位置转换为 ISO 国家/地区代码。

使用 SDK


    setCountryCode

的方法替代运营商国家/地区代码。

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

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

@interface AppDelegate () <CLLocationManagerDelegate>
@property(nonatomic) CLLocationManager *locationManager;
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")
事件优先级和持久性
可以跟踪重要性高于其他事件的关键业务事件。
开发人员可以将 API) FlagsNormal 中的事件优先级设置为“正常 (”或 API) 中的“严重 (FlagsCritical”。
优先级设置为 “严重 ”的事件将首先从存储中检索，并在 正常 事件之前发送。
当本地存储已满且需要存储新事件时。 首先删除优先级最低的最旧事件，以便为新事件腾出空间。
如果存储中满是具有 “关键 ”优先级的日志，则跟踪具有 正常 优先级的事件将失败，因为 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 API AppCenter.start：
[MSACAnalytics startSession];
Analytics.startSession()
本地存储大小
默认情况下，SDK 存储所有日志最多 10 MB。 开发人员可以使用 API 来增加 存储大小 ，SDK 将一直存储日志，直到存储已满。
无 Internet 访问
如果没有任何网络连接，SDK 将最多 10 MB 的日志保存在本地存储中。 存储已满后，SDK 将开始放弃旧日志，为新日志腾出空间。 网络连接恢复后，SDK 默认) 每隔 6 秒发送一批 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 支持对可恢复的网络错误进行回退重试。 下面是重试逻辑：
每个请求最多尝试 3 次。
每个请求都有自己的重试状态机。
所有传输通道 (禁用，直到下一个应用进程) 后，一个请求耗尽其所有重试。
50% 随机化，第一次重试在 5 到 10 秒之间，第二次重试在 2.5 到 5 分钟之间，最后一次重试在 10 到 20 分钟之间。
如果网络从关机切换到 (或从 wi-fi 切换到移动) ，则重试状态会重置并立即重试请求。