Alibaba Cloud Mobile Push + Unity framework best practices

1.1 Create an application

1. Log on to the Alibaba Cloud Mobile Push console.

2. Create a project and an application to obtain the AppKey and AppSecret. For more information, see Quick Start.

1.2 Configure the application

1. For Android applications, configure the keys in the Mobile Push console. For more information, see Configure third-party channel keys.

2. For iOS applications, configure a P8 or P12 certificate in the Mobile Push console. For more information, see Configure APNs authentication.

2.1 Import the plugin

Method 1: Use a unitypackage

1. Download the SDK

   • Download alicloud-push.unitypackage from the download page.

2. Import into your Unity project

   • Double-click the downloaded alicloud-push.unitypackage file. Alternatively, in the Unity Editor, select Assets > Import Package > Custom Package... and choose the downloaded file.

   • In the dialog box that appears, click Import.

3. Verify the installation

   • After the import is successful, the Assets/Plugins/ directory appears in the Project window.

   • This directory contains files such as PushHelper.cs.

Method 2: Manual integration

Alternatively, you can copy the Assets/Plugins directory from the open source repository to your Unity project.

2.2 Configure Android build settings for Unity

To ensure that push notifications work correctly on Android, you must enable custom Android configurations in Unity.

1. Enable custom Android configurations

   • Go to File -> Build Profiles -> Android -> Player Settings.

   • In the Publishing Settings section, select the following five options:

     • Custom Main Manifest: Enables a custom main manifest file.

     • Custom Main Gradle Template: Enables a custom main Gradle template.

     • Custom Base Gradle Template: Enables a custom base Gradle template.

     • Custom Gradle Settings Template: Enables a custom settings Gradle template.

     • Custom Proguard File: Enables a custom Proguard file.

2. Notes on merging files

   • If your project already has custom Android XML or Gradle files, merge your existing configurations with the plugin files in the Assets/Plugins/Android/ directory.

   • Ensure that the permission declarations and component configurations in AndroidManifest.xml do not conflict.

   • Merge the dependencies in the Gradle files to avoid version conflicts.

2.3 Manage iOS dependencies with CocoaPods

The iOS platform uses CocoaPods to manage dependencies. Take note of the following configurations:

1. Automatic Podfile generation

   • The Podfile is currently generated by the Assets/Plugins/Editor/iOSAliyunPushPostProcessor.cs script.

   • This script automatically generates a Podfile when you build the iOS project.

2. Pod dependency merging

   • If your project depends on other Pod libraries, merge your existing Pod configuration with the configuration generated by the iOSAliyunPushPostProcessor.cs script.

   • You can add your other Pod dependencies to the iOSAliyunPushPostProcessor.cs script, or modify the script to be compatible with your existing Podfile configuration.

   • Ensure Pod version compatibility to prevent dependency conflicts.

2.4 Configure the application package name

Ensure that your application package name (for Android) or Bundle ID (for iOS) matches the one for the application that you created in the Mobile Push console.

3.1 Configure AndroidManifest.xml

In the Assets/Plugins/Android/AndroidManifest.xml file, configure the AppKey, AppSecret, and third-party channel keys.

<application>
    <!-- Enter the AppKey and AppSecret from Alibaba Cloud -->
    <meta-data android:name="com.alibaba.app.appkey" android:value="Your_AppKey" />
    <meta-data android:name="com.alibaba.app.appsecret" android:value="Your_AppSecret" />

    <!-- Parameters for the Huawei channel -->
    <meta-data android:name="com.huawei.hms.client.appid" android:value="appid=Your_Huawei_AppId" />

    <!-- Parameters for the Honor channel -->
    <meta-data android:name="com.hihonor.push.app_id" android:value="Your_Honor_AppId" />

    <!-- Parameters for the Xiaomi channel -->
    <meta-data android:name="com.aliyun.ams.push.xiaomi.id" android:value="id=Your_Xiaomi_AppId" />
    <meta-data android:name="com.aliyun.ams.push.xiaomi.key" android:value="id=Your_Xiaomi_AppKey" />

    <!-- Parameters for the OPPO channel -->
    <meta-data android:name="com.aliyun.ams.push.oppo.key" android:value="id=Your_OPPO_AppKey" />
    <meta-data android:name="com.aliyun.ams.push.oppo.secret" android:value="id=Your_OPPO_AppSecret" />

    <!-- Parameters for the vivo channel. api_key is the AppKey. -->
    <meta-data android:name="com.vivo.push.api_key" android:value="Your_vivo_AppKey" />
    <meta-data android:name="com.vivo.push.app_id" android:value="Your_vivo_AppId" />

    <!-- Parameters for the Meizu channel -->
    <meta-data android:name="com.aliyun.ams.push.meizu.id" android:value="id=Your_Meizu_AppId" />
    <meta-data android:name="com.aliyun.ams.push.meizu.secret" android:value="id=Your_Meizu_AppKey" />

    <!-- Parameters for the FCM channel -->
    <meta-data android:name="com.aliyun.ams.push.gcm.sendid" android:value="id=Your_FCM_project_number" />
    <meta-data android:name="com.aliyun.ams.push.gcm.applicationid" android:value="id=Your_FCM_mobilesdk_app_id" />
    <meta-data android:name="com.aliyun.ams.push.gcm.projectid" android:value="id=Your_FCM_project_id"/>
    <meta-data android:name="com.aliyun.ams.push.gcm.apiKey" android:value="id=Your_FCM_current_key"/>
</application>

3.2 Create a notification channel

You must create a notification channel for Android 8.0 and later.

PushHelper.CreateNotificationChannel(
    id: "default_channel",
    name: "Default Notification",
    importance: PushHelper.IMPORTANCE_DEFAULT,
    desc: "Default notification channel for the application",
    showBadge: true,
    enableLights: true,
    lightColor: unchecked((int)0xFF0000FF),  // Blue
    enableVibration: true,
    vibrationPattern: "0,250,250,250"
);

When you send a push notification from the server, set the AndroidNotificationChannel parameter (or the ChannelId parameter in Push v2) to the same ID as the channel created on the client.

3.3 Configure the Android message receiver callback (Optional)

If you want to set up an Android message receiver callback, you must set it before you call InitPush. For example:

#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 Set the foreground notification handling mode (Optional)

For an iOS application, you can set the foreground notification handling mode to determine whether to display a notification and whether to invoke the callback.

#if UNITY_IOS
// Show notification and invoke callback
PushHelper.SetIOSForegroundNotificationMode(PushHelper.IOS_FOREGROUND_SHOW_AND_CALLBACK);
#endif

4.2 Configure the iOS message receiver callback (Optional)

To set the callback for receiving Android messages, you must set it before you call InitPush. For example:

#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 Install pod dependencies

The Assets/Plugins/Editor/iOSAliyunPushPostProcessor.cs script automatically generates a Podfile. After you build the iOS Xcode project, go to the project's root directory and run the following commands:

pod repo update AliyunRepo
pod install

# If you have not added the Alibaba Cloud CocoaPods repository, run the following command first to add it.
# pod repo add AliyunRepo https://github.com/aliyun/aliyun-specs.git

6.2 Configure APNs push capabilities

After you open the Xcode project, configure it as follows:

1. Go to Target > Signing & Capabilities and add the Push Notifications and Background Modes capabilities.

2. In Background Modes, select Remote notifications.

For more information, see 2.3 Configure APNs push capabilities.

1.1 SetLogLevel - Set the log level

Sets the log output level of the SDK for debugging and troubleshooting.

Method signature:

public static void SetLogLevel(string logLevel)

Parameters:

• logLevel: The log level. Valid values:

  • PushHelper.LOG_OFF: Disables logging.

  • PushHelper.LOG_ERROR: Logs errors only.

  • PushHelper.LOG_WARN: Logs warnings and errors.

  • PushHelper.LOG_INFO: Logs informational messages, warnings, and errors.

  • PushHelper.LOG_DEBUG: Logs all messages for debugging purposes.

Platform support: iOS and Android

Example:

// Use the DEBUG level in the development environment.
#if UNITY_EDITOR || DEVELOPMENT_BUILD
    PushHelper.SetLogLevel(PushHelper.LOG_DEBUG);
#else
    // Disable logging or show only errors in the production environment.
    PushHelper.SetLogLevel(PushHelper.LOG_ERROR);
#endif

Notes:

• In a production environment, we recommend that you disable or lower the log level to avoid performance impacts and prevent information leaks.

1.2 SetAndroidMessageReceiver - Set the Android message receiver callback

Sets all message and notification callbacks for the Android platform. This method must be called before `InitPush`.

Method signature:

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
)

Parameters:

• onMessage: The callback for when a pass-through message arrives.

  • Trigger: This callback is triggered when a pass-through message is received through the Alibaba Cloud proprietary channel.

  • Parameter 1 (string title): The message title.

  • Parameter 2 (string body): The message content.

  • Description: Pass-through messages are not displayed in the notification bar. You must handle the UI display yourself.

• onNotification: The callback for when a notification arrives.

  • Trigger: This callback is triggered when a notification is received through the Alibaba Cloud proprietary channel.

  • Parameter 1 (string title): The notification title.

  • Parameter 2 (string body): The notification content.

  • Parameter 3 (Dictionary<string, string> extraMap): A dictionary of the extended fields of the notification.

  • Description: This callback is used to record or process notification arrival events.

• onNotificationOpened: The callback for when a notification is clicked.

  • Trigger: This callback is triggered when a user clicks a notification from the Alibaba Cloud proprietary channel or the FCM channel.

  • Parameter 1 (string title): The notification title.

  • Parameter 2 (string body): The notification content.

  • Parameter 3 (string extraMapString): A JSON string of the extended fields of the notification.

  • Description: Use this callback to handle navigation logic after a user clicks a notification, such as opening a specific page.

• onNotificationClickedWithNoAction: The callback for a notification click with no action.

  • Trigger: This callback is triggered when a user clicks a notification from the Alibaba Cloud proprietary channel. You must set the AndroidOpenType parameter (or the OpenType parameter under Accs in Push v2) to NONE when you send the push notification.

  • Parameter 1 (string title): The notification title.

  • Parameter 2 (string body): The notification content.

  • Parameter 3 (string extraMapString): A JSON string of the extended fields of the notification.

  • Description: This callback is triggered when the push notification is configured to have no action on click. You can define custom handling logic in this callback.

• onNotificationRemoved: The callback for when a notification is removed.

  • Trigger: This callback is triggered when a user manually clears a notification from the Alibaba Cloud proprietary channel.

  • Parameter 1 (string messageId): The unique message ID.

  • Description: Use this callback to track notification dismissals.

• onNotificationReceivedInApp: The callback for when an in-app notification is received.

  • Trigger: Occurs when the application receives a notification from the Alibaba Cloud proprietary channel and you have overridden the showNotificationNow method in Assets/Plugins/Android/alicloud-push/PushMessageReceiver.java to return false. In this case, the notification is not displayed.

  • Parameter 1 (string title): The notification title.

  • Parameter 2 (string body): The notification content.

  • Parameter 3 (Dictionary<string, string> extraMap): A dictionary of the extended fields of the notification.

  • Parameter 4 (int openType): The open type. Valid values: 1 (Activity), 2 (URL), and 3 (No action).

  • Parameter 5 (string openActivity): The name of the Activity to open.

  • Parameter 6 (string openUrl): The URL to open.

  • Description: Use this callback to customize the display of in-app notifications. This callback must be used with notification interception.

• onSysNoticeOpened: The callback for when a notification from a third-party channel (excluding FCM) is clicked.

  • Trigger: This callback is triggered when a user clicks a notification sent through a third-party channel, such as Xiaomi, Huawei, or OPPO. You must set the AndroidPopupActivity parameter (or the VendorChannelActivity parameter in Push v2) to com.alibaba.sdk.android.pushwrapper.ThirdPushActivity when you send the push notification.

  • Parameter 1 (string title): The notification title.

  • Parameter 2 (string body): The notification content.

  • Parameter 3 (Dictionary<string, string> extraMap): A dictionary of the extended fields of the notification.

  • Description: This callback handles click events for notifications from third-party channels.

Platform support: Android only

Example:

#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

Notes:

• You must set the callback before you call InitPush.

• All callback parameters are optional. You need to set only the callbacks that you require.

1.3 SetIOSMessageReceiver - Set the iOS message receiver callback

Sets all message and notification callbacks for the iOS platform. This method must be called before `InitPush`.

Method signature:

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
)

Metric description:

• onMessageReceived: Callback for when a message is received through the Alibaba Cloud proprietary channel.

  • Trigger: When a pass-through message is received through the Alibaba Cloud proprietary channel.

  • Parameter 1 (string title): The message title.

  • Parameter 2 (string body): The message content.

  • Description: Pass-through messages are not displayed in the Notification Center. You must handle the UI display for these messages.

• onAPNSRegisterSuccess: Callback for a successful Apple Push Notification service (APNs) registration.

  • Trigger: When the device successfully registers with the APNs server and obtains a device token.

  • Parameter 1 (string deviceToken): The device token assigned by the Apple Push Notification service.

  • Description: The device token is used for direct server-side pushes.

• onAPNSRegisterFailed: Callback for a failed APNs registration.

  • Trigger: When the device fails to register with the APNs server.

  • Parameter 1 (string error): The error message for the registration failure.

  • Description: You can use this callback to troubleshoot APNs registration issues. Common causes include network problems and incorrect certificate configurations.

• onForegroundNotificationReceived: Callback for when a notification is received while the application is in the foreground.

  • Trigger: When an APNs notification is received while the application is in the foreground.

  • Parameter 1 (string title): The notification title.

  • Parameter 2 (string body): The notification content.

  • Parameter 3 (string subtitle): The notification subtitle (supported in iOS 10 and later).

  • Parameter 4 (string userInfo): A JSON string that contains the notification's user information and custom fields.

  • Description: By default, iOS applications do not display notifications while they are in the foreground. You can use this callback to define custom handling.

• onNotificationOpened: Callback for when a notification is clicked.

  • Trigger: When a user clicks a push notification in the Notification Center.

  • Parameter 1 (string title): The notification title.

  • Parameter 2 (string body): The notification content.

  • Parameter 3 (string subtitle): The notification subtitle.

  • Parameter 4 (string userInfo): A JSON string that contains the notification's user information.

  • Description: You can use this callback to handle navigation logic after a user clicks a notification. The application is then launched or brought to the foreground.

• onNotificationRemoved: Callback for when a notification is removed.

  • Trigger: When a user manually clears a notification from the Notification Center. For this callback to be triggered, you must set the iOSNotificationCategory parameter (or the Category parameter under Ios in Push v2) to aliyun_push_category when sending the push notification. If you want to use a custom category name, you must also modify the category name in the createCustomNotificationCategory method in the Assets/Plugins/iOS/alicloud-push/PushWrapper.m file.

  • Parameter 1 (string userInfo): A JSON string that contains the notification's user information.

  • Description: You can use this callback to track notification dismissals. This feature is supported in iOS 10 and later.

• onRemoteNotificationReceived: Callback for when a silent notification is received.

  • Trigger: When the application receives a silent push notification. For this callback to be triggered, you must set the iOSSilentNotification parameter (or the Silent parameter under Ios in Push v2) to true when sending the push notification.

  • Parameter 1 (string title): The notification title. This may be empty for silent pushes.

  • Parameter 2 (string body): The notification content. This may be empty for silent pushes.

  • Parameter 3 (string subtitle): The notification subtitle. This may be empty for silent pushes.

  • Parameter 4 (string userInfo): A JSON string that contains the notification's user information.

  • Description: You can use this callback to handle silent pushes for tasks such as data synchronization or content pre-loading. A notification is not displayed to the user.

Supported platform: iOS only

Example:

#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

Notes:

• You must set the callback before calling InitPush.

• Because all callback parameters are optional, you only need to set the ones that you require.

1.4 SetIOSForegroundNotificationMode - Set the iOS foreground notification handling mode

Sets how notifications are handled when the iOS application is in the foreground.

Method signature:

public static void SetIOSForegroundNotificationMode(string mode)

Parameters:

• mode: The handling mode. Valid values:

  • PushHelper.IOS_FOREGROUND_SHOW_AND_CALLBACK: Displays the notification and invokes the callback.

  • PushHelper.IOS_FOREGROUND_SHOW_ONLY: Displays the notification only. Does not invoke the callback.

  • PushHelper.IOS_FOREGROUND_CALLBACK_ONLY: Invokes the callback only. Does not display the notification.

Platform support: iOS only

Example:

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

2.1 InitPush - Initialize the push service

Initializes the push SDK. This is a core step for using the push service.

Method signature:

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

Parameters

• appKey: The AppKey for your application, obtained from the Alibaba Cloud Mobile Push console.

• appSecret: The AppSecret for your application, obtained from the Alibaba Cloud Mobile Push console.

• callback: The callback for the initialization result.

  • bool: Indicates whether the operation succeeded.

  • string: The error message that is returned if the request fails.

Supported platforms: iOS and Android

Example:

PushHelper.InitPush("Your_AppKey", "Your_AppSecret", (success, message) => {
    if (success) {
        Debug.Log("Push initialization successful: " + message);
    } else {
        Debug.LogError("Push initialization failed: " + message);
    }
});

Note:

• For Android, you must also configure the AppKey and AppSecret in AndroidManifest.xml.

• You can call this method as early as possible upon application startup.

• You can use other push features only after the initialization is successful.

2.2 InitAndroidThirdPush - Initialize Android third-party channels

Initializes Android third-party push channels, such as Xiaomi, Huawei, OPPO, vivo, and Meizu, to improve the delivery rate of offline push notifications.

Method signature:

public static void InitAndroidThirdPush()

Platform support: Android only

Example:

#if UNITY_ANDROID
PushHelper.InitAndroidThirdPush();
#endif

Notes:

• You must configure the parameters for the corresponding third-party channels in the AndroidManifest.xml file.

• This applies only to devices from the corresponding brand.

• Call this method after the InitPush call is successful.

3.1 BindAccount - Bind an account

Binds a device to a business account. After the binding is successful, you can send push notifications to the account.

Method signature:

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

Parameters

• account: The user account, such as a user ID.

• callback: The callback that receives the binding result.

Supported platforms: iOS & Android

Example:

PushHelper.BindAccount("user123", (success, message) => {
    if (success) {
        Debug.Log("Account bound successfully");
    } else {
        Debug.LogError("Failed to bind account: " + message);
    }
});

Notes:

• A device can be bound to only one account. Re-binding the device overwrites the previous binding.

• Account-based push notifications enable you to precisely target specific users.

3.2 UnbindAccount - Unbind an account

Removes the binding between a device and a business account.

Method signature:

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

Parameters:

• callback: The callback for the unbind result.

Supported platforms: iOS and Android

Example:

PushHelper.UnbindAccount((success, message) => {
    if (success) {
        Debug.Log("Account unbound successfully");
    } else {
        Debug.LogError("Failed to unbind account: " + message);
    }
});

4.1 BindTag - Attach a tag

Binds a tag to a specified target.

Method signature:

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

Metric Description:

• target: The target type.

  • 1: Device (CloudPushService.DEVICE_TARGET)

  • 2: Account (CloudPushService.ACCOUNT_TARGET)

  • 3: Alias (CloudPushService.ALIAS_TARGET)

• tag: The tag name.

• alias: The alias (required only when target is 3).

• callback: The callback for the result of the attach operation.

Supported platforms: iOS and Android

Example:

// Attach a tag to the device
PushHelper.BindTag(1, "VIP_User", null, (success, message) => {
    if (success) {
        Debug.Log("Device tag attached successfully");
    } else {
        Debug.LogError("Failed to attach tag: " + message);
    }
});

Notes:

• You can attach multiple tags to a target.

• Use meaningful category names for tags.

4.2 UnbindTag - Detach a tag

Unbinds a tag from a specified target.

Method signature:

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

Parameters:

• target: The target type. Valid values: 1 (Device), 2 (Account), or 3 (Alias).

• tag: The tag name.

• alias: The alias. This parameter is required if the `target` is 3.

• callback: The callback for the result of the detach operation.

Supported platforms: iOS and Android

Example:

// Detach a device tag
PushHelper.UnbindTag(1, "VIP_User", null, (success, message) => {
    if (success) {
        Debug.Log("Tag detached successfully");
    } else {
        Debug.LogError("Failed to detach tag: " + message);
    }
});

Notes:

• You can detach only existing tags.

4.3 ListTags - List tags

Queries all tags that are bound to a specified target.

Method signature:

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

Parameters:

• target: The target type. A value of 1 indicates a device.

• callback: The callback for the query result. A list of tags is returned on success.

Supported platforms: iOS & Android

Example:

// Query all tags for the device
PushHelper.ListTags(1, (success, tags) => {
    if (success) {
        Debug.Log("Tag list: " + tags);
    } else {
        Debug.LogError("Query failed: " + tags);
    }
});

5.1 AddAlias - Add an alias

Adds an alias to a device.

Method signature:

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

Parameters:

• alias: The alias.

• callback: The callback for the result of the add operation.

Supported platforms: iOS & Android

Example:

PushHelper.AddAlias("player_001", (success, message) => {
    if (success) {
        Debug.Log("Alias added successfully");
    } else {
        Debug.LogError("Failed to add alias: " + message);
    }
});

Notes:

• A device can have multiple aliases.

• Aliases enable more flexible push notification scenarios.

• Use meaningful alias names.

5.2 RemoveAlias - Remove an alias

Removes a specified alias from a device.

Method signature:

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

Parameters:

• alias: The alias.

• callback: The callback to handle the removal result.

Supported platforms: iOS & Android

Example:

// Remove an alias
PushHelper.RemoveAlias("player_001", (success, message) => {
    if (success) {
        Debug.Log("Alias removed successfully");
    } else {
        Debug.LogError("Failed to remove alias: " + message);
    }
});

Notes:

• You can only remove existing aliases.

• After an alias is removed, you can no longer use it to send push notifications to the device.

5.3 ListAliases - List aliases

Queries all aliases for a device.

Method signature:

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

Parameters

• callback: The callback function for the query result. On success, this function receives a list of aliases.

Supported platforms: iOS & Android

Example:

// Query all aliases for the device
PushHelper.ListAliases((success, aliases) => {
    if (success) {
        Debug.Log("Alias list: " + aliases);
    } else {
        Debug.LogError("Query failed: " + aliases);
    }
});

6.1 BindPhoneNumber - Bind a mobile phone number

Binds a mobile phone number to a device.

Method signature:

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

Parameters:

• phone: The mobile phone number.

• callback: The callback that receives the binding result.

Supported platform: Android only

Example:

#if UNITY_ANDROID
PushHelper.BindPhoneNumber("13800138000", (success, message) => {
    if (success) {
        Debug.Log("Mobile phone number bound successfully");
    } else {
        Debug.LogError("Failed to bind mobile phone number: " + message);
    }
});
#endif

Notes:

• This feature is supported only on the Android platform.

• This feature is used for integrated text message push solutions.

• Each device can be bound to only one mobile phone number.

6.2 UnbindPhoneNumber - Unbind a mobile phone number

Removes the binding between a device and a mobile phone number.

Method signature:

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

Metric description:

• callback: The callback that returns the unbinding result.

Platform support: Android only

Example:

#if UNITY_ANDROID
// Unbind the mobile phone number
PushHelper.UnbindPhoneNumber((success, message) => {
    if (success) {
        Debug.Log("Mobile phone number unbound successfully");
    } else {
        Debug.LogError("Failed to unbind mobile phone number: " + message);
    }
});
#endif

Note:

• After unbinding, you will lose access to the integrated text message push feature.

7.1 GetDeviceId - Get the device ID

Retrieves the unique device identifier that is assigned by the push service.

Method signature:

public static string GetDeviceId()

Return value

• Device ID (string)

Supported platforms: iOS and Android

Example:

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

Notes:

• This call must be made after InitPush succeeds.

• The device ID is a unique identifier for the push service.

• Server-side APIs can use it to send push notifications to the device.

8.1 IsNotificationEnabled - Check notification permissions

Checks whether the user has granted the application permission to display notifications.

Method signature:

public static bool IsNotificationEnabled()

Return value:

• true: Notification permissions are enabled.

• false: Notification permissions are disabled.

Supported platforms: Android only

Example:

#if UNITY_ANDROID
bool isEnabled = PushHelper.IsNotificationEnabled();
Debug.Log("Notification permission status: " + isEnabled);
#endif

Notes:

• Check for notification permissions upon application startup.

• If the permissions are not enabled, guide the user to the settings page.

8.2 IsNotificationChannelEnabled - Check notification channel permissions

Checks whether a specified notification channel is enabled. This method is for Android 8.0 and later.

Method signature:

public static bool IsNotificationChannelEnabled(string channelId)

Metric Description:

• channelId: The ID of the notification channel.

Return value

• true: The notification channel is enabled.

• false: The notification channel is disabled.

Platform: Android only

Example:

#if UNITY_ANDROID
bool isEnabled = PushHelper.IsNotificationChannelEnabled("default_channel");
Debug.Log("Notification channel status: " + isEnabled);
#endif

Note:

• This applies only to Android 8.0 and later.

• You must first create the notification channel.

8.3 JumpToNotificationSetting - Go to notification settings

Navigates to the application's notification settings page.

Method signature:

public static void JumpToNotificationSetting()

Supported platforms: Android only

Example:

#if UNITY_ANDROID
PushHelper.JumpToNotificationSetting();
#endif

Note:

• The System Settings page opens. You must manually enable the setting.

• We recommend that you provide guidance to the user if a permission is not granted.

8.4 JumpToNotificationChannelSetting - Go to notification channel settings

Navigates to the settings page for a specified notification channel.

Method signature:

public static void JumpToNotificationChannelSetting(string channelId)

Parameters

• channelId: The ID of the notification channel.

Supported platforms: Android only

Example:

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

Note

• This applies only to Android 8.0 or later.

• Some devices may not support this feature. In such cases, the user is redirected to the main notification settings page.

8.5 CreateNotificationChannel - Create a notification channel

Creates an Android notification channel. This is required for Android 8.0 and later.

Method signature:

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 = ""
)

Parameters:

• id: The channel ID (unique identifier).

• name: The channel name (visible to users).

• importance: The importance level (0-5).

  • PushHelper.IMPORTANCE_NONE (0): Does not show a notification.

  • PushHelper.IMPORTANCE_MIN (1): Lowest level. Makes no sound.

  • PushHelper.IMPORTANCE_LOW (2): Low level. Makes no sound.

  • PushHelper.IMPORTANCE_DEFAULT (3): Default level. Makes a sound.

  • PushHelper.IMPORTANCE_HIGH (4): High level. Makes a sound and appears as a heads-up notification.

  • PushHelper.IMPORTANCE_MAX (5): Highest level.

• desc: The channel description.

• showBadge: Specifies whether to show a badge.

• enableLights: Specifies whether to enable the LED indicator.

• lightColor: The color of the LED indicator (ARGB format).

• enableVibration: Specifies whether to enable vibration.

• vibrationPattern: The vibration pattern (comma-separated millisecond values).

Platform: Android only

Example:

#if UNITY_ANDROID
PushHelper.CreateNotificationChannel(
    id: "default_channel",
    name: "Default Notification",
    importance: PushHelper.IMPORTANCE_DEFAULT,
    desc: "Default notification channel for the application",
    showBadge: true,
    enableLights: true,
    lightColor: unchecked((int)0xFF0000FF),  // Blue
    enableVibration: true,
    vibrationPattern: "0,250,250,250"
);
#endif

Note

• You must create a notification channel for Android 8.0 and later.

• Create the channel when the application starts.

• Once a channel is created, users can manage it in the system settings.

• The lightColor uses the ARGB format. Use unchecked to prevent overflow.