# SDK 迁移指南

> Update your User Reporting implementation from version 1.0 to version 2.0 to access the latest features and updates.

User Reporting SDK 现已更新，并影响整个 API。

最显著的是，为了更好地聚焦开发和支持，公共 API 范围已经大幅缩减。

> **Warning:**
>
> **重要提示**：关键的是，这意味着如果您使用的是先前版本的 SDK，则必须升级到新版本才能收到更新。随着我们进一步开发新功能，旧版本可能最终与 Unity Dashboard（Unity 后台）或 User Reporting 后端的未来更改不兼容。

**User Reporting 1.0** 是指旧版 SDK；您可以在[这里](https://userreporting.cloud.unity3d.com/api/userreporting/sdk)找到参考分发。**User Reporting 2.0** 是指 Unity Package Manager 中可用的更新 SDK。

## 重大变化##significant-changes

* 整个 API 现在位于 `Unity.Services.UserReporting` 命名空间中。
* 该 API 现在通过 `Unity.Services.UserReporting.Instance` 使用单个访问点。
* 整个源代码已不再公开，因此 `CyclicalList` 等辅助工具在 SDK 中不再可用。
* 该 SDK 使用外部依赖项，而不是包含源代码依赖项和提供对其的访问，比如 `SimpleJSON` 解析器或 `PngHelper` 类；两者都已被移除。
* 一些错误修复尚未进行回溯，其中包括修复了发送报告时可能发生的内存泄露。
* `AsyncUnityUserReportingPlatform` 已被移除。
* 示例 prefab GUI 现在会根据显示进行缩放。

旧 SDK 中的过时元素不再被视为受支持；如果您的工作依赖于 `SimpleJSON` 解析器等辅助工具，仍然可以继续使用它们，但我们强烈建议您用替代方案替换它们。Unity 将不再维护或支持先前版本 SDK 中的这些元素。

如果您打算在项目中依赖旧的 SDK 辅助工具来提供新功能，比如使用 `PngHelper`，我们建议您探索替代方案，而不是依赖已过时的 SDK。

User Reporting API 专注于与 User Reporting 相关的功能，并有助于防止未来的 API 变动。它还有助于 Unity 专门提供对 SDK User Reporting 方面有意义的支持和改进。

## 使用新的示例预制件##use-the-new-example-prefab

旧版 SDK 中包含的示例起点已经进行了更新和替换。它提供了相同的最终用户功能，并且可以在场景中进行替换。

## 创建报告##create-a-report

用户报告对象不再手动创建。一次只能创建并发送一个报告。正在进行的报告被称为“进行中”报告。如果创建新的用户报告，它将清除先前的进行中报告（如果存在的话）。

`UserReportingService.Instance.CreateNewUserReport();`

如果您希望同时收集和整理多个报告的数据，您需要负责数据管理，最终在准备好发送时将这些数据导出为报告。

## 发送报告##send-a-report

该 SDK 现在一次只处理一个报告。该 API 不是将 UserReport 对象提供给 send 方法，而是有一个单独的调用来发送进行中报告：`UserReportingService.Instance.SendUserReport(...)`。

此外，进行中报告现在不再只有一个回调，而是提供了两个单独的可选回调：一个用于提交进度更新，另一个用于报告提交尝试结束时。

```cs
UserReportingService.Instance.SendUserReport(
(uploadProgress) =>
{
	// The progressUpdate Action uses the uploadProgress float to indicate progress from 0.0 -> 1.0
	Debug.Log("${uploadProgress:P}");

},
(success) =>
{
	// The result Action uses the success bool to indicate whether or not the submission succeeded
	if (!success)
	{
		Debug.Log("Failed to send report!");
	}
});
```

## 关于添加数据的一般性更改##general-changes-to-adding-data

将个别对象值添加到个别报告对象的列表时，使用了一个专用函数，其参数与过去使用的构造函数相同并适用于各处。

请查看以下示例，这种情况下添加了一个新的报告维度：

1.0 添加新报告维度示例：

```cs
UserReport current;
UnityUserReporting.CurrentClient.CreateUserReport((report) => 
{
	current = report;
});
current.Dimensions.Add(new UserReportNamedValue("Category", “Value”));
```

2.0 添加新报告维度示例：

`UserReportingService.Instance.AddDimensionValue("Category", “Value”);`

## 添加自定义附件##add-custom-attachments

该 SDK 现在有一个函数，可以将附件添加到进行中报告，而不是直接将附件添加到用户报告对象本身：

```cs
string content = "{}"; // An empty JSON object for example purposes.
UserReportingService.Instance.AddAttachmentToReport("Sample Attachment JSON", "SampleAttachment.json", Encoding.UTF8.GetBytes(content), "application/json");
```

添加（设备）元数据：“设备元数据”通常简称为元数据。同样，现在有一个专门用于此目的的函数。

`UserReportingService.Instance.AddMetadata(“Example Name”, “Example Value”)`

## 总结##conclusion

截至本文撰写时，User Reporting 面板仍符合本文描述。

在升级到该 SDK 的最新版本时，请参阅官方 User Reporting 文档。