Game > Gamebase > Unity Developer's Guide > Push

This document describes how to set push notifications for each platform.

[Caution]

If there is push-related processing in an external package, the Gamebase push function may not work properly.

Settings

For how to set up push on Android or iOS, refer to the following documents.

• Android
  • Android Push Settings
  • Firebase Notification Settings
• iOS
  • iOS Push Settings

Register Push

Call the following API to register the user for NHN Cloud Push. Get the values of consent to receiving push (enablePush), consent to receiving advertisement push (enableAdPush), and consent to receiving night-time advertisement push (enableAdNightPush) from the user, and call the following API to complete the registration.

[Caution]

It is recommended to call the registerPush API every time after logging in because the push settings may be different for each UserID and the push token may expire.

API

Supported Platforms

■ UNITY_IOS ■ UNITY_ANDROID

public static void RegisterPush(GamebaseRequest.Push.PushConfiguration pushConfiguration, GamebaseCallback.ErrorDelegate callback);
public static void RegisterPush(GamebaseRequest.Push.PushConfiguration pushConfiguration, GamebaseRequest.Push.NotificationOptions options, GamebaseCallback.ErrorDelegate callback);

GamebaseRequest.Push.PushConfiguration

Parameter	Mandatory(M) / Optional(O)	Values	Description
pushEnabled	M	bool	Consent to receiving pushes or not
adAgreement	M	bool	Consent to receiving advertising pushes or not
ADAgreemadAgreementNightentNight	M	bool	Consent to receiving nightime advertising pushes or not
requestNotificationPermission	O	bool	Whether to automatically display the Push permission request popup when calling the RegisterPush API on Android 13 and later OSes default: true Only for Android
alwaysAllowTokenRegistration	O	bool	Whether to register tokens if user denies push permissions When set to true, register tokens even if push permissions are not obtained. default: false Only for iOS

Example

public void RegisterPush(bool pushEnabled, bool adAgreement, bool adAgreementNight, bool requestNotificationPermission, bool alwaysAllowTokenRegistration)
{
    GamebaseRequest.Push.PushConfiguration pushConfiguration = new GamebaseRequest.Push.PushConfiguration
    {
        pushEnabled = pushEnabled,
        adAgreement = adAgreement,
        adAgreementNight = adAgreementNight,
        displayLanguageCode = displayLanguage,
        requestNotificationPermission = requestNotificationPermission,
        alwaysAllowTokenRegistration = alwaysAllowTokenRegistration
    };

    // You should receive the above values to the logged-in user.
    Gamebase.Push.RegisterPush(pushConfiguration, (error) =>
    {
        if (Gamebase.IsSuccess(error))
        {
            Debug.Log("RegisterPush succeeded.");
        }
        else
        {
            Debug.Log(string.Format("RegisterPush failed. error is {0}", error));
        }
    });
}

Setting for APNS Sandbox

• Enable the SandboxMode, and push messages can be registered and sent via APNS Sandbox.
• Sending from Console
  • Select iOS Sandbox from Target of the Push menu, and send.

Notification Options

• You can use the Notification Options to change how the notification will be displayed in the device.
• You can call the registerPush API at runtime to change it.

Set Notification Options with RegisterPush in Runtime

When calling the RegisterPush API, you can add the GamebaseRequest.Push.NotificationOptions argument to set the notification options. If you pass the Gamebase.Push.GetNotificationOptions() call results to the creator of the GamebaseRequest.Push.NotificationOptions, the object initialized with the current notification options is created, and you can just change the necessary values.
The following settings are available:

API	Parameter	Description
foregroundEnabled	bool	Expose the notifications when the app is in the foreground status default: false
badgeEnabled	bool	Use the badge icon default: true
soundEnabled	bool	Whether to use the notification sound default: true iOS Only
priority	int	Notification priority. You can set the following five values: GamebaseNotificationPriority.MIN : -2 GamebaseNotificationPriority.LOW : -1 GamebaseNotificationPriority.DEFAULT : 0 GamebaseNotificationPriority.HIGH : 1 GamebaseNotificationPriority.MAX : 2 default: GamebaseNotificationPriority.HIGH Android Only
smallIconName	string	Small icon file name for notification. If disabled, the app icon is used. default: null Android Only
soundFileName	string	Notification sound file name. Works only in OS with Android 8.0 or less. The notification sound changes if you specify the mp3, wav file name in the 'res/raw' folder. default: null Android Only

Example

public void RegisterPush(bool pushEnabled, bool adAgreement, bool adAgreementNight, bool requestNotificationPermission, bool alwaysAllowTokenRegistration)
    GamebaseRequest.Push.PushConfiguration pushConfiguration = new GamebaseRequest.Push.PushConfiguration
    {
        pushEnabled = pushEnabled,
        adAgreement = adAgreement,
        adAgreementNight = adAgreementNight,
        requestNotificationPermission = requestNotificationPermission,
        alwaysAllowTokenRegistration = alwaysAllowTokenRegistration
    };

    var notificationOptions = new GamebaseRequest.Push.NotificationOptions
    {
        foregroundEnabled = true,
        priority = GamebaseNotificationPriority.HIGH
    };

    Gamebase.Push.RegisterPush(configuration, notificationOptions, (error) =>
    {
        if (Gamebase.IsSuccess(error) == true)
        {
            Debug.Log("RegisterPush succeeded.");
        }
        else
        {
            // Check the error code and handle the error appropriately.
            Debug.Log(string.Format("RegisterPush failed. error is {0}", error));
        }
    });
}

Get NotificationOptions

Retrieves the notification options value which was set previously when registering the push notification.

API

Supported Platforms

■ UNITY_IOS ■ UNITY_ANDROID

public static GamebaseResponse.Push.NotificationOptions GetNotificationOptions();

Example

public void GetNotificationOptionsSample()
{
    GamebaseResponse.Push.NotificationOptions notificationOptions = Gamebase.Push.GetNotificationOptions();

    GamebaseRequest.Push.NotificationOptions options = new GamebaseRequest.Push.NotificationOptions(notificationOptions);
    options.foregroundEnabled = true;
    options.smallIconName = "notification_icon_name";

    GamebaseRequest.Push.PushConfiguration configuration = new GamebaseRequest.Push.PushConfiguration();
    Gamebase.Push.RegisterPush(configuration, options, (error)=> { });
}

Request Push Settings

To retrieve user's push setting, apply API as below. From GamebaseResponse.Push.TokenInfo callback values, you can get user's value set.

API

Supported Platforms

■ UNITY_IOS ■ UNITY_ANDROID

public static void QueryTokenInfo(GamebaseCallback.GamebaseDelegate<GamebaseResponse.Push.TokenInfo> callback);

// Legacy API
public static void QueryPush(GamebaseCallback.GamebaseDelegate<GamebaseResponse.Push.PushConfiguration> callback);

Example

public void QueryTokenInfoSample(bool isSandbox)
{
    Gamebase.Push.QueryTokenInfo((data, error)=> 
    {
        if (Gamebase.IsSuccess(error)) 
        {
            // Succeeded.
            bool enablePush = data.agreement.pushEnabled;
            bool enableAdPush = data.agreement.adAgreement;
            bool enableAdNightPush = data.agreement.adAgreementNight;
            string token = data.token;
        } 
        else 
        {
        // Failed.
        }
    });
}

GamebaseResponse.Push.TokenInfo

Parameter	Values	Description
pushType	string	Push token type
token	string	Token
userId	string	User ID
deviceCountryCode	string	Country code
timezone	string	Standard timezone
registeredDateTime	string	Token update time
languageCode	string	Language settings
agreement	GamebaseResponse.Push.Agreement	Opt in
sandbox	bool	Whether to use sandbox (iOS Only)

GamebaseResponse.Push.Agreement

Parameter	Values	Description
pushEnabled	bool	Opt in to display notifications
adAgreement	bool	Opt in to display advertisement notifications
adAgreementNight	bool	Opt in to display night advertisement notifications

Event Handling

• You can handle events when a push message is received or clicked.
• For how to register event handlers, refer to the GamebaseEventHandler guide.
  • Game > Gamebase > Unity SDK User Guide > ETC > Additional Features > Gamebase Event Handler > Push Received Message
  • Game > Gamebase > Unity SDK User Guide > ETC > Additional Features > Gamebase Event Handler > Push Click Message
  • Game > Gamebase > Unity SDK User Guide > ETC > Additional Features > Gamebase Event Handler > Push Click Action

Setting for APNS Sandbox

• By turning on the SandboxMode, it can be registered so that the push will be sent with the APNS Sandbox.
• How to send console
  • In the Target of the Push menu, select iOS Sandbox to send it.

API

Supported Platforms

■ UNITY_IOS

public static void SetSandboxMode(bool isSandbox)

Example

public void SetSandboxModeSample()
{
    Gamebase.Push.SetSandboxMode(true);
}

Error Handling

Error	Error Code	Description
PUSH_EXTERNAL_LIBRARY_ERROR	5101	Error in NHN Cloud Push library. Please check the code details.
PUSH_ALREADY_IN_PROGRESS_ERROR	5102	Previous Push API call is not completed. Please call again after the previous push API callback is executed.
PUSH_UNKNOWN_ERROR	5999	Undefined push error. Please upload the entire logs to Customer Center, and we'll respond ASAP.

• Refer to the following document for the entire error codes.
  • Entire Error Codes

PUSH_EXTERNAL_LIBRARY_ERROR

• The error is returned when an error occurs in NHN Cloud Push library.
• The information on the error in NHN Cloud Push library is included in the error details, and you can find detailed error code and message as follows.

GamebaseError gamebaseError = error; // GamebaseError object via callback

if (Gamebase.IsSuccess(gamebaseError))
{
    // succeeded
}
else
{
    Debug.Log(string.Format("code:{0}, message:{1}", gamebaseError.code, gamebaseError.message));

    GamebaseError moduleError = gamebaseError.error; // GamebaseError.error object from external module
    if (null != moduleError)
    {
        int moduleErrorCode = moduleError.code;
        string moduleErrorMessage = moduleError.message;

        Debug.Log(string.Format("moduleErrorCode:{0}, moduleErrorMessage:{1}", moduleErrorCode, moduleErrorMessage));
    }
}

• NHN Cloud Push error codes are as follows:
  • Android
    
  • iOS