阿里云移动推送+Unity框架最佳实践

1.1 创建应用

1. 登录阿里云移动推送控制台。

2. 创建项目和应用并获取appKey与appSecret。具体操作请参见快速入门。

1.2 配置应用

1. Android应用参考配置厂商通道密钥在移动推送控制台配置厂商密钥信息。

2. iOS应用参考APNs鉴权配置在移动推送控制台配置P8或P12证书。

2.1 导入插件

方式一：使用unitypackage

1. 下载SDK

   • 从下载页面下载alicloud-push.unitypackage

2. 导入到Unity项目

   • 双击下载的alicloud-push.unitypackage，或在Unity中选择Assets -> Import Package -> Custom Package...，然后选择下载的文件

   • 在弹出的对话框中点击"Import"

3. 验证安装

   • 导入成功后，在Project窗口中应该能看到Assets/Plugins/目录

   • 包含PushHelper.cs等文件

方式二：手动集成

如果您不使用unitypackage，也可以手动将开源仓库中Assets/Plugins目录复制到您的Unity项目中。

2.2 Unity Android构建设置

为了确保Android平台的推送功能正常工作，需要在Unity中启用自定义Android配置：

1. 启用自定义Android配置

   • 打开File -> Build Profiles -> Android -> Player Settings

   • 在Publishing Settings部分，勾选以下五个选项：

     • Custom Main Manifest：启用自定义主清单文件

     • Custom Main Gradle Template：启用自定义主Gradle模板

     • Custom Base Gradle Template：启用自定义Base Gradle模板

     • Custom Gradle Settings Template：启用自定义Settings Gradle 模板

     • Custom Proguard File：启用自定义Proguard文件

2. 文件合并注意事项

   • 如果您的项目已经有自定义的Android XML或Gradle文件，请注意将现有配置与Assets/Plugins/Android/目录下的插件文件进行合并

   • 特别注意AndroidManifest.xml中的权限声明和组件配置不要冲突

   • Gradle文件中的依赖项需要合并，避免版本冲突

2.3 iOS CocoaPods依赖管理

iOS平台使用CocoaPods管理依赖，需要注意以下配置：

1. 自动Podfile生成

   • 当前Pod文件的生成依赖于脚本Assets/Plugins/Editor/iOSAliyunPushPostProcessor.cs

   • 该脚本会在构建iOS项目时自动生成Podfile文件

2. Pod依赖合并

   • 如果您的项目依赖其他的Pod库，需要将现有的Pod配置与iOSAliyunPushPostProcessor.cs脚本生成的配置进行合并

   • 建议在iOSAliyunPushPostProcessor.cs脚本中添加您的其他Pod依赖，或者修改脚本以兼容现有的Podfile配置

   • 确保Pod版本兼容性，避免依赖冲突

2.4 配置应用包名

确保您的应用包名（Android）或Bundle ID（iOS）与推送控制台中创建的应用一致。

3.1 配置AndroidManifest.xml

在Assets/Plugins/Android/AndroidManifest.xml文件中配置AppKey、AppSecret以及厂商通道密钥

<application>
    <!-- 请填写阿里云的- appKey appSecret -->
    <meta-data android:name="com.alibaba.app.appkey" android:value="您的AppKey" />
    <meta-data android:name="com.alibaba.app.appsecret" android:value="您的AppSecret" />

    <!-- 华为通道的参数appid -->
    <meta-data android:name="com.huawei.hms.client.appid" android:value="appid=您的华为AppId" />

    <!-- 荣耀通道的参数-->
    <meta-data android:name="com.hihonor.push.app_id" android:value="您的荣耀AppId" />

    <!-- 小米通道的参数 -->
    <meta-data android:name="com.aliyun.ams.push.xiaomi.id" android:value="您的小米AppId" />
    <meta-data android:name="com.aliyun.ams.push.xiaomi.key" android:value="您的小米AppKey" />

    <!-- oppo通道的参数 -->
    <meta-data android:name="com.aliyun.ams.push.oppo.key" android:value="您的OPPO AppKey" />
    <meta-data android:name="com.aliyun.ams.push.oppo.secret" android:value="您的OPPO AppSecret" />

    <!-- vivo通道的参数api_key为appkey -->
    <meta-data android:name="com.vivo.push.api_key" android:value="您的vivo AppKey" />
    <meta-data android:name="com.vivo.push.app_id" android:value="您的vivo AppId" />

    <!-- 魅族通道的参数 -->
    <meta-data android:name="com.aliyun.ams.push.meizu.id" android:value="您的魅族AppId" />
    <meta-data android:name="com.aliyun.ams.push.meizu.secret" android:value="您的魅族AppKey" />

    <!-- fcm通道的参数 -->
    <meta-data android:name="com.aliyun.ams.push.gcm.sendid" android:value="您的fcm project_number" />
    <meta-data android:name="com.aliyun.ams.push.gcm.applicationid" android:value="您的fcm mobilesdk_app_id" />
    <meta-data android:name="com.aliyun.ams.push.gcm.projectid" android:value="您的fcm project_id"/>
    <meta-data android:name="com.aliyun.ams.push.gcm.apiKey" android:value="您的fcm current_key"/>
</application>

3.2 创建通知渠道

Android 8.0及以上版本需要创建通知渠道：

PushHelper.CreateNotificationChannel(
    id: "default_channel",
    name: "默认通知",
    importance: PushHelper.IMPORTANCE_DEFAULT,
    desc: "应用默认通知渠道",
    showBadge: true,
    enableLights: true,
    lightColor: unchecked((int)0xFF0000FF),  // 蓝色
    enableVibration: true,
    vibrationPattern: "0,250,250,250"
);

服务端推送时需要设置AndroidNotificationChannel参数（PushV2中为ChannelId参数）与这里客户端创建的channel的id相同。

3.3 配置Android消息接收回调（可选）

如果您希望设置Android消息接收回调，那么需要在调用InitPush之前设置，例如：

#if UNITY_ANDROID
PushHelper.SetAndroidMessageReceiver(
    onMessage: (title, body) => {
        Debug.Log("onMessage - title: " + title + ", body: " + body);
    },
    onNotification: (title, body, extraMap) => {
        string extras = extraMap != null ? string.Join(", ", extraMap) : "";
        Debug.Log("onNotification - title: " + title + ", body: " + body + ", extraMap: " + extras);
    },
    onNotificationOpened: (title, body, extraMapString) => {
        Debug.Log("onNotificationOpened - title: " + title + ", body: " + body + ", extraMapString: " + extraMapString);
    },
    onNotificationRemoved: (messageId) => {
        Debug.Log("onNotificationRemoved - messageId: " + messageId);
    },
    onSysNoticeOpened: (title, body, extraMap) => {
        string extras = extraMap != null ? string.Join(", ", extraMap) : "";
        Debug.Log("onSysNoticeOpened - title: " + title + ", body: " + body + ", extraMap: " + extras);
    }
);
#endif

4.1 前台通知处理模式设置（可选）

iOS应用可以设置前台通知处理模式，选择是否弹出通知以及是否调用回调

#if UNITY_IOS
// 展示通知且调用回调
PushHelper.SetIOSForegroundNotificationMode(PushHelper.IOS_FOREGROUND_SHOW_AND_CALLBACK);
#endif

4.2 配置iOS消息接收回调（可选）

如果您希望设置Android消息接收回调，那么需要在调用InitPush之前设置，例如：

#if UNITY_IOS
PushHelper.SetIOSMessageReceiver(
    onMessageReceived: (title, body) => {
        Debug.Log("onMessageReceived - title: " + title + ", body: " + body);
    },
    onAPNSRegisterSuccess: (deviceToken) => {
        Debug.Log("onAPNSRegisterSuccess - deviceToken: " + deviceToken);
    },
    onAPNSRegisterFailed: (error) => {
        Debug.Log("onAPNSRegisterFailed - error: " + error);
    },
    onForegroundNotificationReceived: (title, body, subtitle, userInfo) => {
        Debug.Log("onForegroundNotificationReceived - title: " + title + ", body: " + body + ", subtitle: " + subtitle + ", userInfo: " + userInfo);
    },
    onNotificationOpened: (title, body, subtitle, userInfo) => {
        Debug.Log("onNotificationOpened - title: " + title + ", body: " + body + ", subtitle: " + subtitle + ", userInfo: " + userInfo);
    },
    onNotificationRemoved: (userInfo) => {
        Debug.Log("onNotificationRemoved - userInfo: " + userInfo);
    },
    onRemoteNotificationReceived: (title, body, subtitle, userInfo) => {
        Debug.Log("onRemoteNotificationReceived - title: " + title + ", body: " + body + ", subtitle: " + subtitle + ", userInfo: " + userInfo);
    }
);
#endif

6.1 安装pod依赖

Assets/Plugins/Editor/iOSAliyunPushPostProcessor.cs脚本会自动生成Podfile文件，您需要在build出iOS xcode项目后，进入项目根目录执行以下命令：

pod repo update AliyunRepo
pod install

# 如果您尚未添加阿里云Cocoapods仓库，请先执行以下命令添加仓库
# pod repo add AliyunRepo https://github.com/aliyun/aliyun-specs.git

6.2 配置APNs推送能力

在打开xcode工程后，您需要按照以下方式配置工程：

1. Target → Signing & Capabilities → 添加 Push Notifications 和 Background Modes 两个Capability

2. Background Modes → 勾选Remote notifications

详情请参考2.3 配置APNs推送能力

1.1 SetLogLevel - 设置日志级别

设置SDK的日志输出级别，用于调试和问题排查。

方法签名：

public static void SetLogLevel(string logLevel)

参数说明：

• logLevel：日志级别，可选值：

  • PushHelper.LOG_OFF：关闭日志

  • PushHelper.LOG_ERROR：仅错误日志

  • PushHelper.LOG_WARN：警告及以上

  • PushHelper.LOG_INFO：信息及以上

  • PushHelper.LOG_DEBUG：所有日志（调试用）

平台支持： iOS & Android

使用示例：

// 开发环境使用DEBUG级别
#if UNITY_EDITOR || DEVELOPMENT_BUILD
    PushHelper.SetLogLevel(PushHelper.LOG_DEBUG);
#else
    // 生产环境关闭日志或仅显示错误
    PushHelper.SetLogLevel(PushHelper.LOG_ERROR);
#endif

注意事项：

• 生产环境应关闭或降低日志级别，避免性能影响和信息泄露

1.2 SetAndroidMessageReceiver - 设置Android消息接收回调

统一设置Android平台的所有消息和通知回调。必须在InitPush之前调用。

方法签名：

public static void SetAndroidMessageReceiver(
    Action<string, string> onMessage = null,
    Action<string, string, Dictionary<string, string>> onNotification = null,
    Action<string, string, string> onNotificationOpened = null,
    Action<string, string, string> onNotificationClickedWithNoAction = null,
    Action<string> onNotificationRemoved = null,
    Action<string, string, Dictionary<string, string>, int, string, string> onNotificationReceivedInApp = null,
    Action<string, string, Dictionary<string, string>> onSysNoticeOpened = null
)

参数说明：

• onMessage：透传消息到达回调

  • 触发时机：当收到阿里云自有通道的透传消息时

  • 参数1 (string title)：消息标题

  • 参数2 (string body)：消息内容

  • 说明：透传消息不会在通知栏显示，需要开发者自行处理UI展示

• onNotification：通知到达回调

  • 触发时机：当收到阿里云自有通道的通知消息时

  • 参数1 (string title)：通知标题

  • 参数2 (string body)：通知内容

  • 参数3 (Dictionary<string, string> extraMap)：通知扩展字段字典

  • 说明：此回调用于记录或处理通知到达事件

• onNotificationOpened：通知点击回调

  • 触发时机：用户点击阿里云自有通道或fcm通道的通知时

  • 参数1 (string title)：通知标题

  • 参数2 (string body)：通知内容

  • 参数3 (string extraMapString)：通知扩展字段JSON字符串

  • 说明：用于处理用户点击通知后的跳转逻辑，如打开特定页面

• onNotificationClickedWithNoAction：通知点击无动作回调

  • 触发时机：用户点击阿里云自有通道的通知时触发。需要推送时设置AndroidOpenType参数（PushV2为Accs下的OpenType参数）为NONE

  • 参数1 (string title)：通知标题

  • 参数2 (string body)：通知内容

  • 参数3 (string extraMapString)：通知扩展字段JSON字符串

  • 说明：当推送配置为点击无动作时触发，开发者可自定义处理逻辑

• onNotificationRemoved：通知移除回调

  • 触发时机：用户手动清除阿里云自有通道的通知时

  • 参数1 (string messageId)：消息唯一标识ID

  • 说明：用于统计通知的清除情况

• onNotificationReceivedInApp：应用内通知接收回调

  • 触发时机：应用收到阿里云自有通道的通知，且主动在Assets/Plugins/Android/alicloud-push/PushMessageReceiver.java中覆写了showNotificationNow方法返回false，此时不会展示通知

  • 参数1 (string title)：通知标题

  • 参数2 (string body)：通知内容

  • 参数3 (Dictionary<string, string> extraMap)：通知扩展字段字典

  • 参数4 (int openType)：打开类型（1=Activity, 2=URL, 3=无动作）

  • 参数5 (string openActivity)：要打开的Activity名称

  • 参数6 (string openUrl)：要打开的URL地址

  • 说明：用于自定义应用内通知展示，需要配合拦截通知使用

• onSysNoticeOpened：厂商通道（fcm除外）的通知点击回调

  • 触发时机：用户点击厂商通道（小米、华为、OPPO等）推送的通知时触发。需要推送时设置AndroidPopupActivity参数（PushV2为VendorChannelActivity参数）为com.alibaba.sdk.android.pushwrapper.ThirdPushActivity

  • 参数1 (string title)：通知标题

  • 参数2 (string body)：通知内容

  • 参数3 (Dictionary<string, string> extraMap)：通知扩展字段字典

  • 说明：处理厂商通道通知的点击事件

平台支持： 仅Android

使用示例：

#if UNITY_ANDROID
PushHelper.SetAndroidMessageReceiver(
    onMessage: (title, body) => {
        Debug.Log("onMessage - title: " + title + ", body: " + body);
    },
    onNotification: (title, body, extraMap) => {
        string extras = extraMap != null ? string.Join(", ", extraMap) : "";
        Debug.Log("onNotification - title: " + title + ", body: " + body + ", extraMap: " + extras);
    },
    onNotificationOpened: (title, body, extraMapString) => {
        Debug.Log("onNotificationOpened - title: " + title + ", body: " + body + ", extraMapString: " + extraMapString);
    },
    onNotificationClickedWithNoAction: (title, body, extraMapString) => {
        Debug.Log("onNotificationClickedWithNoAction - title: " + title + ", body: " + body);
    },
    onNotificationRemoved: (messageId) => {
        Debug.Log("onNotificationRemoved - messageId: " + messageId);
    },
    onNotificationReceivedInApp: (title, body, extraMap, openType, openActivity, openUrl) => {
        Debug.Log("onNotificationReceivedInApp - title: " + title + ", openType: " + openType);
    },
    onSysNoticeOpened: (title, body, extraMap) => {
        string extras = extraMap != null ? string.Join(", ", extraMap) : "";
        Debug.Log("onSysNoticeOpened - title: " + title + ", body: " + body + ", extraMap: " + extras);
    }
);
#endif

注意事项：

• 必须在InitPush之前设置回调

• 所有回调参数都是可选的，只需设置需要的回调

1.3 SetIOSMessageReceiver - 设置iOS消息接收回调

统一设置iOS平台的所有消息和通知回调。必须在InitPush之前调用。

方法签名：

public static void SetIOSMessageReceiver(
    Action<string, string> onMessageReceived = null,
    Action<string> onAPNSRegisterSuccess = null,
    Action<string> onAPNSRegisterFailed = null,
    Action<string, string, string, string> onForegroundNotificationReceived = null,
    Action<string, string, string, string> onNotificationOpened = null,
    Action<string> onNotificationRemoved = null,
    Action<string, string, string, string> onRemoteNotificationReceived = null
)

参数说明：

• onMessageReceived：阿里云自有通道消息接收回调

  • 触发时机：当收到阿里云自有通道的透传消息时

  • 参数1 (string title)：消息标题

  • 参数2 (string body)：消息内容

  • 说明：透传消息不会在通知中心显示，需要开发者自行处理UI展示

• onAPNSRegisterSuccess：APNS注册成功回调

  • 触发时机：设备成功向苹果APNS服务器注册并获取到DeviceToken时

  • 参数1 (string deviceToken)：苹果推送服务分配的设备令牌

  • 说明：DeviceToken用于服务端直接推送

• onAPNSRegisterFailed：APNS注册失败回调

  • 触发时机：设备向苹果APNS服务器注册失败时

  • 参数1 (string error)：注册失败的错误信息

  • 说明：用于排查APNS注册问题，常见原因包括网络问题、证书配置错误等

• onForegroundNotificationReceived：前台通知接收回调

  • 触发时机：应用在前台时收到APNs通知

  • 参数1 (string title)：通知标题

  • 参数2 (string body)：通知内容

  • 参数3 (string subtitle)：通知副标题（iOS 10+支持）

  • 参数4 (string userInfo)：通知用户信息JSON字符串，包含自定义字段

  • 说明：iOS应用在前台时默认不显示通知，可通过此回调自定义处理

• onNotificationOpened：通知点击回调

  • 触发时机：用户点击通知中心的推送通知时

  • 参数1 (string title)：通知标题

  • 参数2 (string body)：通知内容

  • 参数3 (string subtitle)：通知副标题

  • 参数4 (string userInfo)：通知用户信息JSON字符串

  • 说明：用于处理用户点击通知后的跳转逻辑，应用会被唤醒或切换到前台

• onNotificationRemoved：通知移除回调

  • 触发时机：用户手动清除通知中心的通知时触发。需要推送时设置iOSNotificationCategory参数（PushV2中为Ios下的Category参数）为aliyun_push_category。如果您希望自定义category名称，请同步修改Assets/Plugins/iOS/alicloud-push/PushWrapper.m文件中createCustomNotificationCategory方法里的category名称

  • 参数1 (string userInfo)：通知用户信息JSON字符串

  • 说明：用于统计通知的清除情况，iOS 10+支持

• onRemoteNotificationReceived：静默通知接收回调

  • 触发时机：应用收到静默推送时触发。需要推送时设置iOSSilentNotification参数（PushV2中为Ios下的Silent参数）为true

  • 参数1 (string title)：通知标题（静默推送可能为空）

  • 参数2 (string body)：通知内容（静默推送可能为空）

  • 参数3 (string subtitle)：通知副标题（静默推送可能为空）

  • 参数4 (string userInfo)：通知用户信息JSON字符串

  • 说明：用于处理静默推送，如数据同步、内容预加载等，不会显示通知

平台支持： 仅iOS

使用示例：

#if UNITY_IOS
PushHelper.SetIOSMessageReceiver(
    onMessageReceived: (title, body) => {
        Debug.Log("onMessageReceived - title: " + title + ", body: " + body);
    },
    onAPNSRegisterSuccess: (deviceToken) => {
        Debug.Log("onAPNSRegisterSuccess - deviceToken: " + deviceToken);
    },
    onAPNSRegisterFailed: (error) => {
        Debug.Log("onAPNSRegisterFailed - error: " + error);
    },
    onForegroundNotificationReceived: (title, body, subtitle, userInfo) => {
        Debug.Log("onForegroundNotificationReceived - title: " + title + ", body: " + body + ", subtitle: " + subtitle + ", userInfo: " + userInfo);
    },
    onNotificationOpened: (title, body, subtitle, userInfo) => {
        Debug.Log("onNotificationOpened - title: " + title + ", body: " + body + ", subtitle: " + subtitle + ", userInfo: " + userInfo);
    },
    onNotificationRemoved: (userInfo) => {
        Debug.Log("onNotificationRemoved - userInfo: " + userInfo);
    },
    onRemoteNotificationReceived: (title, body, subtitle, userInfo) => {
        Debug.Log("onRemoteNotificationReceived - title: " + title + ", body: " + body + ", subtitle: " + subtitle + ", userInfo: " + userInfo);
    }
);
#endif

注意事项：

• 必须在InitPush之前设置回调

• 所有回调参数都是可选的，只需设置需要的回调

1.4 SetIOSForegroundNotificationMode - 设置iOS前台通知处理模式

设置iOS应用在前台时收到通知的处理方式。

方法签名：

public static void SetIOSForegroundNotificationMode(string mode)

参数说明：

• mode：处理模式，可选值：

  • PushHelper.IOS_FOREGROUND_SHOW_AND_CALLBACK：展示通知且调用回调

  • PushHelper.IOS_FOREGROUND_SHOW_ONLY：只展示通知，不调用回调

  • PushHelper.IOS_FOREGROUND_CALLBACK_ONLY：只调用回调，不展示通知

平台支持： 仅iOS

使用示例：

#if UNITY_IOS
PushHelper.SetIOSForegroundNotificationMode(PushHelper.IOS_FOREGROUND_SHOW_AND_CALLBACK);
#endif

2.1 InitPush - 初始化推送服务

初始化推送SDK，这是使用推送服务的核心步骤。

方法签名：

public static void InitPush(string appKey, string appSecret, Action<bool, string> callback)

参数说明：

• appKey：应用的AppKey，从阿里云推送控制台获取

• appSecret：应用的AppSecret，从阿里云推送控制台获取

• callback：初始化结果回调

  • bool：是否成功

  • string：失败时返回错误信息

平台支持： iOS & Android

使用示例：

PushHelper.InitPush("您的AppKey", "您的AppSecret", (success, message) => {
    if (success) {
        Debug.Log("推送初始化成功: " + message);
    } else {
        Debug.LogError("推送初始化失败: " + message);
    }
});

注意事项：

• Android的AppKey和AppSecret也需要在AndroidManifest.xml中配置

• 建议在应用启动时尽早调用此方法

• 初始化成功后才能使用其他推送功能

2.2 InitAndroidThirdPush - 初始化Android厂商通道

初始化Android第三方推送通道（小米、华为、OPPO、vivo、魅族等），提高离线推送到达率。

方法签名：

public static void InitAndroidThirdPush()

平台支持： 仅Android

使用示例：

#if UNITY_ANDROID
PushHelper.InitAndroidThirdPush();
#endif

注意事项：

• 需要在AndroidManifest.xml中配置对应厂商的参数

• 仅在对应品牌的设备上生效

• 建议在InitPush成功后调用

3.1 BindAccount - 绑定账号

将设备与业务账号绑定，绑定后可以通过账号进行推送。

方法签名：

public static void BindAccount(string account, Action<bool, string> callback)

参数说明：

• account：业务账号，如用户ID

• callback：绑定结果回调

平台支持： iOS & Android

使用示例：

PushHelper.BindAccount("user123", (success, message) => {
    if (success) {
        Debug.Log("账号绑定成功");
    } else {
        Debug.LogError("账号绑定失败: " + message);
    }
});

注意事项：

• 一个设备只能绑定一个账号，重复绑定会覆盖

• 账号推送可以实现精准推送到特定用户

3.2 UnbindAccount - 解绑账号

解除设备与业务账号的绑定关系。

方法签名：

public static void UnbindAccount(Action<bool, string> callback)

参数说明：

• callback：解绑结果回调

平台支持： iOS & Android

使用示例：

PushHelper.UnbindAccount((success, message) => {
    if (success) {
        Debug.Log("账号解绑成功");
    } else {
        Debug.LogError("账号解绑失败: " + message);
    }
});

4.1 BindTag - 绑定标签

给指定目标绑定标签。

方法签名：

public static void BindTag(int target, string tag, string alias, Action<bool, string> callback)

参数说明：

• target：目标类型

  • 1：设备（CloudPushService.DEVICE_TARGET）

  • 2：账号（CloudPushService.ACCOUNT_TARGET）

  • 3：别名（CloudPushService.ALIAS_TARGET）

• tag：标签名称

• alias：别名（仅当target=3时需要）

• callback：绑定结果回调

平台支持： iOS & Android

使用示例：

// 给设备绑定标签
PushHelper.BindTag(1, "VIP用户", null, (success, message) => {
    if (success) {
        Debug.Log("设备标签绑定成功");
    } else {
        Debug.LogError("标签绑定失败: " + message);
    }
});

注意事项：

• 一个目标可以绑定多个标签

• 标签名称建议使用有意义的分类名称

4.2 UnbindTag - 解绑标签

解除指定目标的标签绑定。

方法签名：

public static void UnbindTag(int target, string tag, string alias, Action<bool, string> callback)

参数说明：

• target：目标类型（1=设备, 2=账号, 3=别名）

• tag：标签名称

• alias：别名（仅当target=3时需要）

• callback：解绑结果回调

平台支持： iOS & Android

使用示例：

// 解绑设备标签
PushHelper.UnbindTag(1, "VIP用户", null, (success, message) => {
    if (success) {
        Debug.Log("标签解绑成功");
    } else {
        Debug.LogError("标签解绑失败: " + message);
    }
});

注意事项：

• 只能解绑已存在的标签

4.3 ListTags - 查询标签列表

查询指定目标绑定的所有标签。

方法签名：

public static void ListTags(int target, Action<bool, string> callback)

参数说明：

• target：目标类型（1=设备）

• callback：查询结果回调，成功时返回标签列表

平台支持： iOS & Android

使用示例：

// 查询设备的所有标签
PushHelper.ListTags(1, (success, tags) => {
    if (success) {
        Debug.Log("标签列表: " + tags);
    } else {
        Debug.LogError("查询失败: " + tagsJson);
    }
});

5.1 AddAlias - 添加别名

给设备添加别名。

方法签名：

public static void AddAlias(string alias, Action<bool, string> callback)

参数说明：

• alias：别名名称

• callback：添加结果回调

平台支持： iOS & Android

使用示例：

PushHelper.AddAlias("player_001", (success, message) => {
    if (success) {
        Debug.Log("别名添加成功");
    } else {
        Debug.LogError("别名添加失败: " + message);
    }
});

注意事项：

• 一个设备可以有多个别名

• 别名可以用于更灵活的推送场景

• 别名名称建议使用有意义的标识

5.2 RemoveAlias - 移除别名

移除设备的指定别名。

方法签名：

public static void RemoveAlias(string alias, Action<bool, string> callback)

参数说明：

• alias：别名名称

• callback：移除结果回调

平台支持： iOS & Android

使用示例：

// 移除别名
PushHelper.RemoveAlias("player_001", (success, message) => {
    if (success) {
        Debug.Log("别名移除成功");
    } else {
        Debug.LogError("别名移除失败: " + message);
    }
});

注意事项：

• 只能移除已存在的别名

• 移除后将无法通过该别名推送到设备

5.3 ListAliases - 查询别名列表

查询设备的所有别名。

方法签名：

public static void ListAliases(Action<bool, string> callback)

参数说明：

• callback：查询结果回调，成功时返回别名列表

平台支持： iOS & Android

使用示例：

// 查询设备的所有别名
PushHelper.ListAliases((success, aliases) => {
    if (success) {
        Debug.Log("别名列表: " + aliases);
    } else {
        Debug.LogError("查询失败: " + aliasesJson);
    }
});

6.1 BindPhoneNumber - 绑定手机号

给设备绑定手机号。

方法签名：

public static void BindPhoneNumber(string phone, Action<bool, string> callback)

参数说明：

• phone：手机号码

• callback：绑定结果回调

平台支持： 仅Android

使用示例：

#if UNITY_ANDROID
PushHelper.BindPhoneNumber("13800138000", (success, message) => {
    if (success) {
        Debug.Log("手机号绑定成功");
    } else {
        Debug.LogError("手机号绑定失败: " + message);
    }
});
#endif

注意事项：

• 仅Android平台支持

• 用于推送短信融合方案

• 一个设备只能绑定一个手机号

6.2 UnbindPhoneNumber - 解绑手机号

解除设备与手机号的绑定。

方法签名：

public static void UnbindPhoneNumber(Action<bool, string> callback)

参数说明：

• callback：解绑结果回调

平台支持： 仅Android

使用示例：

#if UNITY_ANDROID
// 解绑手机号
PushHelper.UnbindPhoneNumber((success, message) => {
    if (success) {
        Debug.Log("手机号解绑成功");
    } else {
        Debug.LogError("手机号解绑失败: " + message);
    }
});
#endif

注意事项：

• 解绑后将无法使用推送短信融合功能

7.1 GetDeviceId - 获取设备ID

获取推送服务分配的设备唯一标识符。

方法签名：

public static string GetDeviceId()

返回值：

• 设备ID字符串

平台支持： iOS & Android

使用示例：

string deviceId = PushHelper.GetDeviceId();
Debug.Log("设备ID: " + deviceId);

注意事项：

• 需要在InitPush成功后调用

• 设备ID是推送服务的唯一标识

• 可用于服务端API进行设备推送

8.1 IsNotificationEnabled - 检查通知权限

检查用户是否允许应用显示通知。

方法签名：

public static bool IsNotificationEnabled()

返回值：

• true：通知权限已开启

• false：通知权限未开启

平台支持： 仅Android

使用示例：

#if UNITY_ANDROID
bool isEnabled = PushHelper.IsNotificationEnabled();
Debug.Log("通知权限状态: " + isEnabled);
#endif

注意事项：

• 建议在应用启动时检查通知权限

• 如果权限未开启，引导用户去设置

8.2 IsNotificationChannelEnabled - 检查通知渠道权限

检查指定通知渠道是否已开启（Android 8.0+）。

方法签名：

public static bool IsNotificationChannelEnabled(string channelId)

参数说明：

• channelId：通知渠道ID

返回值：

• true：通知渠道已开启

• false：通知渠道未开启

平台支持： 仅Android

使用示例：

#if UNITY_ANDROID
bool isEnabled = PushHelper.IsNotificationChannelEnabled("default_channel");
Debug.Log("通知渠道状态: " + isEnabled);
#endif

注意事项：

• 仅Android 8.0及以上版本有效

• 需要先创建通知渠道

8.3 JumpToNotificationSetting - 跳转通知设置

跳转到应用的通知设置页面。

方法签名：

public static void JumpToNotificationSetting()

平台支持： 仅Android

使用示例：

#if UNITY_ANDROID
PushHelper.JumpToNotificationSetting();
#endif

注意事项：

• 会打开系统设置页面，用户需要手动开启

• 建议在检测到权限未开启时引导用户

8.4 JumpToNotificationChannelSetting - 跳转通知渠道设置

跳转到指定通知渠道的设置页面。

方法签名：

public static void JumpToNotificationChannelSetting(string channelId)

参数说明：

• channelId：通知渠道ID

平台支持： 仅Android

使用示例：

#if UNITY_ANDROID
PushHelper.JumpToNotificationChannelSetting("default_channel");
#endif

注意事项：

• 仅Android 8.0及以上版本有效

• 部分设备可能不支持，会跳转到通知设置页面

8.5 CreateNotificationChannel - 创建通知渠道

创建Android通知渠道（Android 8.0+必需）。

方法签名：

public static void CreateNotificationChannel(
    string id,
    string name,
    int importance = 3,
    string desc = "",
    bool showBadge = true,
    bool enableLights = true,
    int lightColor = 0,
    bool enableVibration = true,
    string vibrationPattern = ""
)

参数说明：

• id：渠道ID（唯一标识）

• name：渠道名称（用户可见）

• importance：重要性级别（0-5）

  • PushHelper.IMPORTANCE_NONE (0)：不显示通知

  • PushHelper.IMPORTANCE_MIN (1)：最低级别，不发出声音

  • PushHelper.IMPORTANCE_LOW (2)：低级别，不发出声音

  • PushHelper.IMPORTANCE_DEFAULT (3)：默认级别，发出声音

  • PushHelper.IMPORTANCE_HIGH (4)：高级别，发出声音并弹出

  • PushHelper.IMPORTANCE_MAX (5)：最高级别

• desc：渠道描述

• showBadge：是否显示角标

• enableLights：是否启用指示灯

• lightColor：指示灯颜色（ARGB格式）

• enableVibration：是否启用震动

• vibrationPattern：震动模式（逗号分隔的毫秒数）

平台支持： 仅Android

使用示例：

#if UNITY_ANDROID
PushHelper.CreateNotificationChannel(
    id: "default_channel",
    name: "默认通知",
    importance: PushHelper.IMPORTANCE_DEFAULT,
    desc: "应用默认通知渠道",
    showBadge: true,
    enableLights: true,
    lightColor: unchecked((int)0xFF0000FF),  // 蓝色
    enableVibration: true,
    vibrationPattern: "0,250,250,250"
);
#endif

注意事项：

• Android 8.0及以上版本必须创建通知渠道

• 建议在应用启动时创建

• 渠道创建后，用户可以在系统设置中管理

• lightColor使用ARGB格式，注意使用unchecked避免溢出