# 配置 User Reporting

> Customize user reports with fields, metadata, attachments, and metrics to match your game's feedback needs.

User Reporting 的默认设置适合一般使用，但随着项目的发展，您可能希望根据特定需求进行更改。您可以构建与应用程序相匹配的自定义 UI 以引入自定义字段，也可以更改用户报告表单的外观。软件包中提供的示例有效，但只是为了帮助您入门。

用户报告包含多种有用的信息，比如元数据、事件、抽样指标、屏幕截图和文件附件。例如，您可以将用户的游戏存档文件附加到其报告中，或者在每次玩家执行特定操作时记录一个事件。您还可以在性能要求高的游戏场景中对性能指标进行抽样。

使用 API 可以配置报告中每种数据类型的最大值。**UserReportExample** 文件（位于导入到 Unity 项目中的示例内）演示了向报告添加数据的不同方式。

例如，您可以自定义以下设置，以限制报告中特定数据类型的最大值：

* `FramesPerMeasure`：一个测量是指标每个收集的样本中涵盖的一组帧。默认测量长度为 60 帧。
* `MaximumMeasureCount`：一个测量是指标样本中涵盖的一组帧，并计算报告中的最大测量次数。默认值为 300 次测量。
* `MaximumEventCount`：此限制适用于报告中包含的事件数量。默认值为 100 个事件。
* `MaximumScreenshotCount`：报告中附加的屏幕截图数量上限。默认值为 10 张屏幕截图。
* `MetricsGatheringMode`：表示指标收集模式。在默认配置下，一些指标，例如每秒帧数 (Graphics.FramesPerSecond)，可以通过自动模式包含在报告中。手动模式仅会在报告中包含您的自定义指标，而禁用模式将完全阻止发送报告中的任何采样指标。

以上设置没有具体限制，但如果您设置较大的值，收集到的数据会影响报告的大小，特别是较大的高分辨率屏幕截图可能会导致报告大小出现大幅增长。

要配置用户报告设置，请调用 `UserReportingService.Instance..Configure(UserReportingClientConfiguration configuration)` 方法：

```cs
var customConfig = new UserReportingClientConfiguration(5, 5, 100, 100, MetricsGatheringMode.Automatic);
UserReportingService.Instance.UserReporting.Configure(customConfig);
```

## 创建和发送报告##create-and-sending-reports

要创建报告，请调用 `UserReportingService.Instance.UserReporting.CreateNewUserReport();`。

要发送报告，请调用 `UserReportingService.Instance.SendUserReport(Action<float> progressUpdate, Action<bool> result)`。

请参考示例以更好地了解操作参数。尽管不是必需的，但建议发送报告。

## 添加元数据##add-metadata

使用元数据可以收集游戏特定的数据，这些数据默认会随设备元数据一起包含在用户报告中。

要添加自定义元数据，请调用 `UserReportingService.Instance.AddMetadata(string name, string value)` 方法。

添加元数据对性能几乎没有影响。

## 记录事件##log-events

要记录自定义事件，请调用 `UserReportingService.Instance.LogEvent(UserReportEventLevel level, string message)` 方法。

记录事件对性能几乎没有影响。

## 添加采样指标##add-sampling-metrics

要添加自定义采样指标，请调用 `UserReportingService.Instance.SampleMetric(string name, double value)` 方法。

`SampleMetric` 方法经过专门设计，使用该方法时每帧调用对性能影响很小。然而，如果您每一帧都调用此方法，每个不同的名称都会显著增加报告的大小。

## 添加屏幕截图##add-screenshots

要向报告中添加屏幕截图，请调用 `UserReportingService.Instance.TakeScreenshot(int maximumWidth, int maximumHeight)` 方法。屏幕截图会在 Dashboard（后台）中作为报告的一部分显示。

您可以选择使用 `UserReportingService.Instance.TakeScreenshot(int maximumWidth, int maximumHeight, object source)` 来指定屏幕截图的来源，比如 Camera 或 RenderTexture。

不管来源如何，图像都将按比例缩小，直到适应由 maximumWidth 和 maximumHeight 参数定义的尺寸。

选择最大宽度和最大高度时，必须确保用户报告小于 10 MB。最后一张屏幕截图将作为报告缩略图显示在 Dashboard（后台）上。

**注意**：截取屏幕截图会对性能产生一定影响。为了避免对用户造成不良影响，请在性能关键时段之外截取屏幕截图，例如玩家处于空闲状态时。

## 添加附件##add-attachments

添加视频和场景图片等附件。

附件会以 Base64 对象的形式编码。

要添加附件，请使用 `UserReportingService.Instance.AddAttachmentToReport(string title, string filename, byte[] data)`。

## 规划报告的维度##organize-report-dimensions

使用维度可以在 Unity Dashboard（Unity 后台）上过滤用户报告。在发送报告之前，您可以通过向维度属性添加项目来向报告中添加维度和指标。每个维度或指标都有一个名称和一个值。您可以通过调用以下方法来向报告中添加新的维度：

`UserReportingService.Instance.AddDimensionValue(string dimension, string value);`

例如，查看带有以下维度的三份报告：

| **名称**           | **值**           |
| ---------------- | --------------- |
| Platform         | Android         |
| Version          | 2               |
| Category         | Graphics        |
| Platform         | WindowsPlayer   |
| Version          | 1               |
| Language         | English         |
| Platform         | WindowsPlayer   |
| Version          | 1               |
| Platform.Version | WindowsPlayer.1 |

查看 Dashboard（后台）上的以下过滤选项：

| **维度名称**         | **维度值**          |
| ---------------- | ---------------- |
| Category         | Graphics         |
| Language         | English          |
| Platform         | Android          |
| Platform         | WindowsPlayer    |
| Platform.Version | WindowsPlayer: 1 |
| Version          | 1                |
| Version          | 2                |

您还可以为不同的报告添加不同的维度。例如，您可能只想在本地化报告中添加 SystemLanguage 作为一个维度。

用户还可以在报告摘要中添加单个井号标签。该井号标签会显示为一个维度。

例如，摘要“我掉到地板下了 #FloorBug”将显示为：

| **维度名称** | **维度值**  |
| -------- | -------- |
| Hash Tag | FloorBug |