Game > Gamebase > iOS Developer's Guide > Push

[Caution]

If you use a 3rd party push plugin or module such as Unreal or Unity, it may affect the Gamebase push function.

Settings

Getting Authentication Information for APNS JWT

This document describes the process of getting authentication information for APNS JWT required to deliver push notifications.

Registering Gamebase Console

  • Go to Gamebase > Push > Certificate and enter the information you get in APNS JWT.

Implementing Notification Service Extension

  • For tasks such as collecting inbound indicators and setting the notification sound, see NHN Cloud Push Guide to implement the Notification Service Extension for the application.

Setting up Xcode Project

  • Go to Targets > Capabilities > Push Notifications and set it to ON.
  • Open the .entitlements file automatically created, and set the value of the APS Environment key to an appropriate value.
    • development: Sandbox APNS
    • production: APNS

Import Header File

Import the following header file to the ViewController you want to implement a push API.

#import <Gamebase/Gamebase.h>

Register Push

Call the following API to register the user for NHN Cloud Push.

Get the values of consent to receiving push (TCGBPushConfiguration) from the user, and call the following API to complete the registration.

[Caution]

It is recommended that you always call the registerPush API after logging in, because it is not certain when the push token will expire.

API

+ (void)registerPushWithPushConfiguration:(TCGBPushConfiguration *)configuration
                               completion:(nullable void(^)(TCGBError * _Nullable error))completion;

TCGBPushConfiguration

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
ADAgreementNight M BOOL Consent to receiving nighttime advertising pushes
alwaysAllowTokenRegistration O BOOL Whether to register the token if the user denies push permissions
Set to YES to register the token even if push permissions are not obtained.
default: NO

Example

- (void)didLoginSucceeded {
    BOOL enablePush;
    BOOL enableAdPush;
    BOOL enableAdNightPush;
    BOOL alwaysAllowTokenRegistration;

    // You should receive the above values to the logged-in user.

    TCGBPushConfiguration* pushConfig = [TCGBPushConfiguration pushConfigurationWithPushEnable:enablePush
                                                                            ADAgreement:enableAdPush
                                                                        ADAgreementNight:enableAdNightPush
                                                            alwaysAllowTokenRegistration:alwaysAllowTokenRegistration];

    [TCGBPush registerPushWithPushConfiguration:pushConfig completion:^(TCGBError* error) {
        if (error != nil) {
            // To Register Push Failed.
        }
    }];
}


When registering the user for the NHN Cloud Push, the notification option can be set using the TCGBNotificationOptions object.

Get the values of Enable foreground push (foregroundEnabled), Enable badge (badgeEnabled), and Enable notification sound (soundEnabled) from the user. Then you can call the following API to set the notification option.

API

+ (void)registerPushWithPushConfiguration:(TCGBPushConfiguration *)configuration
                      notificationOptions:(nullable TCGBNotificationOptions *)notificationOptions
                               completion:(nullable void(^)(TCGBError * _Nullable error))completion;

TCGBNotificationOptions

Parameter Mandatory(M) /
Optional(O)
Values Description
foregroundEnabled M BOOL 앱이 포그라운드 상태일때의 알림 노출 여부
default: NO
badgeEnabled M BOOL 배지 아이콘 사용 여부
default: YES
soundEnabled M BOOL 알림음 사용 여부
default: YES

Example

- (void)didLoginSucceeded {
    BOOL enablePush;
    BOOL enableAdPush;
    BOOL enableAdNightPush;
    BOOL alwaysAllowTokenRegistration;

    BOOL foregroundEnabled;
    BOOL badgeEnabled;
    BOOL soundEnabled;

    // You should receive the above values to the logged-in user.

 TCGBNotificationOptions *options = [TCGBNotificationOptions notificationOptionsWithForegroundEnabled:foregroundEnabled 
                                                                                            badgeEnabled:badgeEnabled 
                                                                                            soundEnabled:soundEnabled];

    [TCGBPush registerPushWithPushConfiguration:pushConfig notificationOptions:options completion:^(TCGBError* error) {
        if (error != nil) {
            // To Register Push Failed.
        }
    }];
    // You should receive the above values to the logged-in user.
}

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 set the client
- (void)didLoginSucceeded {
    [TCGBPush setSandboxMode:YES];
    [TCGBPush registerPushWithPushConfiguration:pushConfig completion:^(TCGBError *error) {
        ...
    }];
}
  • Send push from Console

Select iOS Sandbox as the Target from the Push menu and send push.

Get NotificationOptions

Retrieve the notification option value which was set when registering for the push notification.

- (void)didLoginSucceeded {
    TCGBNotificationOptions *options = [TCGBPush notificationOptions];

    if (options == nil) {
        // You need to login and call the registerPush API first.
    }
}

[Note]

foregroundEnabled option can be changed at runtime. badgeEnabled and soundEnabled options are applied only when registerPush API gets called for the first time, and any changes to them at runtime are not guaranteed.

Query Token Info

To view the push settings of the user, the following API is used. You can get the push info registered with the TCGBPushTokenInfo value which comes as callback.

- (void)didLoginSucceeded {
    [TCGBPush queryTokenInfoWithCompletion:^(TCGBPushTokenInfo *tokenInfo, TCGBError *error) {
        if ([TCGBGamebase isSuccessWithError:error] == NO) {
            // To Request Push Token Info Failed.
        }

        NSString *pushType = tokenInfo.pushType;
        NSString *token = tokenInfo.token;
        ...
        // You can handle these variables.
    }];
}

TCGBPushTokenInfo

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
sandbox YES or NO Checks if the token is registered in the sandbox environment
agreement TCGBPushAgreement Opt in

TCGBPushAgreement

Parameter Values Description
pushEnabled YES or NO Opt in to display notifications
ADAgreement YES or NO Opt in to display advertisement notifications
ADAgreementNight YES or NO Opt in to display night advertisement notifications

Event Handling

Error Handling

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

TCGB_ERROR_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.
TCGBError *tcgbError = error; // TCGBError object via callback

NSInteger detailErrorCode = [error detailErrorCode];
NSString *detailErrorMessage = [error detailErrorMessage];
// If you use **description** method, you can get entire information of this object by JSON Format
NSLog(@"TCGBError: %@", [tcgbError description]);
  • The NHN Cloud Push error codes are as follows:
Error Code Description
NHNCloudPushErrorUnknown Unknown
NHNCloudPushErrorNotInitialized Not initialized
NHNCloudPushErrorUserInvalid User ID is not set
NHNCloudPushErrorPermissionDenied Failed to get permission
NHNCloudPushErrorSystemFailed System failed
NHNCloudPushErrorTokenInvalid Token value is empty or invalid
NHNCloudPushErrorAlreadyInProgress Already in progress
NHNCloudPushErrorParameterInvalid Invalid parameter
NHNCloudPushErrorNotSupported Not supported feature
NHNCloudPushErrorClientFailed Server error
TOP