Unity SDK 基本集成指南

本指南将引导您将 Pushwoosh Unity SDK 集成到您的应用程序中。

先决条件

集成步骤

1. 添加 Pushwoosh Unity SDK

将以下内容添加到您的 Packages/manifest.json 中：

{
  "dependencies": {
    "com.pushwoosh.unity.core": "6.2.7",
    "com.pushwoosh.unity.android": "6.2.7",
    "com.pushwoosh.unity.ios": "6.2.7"
  },
  "scopedRegistries": [
    {
      "name": "npmjs",
      "url": "https://registry.npmjs.org",
      "scopes": ["com.pushwoosh"]
    }
  ]
}

仅添加您需要的平台包。例如，如果您只针对 iOS，则省略 com.pushwoosh.unity.android。

在 Unity 中，转到 Window > Package Manager > + > Add package from git URL，然后逐个添加以下 URL：

https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.core
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.android
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.ios

从 GitHub Releases 下载 Pushwoosh.unitypackage，然后通过 Assets > Import Package > Custom Package 导入。

2. 安装 External Dependency Manager

该 SDK 需要 External Dependency Manager for Unity (EDM4U) 来解析原生的 Android 和 iOS 依赖项。

将以下 scoped registry 添加到您的 Packages/manifest.json 中：

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.google.external-dependency-manager"]
    }
  ]
}

然后将该包添加到您的依赖项中：

"com.google.external-dependency-manager": "1.2.183"

3. 初始化 SDK

创建一个 PushNotificator.cs 脚本并将其附加到场景中的任何 GameObject 上：

using UnityEngine;
using System.Collections.Generic;

public class PushNotificator : MonoBehaviour
{
    void Start()
    {
        Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
        Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

        Pushwoosh.Instance.OnRegisteredForPushNotifications += (token) => {
            Debug.Log("Push token: " + token);
        };

        Pushwoosh.Instance.OnFailedToRegisteredForPushNotifications += (error) => {
            Debug.Log("Registration failed: " + error);
        };

        Pushwoosh.Instance.RegisterForPushNotifications();
    }
}

替换：

XXXXX-XXXXX 为您的 Pushwoosh Application Code。
XXXXXXXXXXXX 为您的 Firebase 项目编号 (仅限 Android)。

4. iOS 原生设置

4.1 Capabilities

从 Unity 构建 iOS 项目后，打开生成的 Xcode 项目并在 Signing & Capabilities 中添加以下功能：

Push Notifications
Background Modes 并勾选 Remote notifications

对于时间敏感通知 (iOS 15+)，还需添加 Time Sensitive Notifications 功能。

4.2 Info.plist

将 Pushwoosh Device API Token 添加到您的 Info.plist 中：

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

4.3 消息送达跟踪

向您的 Xcode 项目添加一个 Notification Service Extension 目标。这是在 iOS 上实现精确送达跟踪和富媒体所必需的。

按照原生指南添加扩展目标。

5. Android 原生设置

5.1 添加 Firebase 配置文件

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

5.2 添加 Pushwoosh 元数据

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

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

6. 运行项目

在您的目标平台上构建并运行项目。
在出现提示时授予推送通知权限。
转到 Pushwoosh 控制面板并发送一条推送通知。

扩展集成

在此阶段，您已经可以发送和接收推送通知。以下部分将介绍 SDK 的核心功能。

推送通知事件监听器

SDK 提供了两个用于处理推送通知的事件监听器：

OnPushNotificationsReceived — 当推送通知到达时触发
OnPushNotificationsOpened — 当用户点击通知时触发

在 SDK 初始化期间设置这些监听器：

void Start()
{
    Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
    Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

    Pushwoosh.Instance.OnPushNotificationsReceived += (payload) => {
        Debug.Log("Push received: " + payload);
    };

    Pushwoosh.Instance.OnPushNotificationsOpened += (payload) => {
        Debug.Log("Push opened: " + payload);
    };

    Pushwoosh.Instance.RegisterForPushNotifications();
}

用户配置

通过识别用户并设置其属性来个性化推送通知：

// 设置用户 ID 以进行跨设备跟踪
Pushwoosh.Instance.SetUserId("user-123");

// 设置用户邮箱
Pushwoosh.Instance.SetEmail("user@example.com");

// 同时设置用户 ID 和邮箱
Pushwoosh.Instance.SetUser("user-123", new List<string> { "user@example.com" });

// 设置首选语言
Pushwoosh.Instance.SetLanguage("en");

标签 (Tags)

标签是分配给设备的键值对，可用于用户分群和定向消息发送：

// 字符串标签
Pushwoosh.Instance.SetStringTag("favorite_category", "electronics");

// 整数标签
Pushwoosh.Instance.SetIntTag("purchase_count", 5);

// 列表标签
Pushwoosh.Instance.SetListTag("interests", new List<object> { "sports", "music", "tech" });

// 获取所有标签
Pushwoosh.Instance.GetTags((tags, error) => {
    if (error != null) {
        Debug.Log("Error: " + error.Message);
        return;
    }
    foreach (var tag in tags) {
        Debug.Log(tag.Key + ": " + tag.Value);
    }
});

事件 (Events)

跟踪用户行为以分析行为并触发自动化消息：

// 跟踪登录事件
Pushwoosh.Instance.PostEvent("login", new Dictionary<string, object> {
    { "username", "user-123" },
    { "login_type", "email" }
});

// 跟踪购买事件
Pushwoosh.Instance.PostEvent("purchase", new Dictionary<string, object> {
    { "product_id", "SKU-001" },
    { "price", 29.99 },
    { "currency", "USD" }
});

通信偏好设置

允许用户通过编程方式选择接收或退订推送通知：

// 启用通信
Pushwoosh.Instance.SetCommunicationEnabled(true);

// 禁用通信
Pushwoosh.Instance.SetCommunicationEnabled(false);

// 检查当前状态
bool isEnabled = Pushwoosh.Instance.IsCommunicationEnabled();

应用角标管理

在支持的平台上控制应用程序角标数量：

// 将角标设置为特定数字
Pushwoosh.Instance.SetBadgeNumber(3);

// 增加角标数量
Pushwoosh.Instance.AddBadgeNumber(1);

// 清除角标
Pushwoosh.Instance.SetBadgeNumber(0);

故障排除

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