App Center Analytics (Windows)

项目
03/15/2024

重要

Visual Studio App Center 计划于 2025 年 3 月 31 日停用。虽然可以继续使用 Visual Studio App Center，直到它完全停用，但你可以考虑迁移到几个建议的替代方法。

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

如果尚未在应用程序中设置 SDK，请遵循 WPF/WinForms 入门或 UWP/WinUI 入门部分 (基于平台) 。

此页面中的说明适用于 UWP (包括 Xamarin.Forms 和 WinUI) 、WPF 和 WinForms。

会话和设备信息

将 App Center Analytics 添加到应用并启动 SDK 后，它将自动跟踪会话和设备属性，例如 OS 版本、模型等。

注意

在 WinUI 应用中，由于 UWP 应用的生命周期细节，会话量可能低于 UWP 应用。

国家/地区代码

SDK 不会自动报告国家/地区代码。如果要手动报告，可以按照以下平台的说明进行操作。

UWP

请确保为应用启用位置功能。
获取必应地图身份验证密钥。
在调用 AppCenter.Start(... typeof(Analytics) ...);之前，在任意位置使用以下代码。作为 BingMapsToken，使用在步骤 2 中获取的密钥。

private static async Task SetCountryCode()
{
    // The following country code is used only as a fallback for the main implementation.
    // This fallback country code doesn't reflect the physical device location, but rather the
    // country that corresponds to the culture it uses.
    var countryCode = new GeographicRegion().CodeTwoLetter;
    var accessStatus = await Geolocator.RequestAccessAsync();
    switch (accessStatus)
    {
        case GeolocationAccessStatus.Allowed:
            var geoLocator = new Geolocator
            {
                DesiredAccuracyInMeters = 100
            };
            var position = await geoLocator.GetGeopositionAsync();
            var myLocation = new BasicGeoposition
            {
                Longitude = position.Coordinate.Point.Position.Longitude,
                Latitude = position.Coordinate.Point.Position.Latitude
            };
            var pointToReverseGeocode = new Geopoint(myLocation);
            MapService.ServiceToken = Constants.BingMapsAuthKey;
            var result = await MapLocationFinder.FindLocationsAtAsync(pointToReverseGeocode);
            if (result.Status != MapLocationFinderStatus.Success || result.Locations == null || result.Locations.Count == 0)
            {
                break;
            }

            // The returned country code is in 3-letter format (ISO 3166-1 alpha-3).
            // Below we convert it to ISO 3166-1 alpha-2 (two letter).
            var country = result.Locations[0].Address.CountryCode;
            countryCode = new GeographicRegion(country).CodeTwoLetter;
            break;
        case GeolocationAccessStatus.Denied:
            AppCenterLog.Info(LogTag, "Geolocation access denied. To set country code in App Center, enable location service in Windows 10.");
            break;
        case GeolocationAccessStatus.Unspecified:
            break;
    }
    AppCenter.SetCountryCode(countryCode);
}

注意

对于要在 Analytics 会话上显示的国家/地区代码， AppCenter.SetCountryCode 必须在调用之前调用 AppCenter.Start。

WPF/WinForms

由于 WPF/WinForms 平台没有地理位置 API，因此可以使用系统国家/地区代码。

using System.Globalization;

private static void SetCountryCode()
{
    // This fallback country code doesn't reflect the physical device location, but rather the
    // country that corresponds to the culture it uses.
    var countryCode = RegionInfo.CurrentRegion.TwoLetterISORegionName;
    AppCenter.SetCountryCode(countryCode);
}

注意

对于要在 Analytics 会话上显示的国家/地区代码， AppCenter.SetCountryCode 必须在调用之前调用 AppCenter.Start。

自定义事件

可以使用 最多 20 个属性 跟踪自己的自定义事件，以了解用户与应用之间的交互。

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

Analytics.TrackEvent("Video clicked", new Dictionary<string, string> {
    { "Category", "Music" },
    { "FileName", "favorite.avi"}
});

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

Analytics.TrackEvent("Video clicked");

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

可以在运行时启用和禁用 App Center Analytics。如果禁用它，SDK 将不会为应用收集任何其他分析信息。

Analytics.SetEnabledAsync(false);

若要再次启用 App Center Analytics，请使用同一 API，但将作为参数传递 true 。

Analytics.SetEnabledAsync(true);

无需等待此调用， (其他 API 调用（如 IsEnabledAsync) 一致）。

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

检查是否启用了 App Center Analytics

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

bool isEnabled = await Analytics.IsEnabledAsync();

管理启动会话

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

注意

请注意，每次调用 Analytics.StartSession () API 都会生成一个新会话。如果在手动会话跟踪器模式下不会调用此 API，则所有发送日志都将具有空会话值。

注意

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

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

Analytics.EnableManualSessionTracker();

然后，可以在之后使用 StartSession API AppCenter.Start：

Analytics.StartSession();

本地存储大小

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

无法访问 Internet

如果没有任何网络连接，SDK 将最多 10 MB 的日志保存在本地存储中。存储已满后，SDK 将开始放弃旧日志，为新日志腾出空间。设备重新访问 Internet 后，SDK 将每隔 6 秒发送一批 50 或每 6 秒发送一次日志。

批处理事件日志

App Center SDK 分批上传 50 个日志，如果 SDK 没有 50 个要发送的日志，它仍将在 6 秒后发送日志。最多可以并行发送三个批。

重试和退让逻辑

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

3 次尝试每个请求的最大值。
每个请求都有自己的重试状态机。
所有传输通道 (禁用，直到下一个应用进程在一个请求耗尽其所有重试后) 。

退让逻辑

50% 随机化，第一次重试在 5 秒到 10 秒之间，第二次重试在 2.5 到 5 分钟之间，最后一次重试在 10 到 20 分钟之间。
如果网络从关闭切换到 (或从 wi-fi 切换到移动) ，则会重置重试状态并立即重试请求。