# 迁移到版本 5.0.0

> Update your code to migrate from Analytics SDK version 4.x to version 5.0.0.

新的 Analytics SDK 5.0.0 版本对 SDK 初始化和同意流程进行了大量更改。本指南将帮助您了解这些更改。

> **Note:**
>
> 版本 5.0.0 中仍然存在旧版初始化和同意逻辑，以便在迁移期间向后兼容，但您应尽早切换到新版逻辑，以确保 SDK 按预期工作。旧版流程操作标有 `Obsolete` 属性，并将在 SDK 的未来版本中移除。

旧版初始化流程包含许多自动步骤，包括查找玩家的位置（使用 GeoIP）以确定数据收集是否需要同意，以及是否允许数据收集直到明确撤销。此流程发生了变化。

在新版初始化流程中，SDK **不会**查找玩家的位置，也**不会**自动执行任何活动。新版初始化流程要求通过调用 `StartDataCollection()` 方法来显式激活 SDK。**仅当**满足以下条件之一时，才应调用此方法：

* 您已征得玩家同意根据相应数据隐私法规收集他们的数据。
* 与玩家相关的数据隐私法规不要求用户明确同意，但他们也没有明确选择退出。
* 玩家不受任何数据隐私法规的约束。

调用 `UnityServices.InitializeAsync()` 仍会初始化 Analytics SDK。但是，此初始化只会将 SDK 放入内存，其一直处于“休眠”状态，直到您通过调用 `StartDataCollection()` 将其显式激活。同样，如果使用 `StopDataCollecton()` 方法停用 SDK，则 SDK 将保留在内存中，因此，如果玩家在初始化后的某个时间授予或恢复同意，您可以稍后重新激活 SDK。

> **Note:**
>
> 从新版或旧版流程调用方法时，这会将 SDK 锁定为仅接受与该流程关联的进一步调用。如果尝试同时从这两个流程调用方法，则会抛出异常。

## 初始化流程##initialization-flow

以前，初始化流程如下：

```cs
await UnityServices.InitializeAsync();
List<string> requiredConsents = await AnalyticsService.Instance.CheckForRequiredConsents();

if (consents.Count > 0)
{
	// Show UI element asking the user for their consent //

	bool userGaveConsent = ...

	foreach (string legislationIdentifier in requiredConsents)
	{
		AnalyticsService.Instance.ProvideOptInConsent(identifier, userGaveConsent);
	}
}
```

在 5.0.0 版之前的 SDK 版本中，服务初始化时会发出 Web 请求来查找玩家的位置（并确定玩家是否位于受某些隐私法规约束的区域）。如果此请求失败，则会在 `CheckForRequiredConsents()` 调用中重试。如果第二次尝试失败，SDK 将无法收集数据。这种情况实际上要求应用程序使用互联网连接进行初始化以便收集数据（无论以前是否已同意），并要求可以对事件进行批处理和存储以便在连接恢复时上传。

新版初始化流程不会发出任何 Web 请求。取而代之的要求是您必须构建自己的逻辑，以确定玩家所在的区域是否有某种数据隐私法规要求征得用户同意后才能收集其个人数据。确定已征得玩家同意后，请调用 `StartDataCollection()` 方法以启用 SDK 并开始收集个人数据。如果玩家不同意，无需执行任何操作，因为 SDK 在明确得到 `StartDataCollection()` 信号之前一直处于休眠状态。

> **Note:**
>
> 如需更多有关正确遵守数据隐私法规的信息，请参阅我们的页面：[数据隐私](../privacy-and-consent/manage-data-privacy)、[遵循 GDPR 和 CCPA](../privacy-and-consent/privacy-overview) 以及遵循 PIPL。您还应该咨询自己的律师。

初始化流程现在应如下所示：

```cs
await UnityServices.InitializeAsync();

// Show UI element asking the user for their consent OR retrieve prior consent from storage //

bool userGaveConsent = ...

if (userGaveConsent)
{
	AnalyticsService.Instance.StartDataCollection();
}
```

您可以在服务初始化后随时调用 `StartDataCollection()` 方法以开始数据收集。不需要在应用启动时立即调用此方法。

> **Note:**
>
> SDK 处于休眠状态时记录的事件将被丢弃。这些事件**不会**保存到缓冲区供稍后调用 `StartDataCollection()` 时进行发送。**只有**在您调用 `StartDataCollection()` 后才会记录事件。

> **Note:**
>
> 现在会在调用 `StartDataCollection()` 方法时记录启动事件（如 **gameStarted** 和 **clientDevice**），而不是在调用此方法之前记录。如果在单个会话中启动数据收集，然后停止并再次启动，这种情况下仅在第一个 `StartDataCollection()` 中记录一次。

## 选择退出##opting-out

以前，`OptOut()` 方法会禁用 SDK，将其从内存中移除，并触发玩家的数据删除请求。这种情况使得玩家很难在以后改变主意并再次接受数据收集，因为 SDK 会保留其对于“已撤销同意”状态的认知，并阻止进一步初始化。此时请求删除数据也是不必要的，因为玩家选择退出后续个人数据收集并不一定意味着他们也希望清除以前收集的数据。

调用新的 `StopDataCollection()` 方法时，只会禁用 SDK，将其保留在内存中，以便以后在需要时重新激活。SDK 会尝试对截至该时间点已记录的所有事件进行最终上传，然后丢弃所有其他事件。

如果玩家还希望请求从后端清除其数据，必须单独调用 `RequestDataDeletion()` 方法。

> **Note:**
>
> 数据删除机制会继续尝试发送请求，直到请求成功，如有必要，甚至可以跨会话发送请求。Analytics SDK 使用 `PlayerPrefs` API 记住此状态，因此调用 `PlayerPrefs.DeleteAll()` 可能会中断该过程。

如果玩家选择退出数据收集而未请求删除数据，您仍然可以使用 `RequestDataDeletion()` 方法请求稍后清除其数据。无论 SDK 是处于激活状态还是休眠状态，您都可以随时调用此方法。