Skip to main content

Push Notification

note

In Android 12 and above systems, due to the tightening of SCHEDULE_EXACT_ALARM permission requests by the Android API, the Player Network SDK uses internal delay triggers to implement push.Therefore, after the app is closed, delayed code cannot be triggered, and the trigger time may deviate due to the system sleep strategy.

Prerequisites​

To start using local notifications, simply integrate the Player Network SDK.

Remote push notifications utilize Firebase's push functionality. To use remote push, please complete the following steps:

1. Register the Firebase project

In the Firebase Console page, follow the prompts to register a Firebase project.

Image: Register Firebase project

2. Add an application
note

Firebase supports Multi-store channel package, allowing multiple apps to be created under the same developer account.Simply fill in the new channel package name and corresponding signature configuration under the same Firebase project, and complete additional game application configuration by repeating the following steps.

  1. In the Project Overview page of the Firebase Console, add the Firebase application for the corresponding platform.

    Image: Add Firebase function

  2. Add the relevant information according to prompts.

  3. Add Android application.

    Image: Add Android App

    1. After filling in the information, click REGISTER APP.
      If some fields are uncertain, they can be supplemented later in settings.
    2. Download the google-services.json file for backup, and it can be re-downloaded from the Firebase Console later.
    3. Skip other steps.

  4. Add iOS application.

    Image: Add iOS App

    1. After filling in the information, click REGISTER APP.
      If some fields are uncertain, they can be supplemented later in settings.
    2. Download the google-services.json file for backup, and it can be re-downloaded from the Firebase Console later.
    3. Configure APN certificates for push functionality.
3. Upload iOS APNs Certificate

  1. On the Settings page, click CLOUD MESSAGING and find the iOS project.

    Image: Firebase Cloud Messaging Settings

  2. Add Development Certificate and Production Certificate separately.

    Image: Firebase Cloud Messaging iOS Certificates

For more details, see Set up Apple platform client.

4. Project Configuration

In Project settings, you can continue to edit project information, download google-services.json and GoogleService-Info.plist, or configure the Android certificate fingerprint.

Image: Firebase Project Settings

  1. Integrate the Player Network SDK.

Step 1: Permissions and project configuration​

Local Notification​

Add the following configuration in Android's INTLConfig.ini.

[Android Local Notification]
ANDROID_LOCAL_NOTIFICATION_ENABLE = 1

Remote Push​

Firebase remote push configuration for the push module.

Android​

User Permissions
caution

Since Firebase SDK only supports minSdkVersion >= 19, running on systems below Android 4.2 may have issues. Set minSdkVersion >= 19 for your game.

Firebase requires access to network permissions.

<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
Project Configuration

Configure the Android client key in the INTLConfig.ini file.

[Google]
GOOGLE_CLIENT_KEY_ANDROID = {YOUR_CLIENT_KEY_ANDROID}
  • Replace {YOUR_CLIENT_KEY_ANDROID} with the Web client key required by Player Network SDK, the client ID corresponding to webpage client when configuring API OAuth in the Credentials page.This is the Server Client ID established in the OAuth operations configured at the backend of OAuth 2.5.

google-services.json

caution

Missing google-services.json file will cause packaging failure.

Gradle packaging supports reading contents directly from the google-services.json file, which are converted into the corresponding app/build/generated/res/google-services/{build_type}/values/values.xml configuration file.

For more details on adding the google-services.json file under the project's Assets/Plugins/Android/ directory, see The Google Services Gradle Plugin.

[Optional] Configure Default Background Color

Specify the color when configuring notifications to use it as the default notification banner background color.

You can define color in the resource files under the Android project directory at Unity's Assets/Plugins/Android/.
For example: xxx/res/values/colors.xml.

{/* Set the color for push notifications to be used when the notification itself has not set a color. For more information, see README(https://goo.gl/6BKBk7). */}
  <meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorAccent" />

[Optional] Configure Default Icon

Specify the icon when configuring notifications to use it as the default notification icon.

You can place drawable files in the Android project directory under Unity's Assets/Plugins/Android/.
For example: xxx/res/drawable.

{/*Set a custom default icon, used when the notification itself does not have an icon set.
    See README(https://goo.gl/l4GJaQ) for more information.*/ }
<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_stat_ic_notification" />

Android supports small and large push icons.

  • The small icon is displayed in the top status bar and notification banner.
note

For Android 5.0+ (API level 21+), the icon background must be white and transparent.The shadow of the notification banner can be colored with an accent color, but the icon's color is not affected by the accent color.

  • The recommended size for the large icon is 256x256 pixels; if not set, the small icon will be used.The display position of the large icon depends on the Android version of the device:
    • On Android 4.0.3 — 6.0 (API levels 15 – 23) devices, it displays on the left side of the notification text.
    • On Android 7.0+ (API level 24+) devices, it displays on the right side of the notification text.

It is recommended to use the Notification icon generator tool to create push icons with appropriate resolutions.

Pixel DensityResolutionFile Path
MDPI24 x 24 (drawable-mdpi)Assets/Plugins/Android/res/drawable-mdpi/
HDPI36 x 36 (drawable-hdpi)Assets/Plugins/Android/res/drawable-hdpi/
XHDPI48 x 48 (drawable-xhdpi)Assets/Plugins/Android/res/drawable-xhdpi/
XXHDPI72 x 72 (drawable-xxhdpi)Assets/Plugins/Android/res/drawable-xxhdpi/
XXXHDPI96 x 96 (drawable-xxxhdpi)Assets/Plugins/Android/res/drawable-xxxhdpi/
XXXHDPI (large)256 x 256 (drawable-xxxhdpi) (large)Assets/Plugins/Android/res/drawable-xxxhdpi/

iOS​

Project Configuration

Firebase Plist​

caution

Missing GoogleService-info.plist file will cause app startup crash.

Replace the configuration file GoogleService-info.plist into the Assets/Plugins/iOS/INTLSDK/INTLFirebase/ThirdSDK/ directory.

Image: Unity Plist File

Enable push for Xcode project​

Unity needs to enable the Firebase push feature in the Xcode project.Before exporting the Xcode project, you need to complete the .projmods file configuration.

Player Network SDK has already written the following configuration into the INTLFirebaseKit.projmods file; you only need to ensure the information is correct.

{
    "group": "INTL",
    "libs": [],
    "frameworks": [],
    "files": [
        "Plugins/iOS/INTLSDK/INTLFirebase/GoogleService-Info.plist"
    ],
    "folders": [],
    "excludes": [],
    "headerpaths":[],
    "build_settings": {},
    "system_capabilities": {"com.apple.Push":"TRUE"},
    "Info.plist":{},
}

For more information on Xcode project export, see Player Network SDK XUPorter Solution.

After export is complete, enable Remote notifications under Capability > Background Modes > Push Notifications in the project.

Step 2: Register callback​

Add the following callback for the push module.

APIFunction
AddPushBaseResultObserverAdd the BaseResult callback for the Player Network SDK push module.
Used for handling interface callbacks for RegisterPush.
RemovePushBaseResultObserverRemove the callback listener for BaseResult.
AddPushResultObserverAdd the PushResult callback for the Player Network SDK push module.
Used for handling interface callbacks for AddLocalNotification.
RemovePushResultObserverRemove the callback for PushResult.

Step 3: Configure Notifications​

Local Notification​

Call the AddLocalNotification interface.

Remote Push​

Send push notifications to all devices:

  1. Call the RegisterPush interface in the game, then terminate the game.
  2. In Firebase's backend, select Cloud Messaging, then click Create Notification. Image: Firebase Create Notification
  3. Fill in the notification title and text, then click Next. Image: Add Theme
  4. Select the bundle to send to the application, then click Next. Image: Select Bundle
  5. Select the time, then click Review. Image: Select Time
  6. Once reviewed, you can send the push notification.

Send push notifications to pushToken registered devices:

  1. Call the RegisterPush interface in the game, then copy the FCM token from the logs and terminate the game. Image: FcmToken
  2. In Firebase's backend, select Cloud Messaging, then click Create Notification. Image: Firebase Create Notification
  3. Fill in the notification title and text, then click Send Test Message. Image: Add Theme
  4. Fill in the FCM token from the logs, then click Test to conduct the push test. Image: Create Test Notification

Push Interface​

Image: Push UI

Clear iOS App Badge​

The following badge clearing code needs to be added to the applicationDidBecomeActive method in the Classes/UnityAppController.mm file in the Xcode project directory.

[UIApplication sharedApplication].applicationIconBadgeNumber=0;

Example code:

- (void)applicationDidBecomeActive:(UIApplication*)application
{
    ::printf("-> applicationDidBecomeActive()\n");

    [self removeSnapshotView]; // Code may vary between Unity versions
    [UIApplication sharedApplication].applicationIconBadgeNumber=0; // Added code


    if (_unityAppReady)
    {
        if (UnityIsPaused() && _wasPausedExternal == false)
        {
            UnityWillResume();
            UnityPause(0);
        }
        if (_wasPausedExternal)
        {
            if (UnityIsFullScreenPlaying())
                TryResumeFullScreenVideo();
        }
        UnitySetPlayerFocus(1);
    }
    else if (!_startUnityScheduled)
    {
        _startUnityScheduled = true;
        [self performSelector: @selector(startUnity:) withObject: application afterDelay: 0];
    }

    _didResignActive = false;
}

Automatically add code by creating a XCodePostProcess.cs script.

  1. Assign the variable code to the badge clearing code in the EditorCode method.
  2. Add the method through anchor code.Due to different Unity versions, please confirm whether [self removeSnapshotViewController]; or [self removeSnapshotView]; is called in the applicationDidBecomeActive method, and then use the corresponding result in Step 3.
  3. Configure unityAppController.WriteBelow according to the result of Step 2.
  4. Call EditorCode in the OnPostProcessBuild method.
  5. Check if the built UnityAppController.mm has successfully added the badge clearing code.
private static void EditorCode(string filePath)
{
    // load UnityAppController.mm
    UnityEngine.Debug.Log("EditorCode: " + filePath);
    XClass unityAppController = new XClass(filePath + "/Classes/UnityAppController.mm");

    //add codes
    string codes = "[UIApplication sharedApplication].applicationIconBadgeNumber=0;"; // Added code
    unityAppController.WriteBelow("[self removeSnapshotViewController];", codes); // Added code
}

Push Status​

Notification display behavior in different scenarios:

StatusiOSAndroid
Foreground appNot displayNot display
Background appDisplayDisplay
Exit appDisplayDisplay
note

On iOS 10 and later, you can make notifications appear on the banner by modifying userNotificationCenter:, willPresentNotification:, and withCompletionHandler:. For details, see Apple Developer Documentation.

note

三星设备，用户需在系统内设置 设置 > 通知 > 休眠 为您的 app 添加自启动权限，以在 app 退出的状态下接收推送通知。

For Xiaomi devices, background permissions in the battery settings should not be restricted to receive push notifications when the app is exited.When the app's memory is cleared, displayed notifications will also disappear. ::

Whether callbacks occur in different scenarios:

StatusiOSAndroid
Foreground appYesYes
Background appNoNo
Click NotificationYesNo

Push Notification API​

APIFunction
RegisterPushRegister Push
UnregisterPushAccount Cancellation
AddLocalNotificationAdd Local Notification
ClearLocalNotificationsClear Local Notification
DeleteLocalNotificationsDelete Local Notification

If you encounter issues during integration, please refer to the FAQs.

Privacy PolicyTerms of ServiceDPAOpen Source Licenses
©2025 Proxima Beta Pte. Ltd. All rights reserved.