# Push Notifications SDK

> Register for Push Notifications and configure the SDK for your platform.

使用 Push Notifications SDK 可以向用户发送推送通知广告系列，包括带有图像的丰富推送通知。

## 平台支持##platform-support

此 SDK 支持 iOS 和 Android，但必须是 iOS 10+ 和 Android SDK >= 26 (Oreo)。

## 快速入门##quick-start

此 SDK 附带一个用于注册 Push Notifications 的示例脚本。请将这个脚本添加到您的项目中，并在编辑器的 Project Settings（项目设置）下进行相关设置。

## 注册 Push Notifications##registering-for-push-notifications

注册 Push Notifications 需要三个步骤。

1. 填写[编辑器中的设置](./get-started.md)。这些设置可以在 **Project Settings（项目设置）**> **Services（服务）**> **Push Notifications** 中找到。
2. [初始化 Unity Services](./get-started.md)，以便可以将所需的 Analytics 事件发送到 Unity Analytics。为了正确发送所需的事件，您还需要实现[隐私流程](/analytics/privacy-and-consent/manage-data-privacy.md)。
3. 在游戏的启动代码中注册通知，以确保不会错过任何通知。但是，在首次注册时，会向用户显示权限请求，因此请确保在游戏中方便的位置进行此调用。SDK 将处理通知内容（包括图像、标题和消息正文）的显示。

> **Note:**
>
> 为确保正确发送与推送通知数据相关的事件，需要使用 Analytics。要处理隐私同意，请参阅 Analytics 文档了解更多详细信息。

代码示例：

```cs
using Unity.Services.Analytics;
using Unity.Services.Core;
using Unity.Services.PushNotifications;
...

await UnityServices.InitializeAsync();

bool userGaveConsent = ...;

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

try
{
    string pushToken = await PushNotificationsService.Instance.RegisterForPushNotificationsAsync();

    PushNotificationsService.Instance.OnNotificationReceived += notificationData =>
    {
        Debug.Log("Received a notification!");
    };
}
catch (Exception e)
{
    Debug.Log("Failed to retrieve a push notification token.");
}
```

### 收到通知回调##notification-received-callbacks

您可以注册一个委托，以便在收到通知时接收 C# 事件回调，进而在此时执行自定义行为。为此，请向 `PushNotifications.OnNotificationReceived` 添加委托/方法回调，如上面的示例所示。

### Push Notifications 设置##push-notifications-settings

此 SDK 需要进行多种设置才能正常运行。某些设置仅在特定平台上使用（在设置名称中会进行指示）。您可以进行以下 Android (Firebase) 设置：

您可以在 **Unity 编辑器** > **Edit（编辑）**> **Project Settings（项目设置）**> **Services（服务）**> **Push Notifications** 中找到这些设置。以下所有字段的值都可以在 Firebase 后台的 Settings（设置）页面中找到。

* **FirebaseWebApiKey**：用于 Android Firebase Cloud Messaging API 的 Firebase 项目“Web API Key（Web API 密钥）”。如果您的项目未显示此字段，您可能需要先启用 Firebase 身份验证。
* **FirebaseProjectNumber**：用于 Android Firebase Cloud Messaging 的“Project Number（项目编号）”。
* **FirebaseAppID**：用于 Android Firebase Cloud Messaging API 的 Firebase 应用程序“App ID”。
* **FirebaseProjectID**：用于 Android Firebase Cloud Messaging API 的 Firebase 项目“Project ID”。

> **Note:**
>
> 如果您没有在 Firebase 中设置 Android 应用程序，则需要添加一个应用程序。除了在 Firebase 中创建应用外，“Add app（添加应用）”向导还会在随后立即提供有关如何集成 Firebase SDK 的说明。请注意，**您无需安装 Firebase SDK**，可以放心地忽略涉及向项目添加文件或 Firebase SDK 的所有步骤。


**Frame:**
![](/api/media?file=/push-notifications/media/images/project-settings.png)

在 **Edit（编辑）**> **Project Settings（项目设置）**> **Services（服务）**> **Push Notifications** 中进行这些设置。

必须为较新的项目启用 Cloud Messaging API：

1. 选择已禁用的 Cloud Messaging API (Legacy)（Cloud Messaging API（旧版））旁边的三点图标。
2. 选择 ENABLE Cloud Messaging API (Legacy)（启用 Cloud Messaging API（旧版））。
3. 刷新 Firebase 控制台。


**Frame:**
![](/api/media?file=/push-notifications/media/images/cloud-messaging.png)

### Analytics##analytics

此 SDK 会记录两个 Analytics 事件：

* **notificationServices：** 每当在客户端上注册新令牌时，都会记录此事件。此事件中包含推送令牌，用于向后端服务注册这个令牌，从 Unity Dashboard（Unity 后台）发送通知，并且是该产品正常运行的必要条件。
* **notificationOpened：** 每当用户打开通知时，都会记录此事件。此事件中包含有关用户所在广告系列和群组的数据，以及是否从通知中启动了应用。

#### 仅 Analytics 模式##analytics-only-mode

> **Warning:**
>
> 仅当您尝试将 Unity Dashboard（Unity 后台）Push Notifications 服务与单独的推送通知实现方案搭配使用时，本节的内容才适用。对于大多数用户来说，本节不是必需的，也不建议使用，因为这种模式会导致产品功能减少。

如果需要，可以将此 SDK 与现有推送通知服务集成。为此，请不要调用上述注册方法，而是将 `PushNotificationsService.Instance.Analytics` 中的两个方法与现有实现方案搭配使用。

当您收到设备的新推送令牌时，应调用 `RecordPushTokenUpdated`。请注意，操作系统可能会在应用程序生命周期的多个点创建新令牌，因此应在每次令牌更改时（而不仅仅是在启动时）进行此调用。完整的调用为 `PushNotificationsService.Instance.Analytics.RecordPushTokenUpdated(token);`。

打开通知时应调用 `RecordNotificationOpened`。此调用接受一个字典（即通知有效负载中包含的数据）以及一个布尔标志（指示是否从通知中启动了应用）。完整的调用为 `PushNotificationsService.Instance.Analytics.RecordNotificationOpened(notificationData);`。

请注意，此后，您应该可以从 Unity Dashboard（Unity 后台）中发送和计划通知。但是，这种情况下，很大程度上取决于您已有的其他推送通知实现方案，并可能导致通知中缺少图像或其他内容，因此强烈建议使用标准设置，如果可能，将此 SDK 作为唯一集成的 Push Notifications 解决方案。

## 测试 SDK 集成##testing-the-sdk-integration

您可以在应用中按照以下步骤测试 Push Notifications SDK 集成。

> **Note:**
>
> 在执行这些步骤之前，您需要先按照[开始使用](./get-started.md)页面中的步骤操作。

1. 在应用中，获取 PushNotificationsService 令牌，并使用 \`Debug.Log\` 将此令牌写入日志。

2. 根据您的目标平台，按照适用于 [Android](https://docs.unity3d.com/2021.2/Documentation/Manual/android-debugging-on-an-android-device.html) 的调试指南或适用于 [iOS](https://docs.unity3d.com/2021.2/Documentation/Manual/iphone-BuildProcess.html) 的构建和运行指南来运行您的应用。

3. 读取应用日志以获取记录的令牌。

   1. **对于 Android**：使用 [Android Logcat](https://docs.unity3d.com/Packages/com.unity.mobile.android-logcat@latest) 包。
   2. **对于 iOS**：运行应用时检查 XCODE 中的日志。

4. 在 UGS Dashboard（UGS 后台）中，转到现有的推送通知广告系列或创建新的虚拟推送通知广告系列。

5. 在“Content（内容）”步骤中，创建通知（如有必要）并转到“Test on Device（在设备上测试）”。


**Frame:**
![](/api/media?file=/push-notifications/media/images/test-on-device.png)

6. 选择目标设备并输入获取的令牌。


**Frame:**
![](/api/media?file=/push-notifications/media/images/send-test.png)

7. 选择 **Send（发送）**，然后查看设备是否收到通知。

## External Dependency Manager for Unity (EDM4U) 支持##external-dependency-manager-for-unity-edm4u-support

> **Note:**
>
> 适用于将 EDM4U 或 MDR 与 Push Notifications 集成在一起的用户。

其他 SDK 或 Unity 包（包括 Google 的 Firebase Unity 包）使用 [External Dependency Manager for Unity (EDM4U)](https://github.com/googlesamples/unity-jar-resolver) 或 Mobile Dependency Resolver (MDR) 来解析其在 Unity 项目中的依赖项。

Push Notifications SDK **不**需要使用 EDM4U 或 MDR 来解析其在 Unity 项目中的依赖项，默认情况下也不会重新分发或使用 EDM4U 或 MDR。

但是，从版本 `3.0.1-pre.1` 开始，如果使用了 EDM4U 或 MDR，Push Notifications SDK 会通过在自动生成的 `Assets/Push Notifications/Editor/Android` 目录中生成依赖项文件 (PushSDKDependencies.xml) 来与它们集成。

在构建应用程序之前，应运行 `Resolve` 或 `Force Resolve`（均位于 **Assets（资源）> External Dependency Manager > Android Manager** 下）来确保已解析 Push Notifications SDK 的依赖项。您可以使用 `Display Libraries` 选项（**Assets（资源）> External Dependency Manager > Android Manager > Display Libraries（显示库）**）确认已解析这些依赖项。


**Frame:**
![](/api/media?file=/push-notifications/media/images/edm4u-options.png)

应该会显示以下行：

```text
implementation 'com.google.firebase:firebase-messaging-ktx:22.0.0' // Assets/Push Notifications/Editor/Android/PushSDKDependencies.xml:9
```

请注意，如果其他包也需要同样的依赖项，则注释可能会有所不同。如果是这种情况，EDM4U 将在相邻的注释中列出从中提取依赖项的所有文件。只要依赖文件路径 (`Assets/Push Notifications/Editor/Android/PushSDKDependencies.xml:9`) 出现在注释中，就可以确定 EDM4U/MDR 已成功检测并读取依赖项文件。

如果**未**显示此行，请确保依赖项文件存在于 `Assets/Push Notifications/Editor/Android` 目录下，然后再次尝试使用 `Force Resolve` 选项（**Assets（资源）> External Dependency Manager > Android Manager > Force Resolve（强制解析）**）。

如果尚未生成依赖项文件，请重新打开您的项目。在这个过程期间应该会生成依赖项文件。