App Center Analytics (macOS)
重要
Visual Studio App Center 计划于 2025 年 3 月 31 日停用。 虽然可以继续使用 Visual Studio App Center,直到它完全停用,但你可以考虑迁移到几个建议的替代方法。
App Center Analytics 可帮助你了解用户行为和客户参与度,以改进应用。 SDK 自动捕获会话计数和设备属性,例如模型、OS 版本等。可以定义自己的自定义事件来度量对你很重要的事情。 App Center 门户中提供了捕获的所有信息,用于分析数据。
备注
运营商国家/地区和运营商名称在适用于 macOS 的 App Center Analytics 上不可用,但你可以使用设备位置设置运营商国家/地区。
备注
在 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
。
- 请确保在设备上 启用定位服务 。
- 使用
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")
可以跟踪重要性高于其他事件的关键业务事件。
- 开发人员可以将 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。 如果禁用它,SDK 不会为应用收集任何其他分析信息。
[MSACAnalytics setEnabled:NO];
Analytics.enabled = false
若要再次启用 App Center Analytics,请使用同一 API,但作为参数传递 YES
/true
。
[MSACAnalytics setEnabled:YES];
Analytics.enabled = true
状态在应用程序启动时保留在设备的存储中。
备注
只有在启动后 Analytics
才能使用此方法。
还可以检查是否启用 App Center Analytics。
[MSACAnalytics isEnabled];
Analytics.enabled
备注
此方法必须仅在启动后 Analytics
使用,它始终返回 NO
或在 false
启动之前。
默认情况下,会话 ID 取决于应用程序的生命周期。 如果要手动控制新会话的开始,请执行后续步骤:
备注
请注意,每次调用 Analytics.StartSession () API 都会生成一个新会话。 如果在手动会话跟踪器模式下不会调用此 API,则所有发送日志都将具有 null 会话值。
备注
请注意,新应用程序启动后,将重新生成会话 ID。
- 在 SDK 启动之前调用以下方法:
[MSACAnalytics enableManualSessionTracker];
Analytics.enableManualSessionTracker()
- 然后,可以在 之后使用
startSession
APIAppCenter.start
:
[MSACAnalytics startSession];
Analytics.startSession()
默认情况下,SDK 存储所有日志最多 10 MB。 开发人员可以使用 API 来增加 存储大小 ,SDK 将一直存储日志,直到存储已满。
如果没有任何网络连接,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 切换到移动) ,则重试状态会重置并立即重试请求。