Push Notifications SDK

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

平台支持

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

快速入门

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

注册 Push Notifications

注册 Push Notifications 需要三个步骤。

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

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

代码示例：

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.");
}

收到通知回调

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

Push Notifications 设置

此 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”。

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

在 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 控制台。

Analytics

此 SDK 会记录两个 Analytics 事件：

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

仅 Analytics 模式

仅当您尝试将 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 集成

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

在执行这些步骤之前，您需要先按照开始使用页面中的步骤操作。

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

  2. 根据您的目标平台，按照适用于 Android 的调试指南或适用于 iOS 的构建和运行指南来运行您的应用。

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

    1. 对于 Android：使用 Android Logcat 包。
    2. 对于 iOS：运行应用时检查 XCODE 中的日志。

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

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

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

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

External Dependency Manager for Unity (EDM4U) 支持

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

其他 SDK 或 Unity 包（包括 Google 的 Firebase Unity 包）使用 External Dependency Manager for Unity (EDM4U) 或 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（显示库））确认已解析这些依赖项。

应该会显示以下行：

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（强制解析））。

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

Unity logo Documentation
Copyright © 2025 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.