Unity SDK 基础集成指南

本节包含有关如何将 Pushwoosh Unity SDK 集成到您的应用程序中的信息。

先决条件

要将 Pushwoosh Unity SDK 集成到您的应用中，您需要具备以下条件：

要求

• 一个 Pushwoosh 账户。
• 在您的账户中设置一个 Pushwoosh 项目。
• 对于 iOS 集成：
  • 一个配置为发送推送通知的 iOS 平台。我们建议使用基于令牌的身份验证配置作为最简单的方法。
  • 将网关设置为 Sandbox 以向模拟器发送推送。
• 对于 Android 集成：
  • 一个已配置的 Android 平台
  • 来自您的 Firebase 项目的 project number（也称为发送者 ID）、google-services.json 文件和 package name。
  • 一个连接到您的 Android 应用程序的 Firebase 项目。如果需要，请遵循 Firebase 设置指南。
• 您的 Pushwoosh Application Code 和来自您应用程序的 Pushwoosh 控制面板的 Pushwoosh Device API Token。

集成步骤

1. 添加 Pushwoosh Unity SDK 依赖

将 Unity 推送通知插件导入到您 Unity 的 Assets 文件夹中。

2. Unity SDK 初始化

创建 PushNotificator.cs 脚本并将其附加到场景中的 Camera Object。 在脚本中：

• 使用应用程序代码和 Firebase 项目编号初始化 Pushwoosh SDK。
• 在您的初始化逻辑中调用 RegisterForPushNotifications() 来注册推送通知。
• 添加注册事件处理程序来管理推送注册事件：

PushNotificator.cs

using UnityEngine;
using UnityEngine.UI;

public class PushNotificator : MonoBehaviour {
    void Start () {
        Pushwoosh.ApplicationCode = "__YOUR_APP_ID__";
        Pushwoosh.FcmProjectNumber = "__YOUR_FCM_SENDER_ID__";
        Pushwoosh.Instance.OnRegisteredForPushNotifications += OnRegisteredForPushNotifications;
        Pushwoosh.Instance.OnFailedToRegisteredForPushNotifications += OnFailedToRegisteredForPushNotifications;
        Pushwoosh.Instance.RegisterForPushNotifications();
    }

    void OnRegisteredForPushNotifications(string token) {
        Debug.LogFormat(LogType.Log, LogOption.NoStacktrace, null, "Received token: \n{0}", token);
    }

    void OnFailedToRegisteredForPushNotifications(string error) {
        Debug.LogFormat(LogType.Log, LogOption.NoStacktrace, null, "Error ocurred while registering to push notifications: \n{0}", error);
    }
}

其中：

• __YOUR_APP_ID__ 是来自 Pushwoosh 控制面板的应用程序代码。
• __YOUR_FCM_SENDER_ID__ 是来自 Firebase 控制台的 Firebase 项目编号。

3. iOS 原生设置

3.1 功能 (Capabilities)

要在您的项目中启用推送通知，您需要添加某些功能。

在 “Signing & Capabilities” 部分，添加以下功能：

• Push Notifications
• Background Modes。添加此功能后，勾选 Remote notifications 复选框。

如果您打算使用时效性通知 (iOS 15+)，还需添加 Time Sensitive Notifications 功能。

3.2 Info.plist

在您的 Runner/Info.plist 中，将 __PUSHWOOSH_DEVICE_API_TOKEN__ 键设置为 Pushwoosh Device API Token：

info.plist

<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>

3.3 消息送达跟踪

您必须向您的项目添加一个通知服务扩展 (Notification Service Extension) 目标。这对于在 iOS 上实现准确的送达跟踪和富媒体等功能至关重要。

请遵循原生指南的步骤来添加扩展目标并在其中添加必要的 Pushwoosh 代码。

4. Android 原生设置

4.1 添加 Firebase 配置文件

将 google-services.json 文件放入您项目目录的 Assets 文件夹中。

4.2 调整构建设置

在您的 Android 构建配置文件的 Publishing Settings 部分，启用 Custom Main Manifest 选项。

4.3 添加 Pushwoosh 元数据

在您的 Assets/Plugins/Android/AndroidManifest.xml 文件的 <application> 标签内添加 Pushwoosh Device API Token：

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />

重要提示： 请确保在您的 Pushwoosh 控制面板中为该令牌授予对正确应用的访问权限。了解更多

5. Windows Store 集成

1. 将 link.xml 添加到您的 Assets/ 目录，内容如下：

<linker>
    <assembly fullname="PushSDK" preserve="all"/>
</linker>

2. 您还需要在导出的 Visual Studio 项目中将应用与商店关联。请确保您的应用使用与您的发布者身份匹配的证书进行签名。

在导出的 Visual Studio 项目中，在您的 .appxmanifest 的 Capabilities 选项卡中选择 Internet (Client) 功能。

6. 运行项目

1. 构建并运行项目。
2. 前往 Pushwoosh 控制面板并发送一条推送通知。
3. 您应该会在应用中看到该通知。

扩展集成

至此，您已经集成了 SDK，可以发送和接收推送通知。现在，让我们来探索核心功能。

推送通知事件监听器

在 Pushwoosh SDK 中有两个事件监听器，专为处理推送通知而设计：

• 当收到推送通知时，会触发 OnPushNotificationsReceived 事件
• 当用户打开通知时，会触发 OnPushNotificationsOpened 事件

您应该在 PushNotificator.cs 中初始化 SDK 后立即设置这些事件监听器：

PushNotificator.cs

using UnityEngine;
using UnityEngine.UI;

public class PushNotificator : MonoBehaviour {
    void Start () {
        Pushwoosh.ApplicationCode = "__YOUR_APP_ID__";
        Pushwoosh.FcmProjectNumber = "__YOUR_FCM_SENDER_ID__";
        Pushwoosh.Instance.OnPushNotificationsReceived += OnPushNotificationsReceived;
        Pushwoosh.Instance.OnPushNotificationsOpened += OnPushNotificationsOpened;
        Pushwoosh.Instance.RegisterForPushNotifications();
    }

    void OnPushNotificationsReceived(string payload) {
        Debug.LogFormat(LogType.Log, LogOption.NoStacktrace, null, "Received push notificaiton: \n{0}", payload);
    }

    void OnPushNotificationsOpened(string payload) {
        Debug.LogFormat(LogType.Log, LogOption.NoStacktrace, null, "Opened push notificaiton: \n{0}", payload);
    }

用户配置

通过关注个体用户的行为和偏好，您可以提供个性化内容，从而提高用户满意度和忠诚度。

public class Registration {
  public void afterUserLogin(User user) {

    // 设置用户 ID
    Pushwoosh.Instance.SetUserId(user.getId());

    // 设置用户邮箱
    Pushwoosh.Instance.SetEmail(user.getEmail());

    // 将额外的用户信息设置为 Pushwoosh 的标签
    Pushwoosh.Instance.SetIntTag("Age", user.getAge());
    Pushwoosh.Instance.SetStringTag("Name", user.getName());
    Pushwoosh.Instance.SetStringTag("LastLoginDate", user.getLastLoginDate());
  }
}

标签 (Tags)

标签是分配给用户或设备的键值对，允许根据偏好或行为等属性进行分段，从而实现定向消息传递。

public class UpdateUser {
  public void afterUserUpdateProfile(User user) {

    // 设置喜爱的类别列表
    Pushwoosh.Instance.SetListTag(
      "favorite_categories": user.getFavoriteCategoriesList()
    );

    // 设置支付信息
    Pushwoosh.Instance.SetStringTag("is_subscribed", user.isSubscribed());
    Pushwoosh.Instance.SetStringTag("payment_status", user.getPaymentStatus());
    Pushwoosh.Instance.SetStringTag("billing_address", user.getBillingAddress());
  }
}

事件 (Events)

事件是应用内特定的用户操作或发生的事情，可以被跟踪以分析行为并触发相应的消息或操作。

public class Registration {

  // 跟踪登录事件
  public void afterUserLogin(User user) {
    Pushwoosh.Instance.PostEvent("login", new Dictionary<string, object>() {
      { "name", user.getName() },
      { "last_login", user.getLastLoginDate() }
    });
  }

  public void afterUserPurchase(Product product) {
    // 跟踪购买事件
    Pushwoosh.Instance.PostEvent("purchase", new Dictionary<string, object>() {
      { "product_id", product.getId() },
      { "product_name", product.getName() },
      { "price", product.getPrice() },
      { "quantity", product.getQuantity() }
    });
  }
}

故障排除

如果您在集成过程中遇到任何问题，请参阅支持和社区部分。