Step 3. Issue and register tokens

On iOS, device tokens for receiving remote push messages are issued through APNs (Apple Push Notification service).

This document describes how to get a device token issued with the Hive Axyl APNs plugin, check the push environment, and then register the token with the Hive Axyl push server.

The steps to issue and register an APNs token are as follows.

※ Prerequisites: See the APNs Set up the integration page and complete installing the APNs plugin, requesting notification permission, and connecting the delegate code.

Issue an APNs token
Check the push environment
Register the device token
Handle token refresh

The APNs plugin handles only token issuance and event delivery. The app client itself performs server registration of the issued token, token storage, and notification permission requests.

Note

The simulator cannot issue APNs tokens. Check token issuance on a physical iOS device.
If the delegate does not call the Notify* methods, GetTokenAsync() does not complete.

1. Issue an APNs token

Get the plugin instance with HiveCore.Resolve<IAPNSPlugin>() after you register AddAPNS() during SDK initialization. You must complete HiveBootstrap.Initialize first.

public Task GetTokenAsync();

Gets the APNs device token registered on the current device.

Requests remote notification registration (UIApplication.registerForRemoteNotifications) from the OS.
The call completes when the app's delegate forwards the OS callback to NotifyDidRegisterForRemoteNotificationsAsync().
The issued token is included in the final push message recipients only after you register it with the Hive Axyl push server by calling the Register device tokens method.

Call parameters

Field name	Type	Required	Description
`ct`	CancellationToken	Optional	The cancellation token used to cancel the call. If omitted, the default value is used.

Call example

The return object of GetTokenAsync(), ApnsServiceGetTokenResult, is divided into success and failure states. The method call does not throw exceptions (Exception), and all processing results are delivered through the return object. Therefore, instead of using a separate try/catch statement, branch on the response status with a switch statement.

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Push.Addon.APNS;

IAPNSPlugin apns = HiveCore.Resolve<IAPNSPlugin>();

ApnsServiceGetTokenResult result = await apns.GetTokenAsync();

switch (result)
{
    case ApnsServiceGetTokenResult.Success success:
        string apnsToken = success.Data.Token;   // Lowercase hexadecimal string
        // Register the issued token with the Axyl server.
        break;

    // Handle common failures - for the detailed error model, see [Error handling](PLACEHOLDER_에러처리_링크)
    case ApnsServiceGetTokenResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // Safety net: unknown new results
    default:
        Debug.LogWarning($"Unhandled result: {result.GetType().Name}");
        break;
}

Considerations when calling

Call GetTokenAsync() on a physical iOS device. The simulator cannot issue APNs tokens.
Before calling, complete HiveBootstrap.Initialize, and prepare the APNs integration environment and the notification permission request.
The app delegate must forward the OS registration result to the plugin's Notify* methods.
The token can change for reasons such as app installation, provisioning information changes, or OS decisions. Even after the first issuance, you must handle the token refresh event.

Response data

On success, Data of ApnsServiceGetTokenResult.Success contains the issued token.

Field name	Type	Required	Description
`Data.Token`	string	Required	The issued APNs device token. It is returned as a lowercase hexadecimal string.

Response status

The return object ApnsServiceGetTokenResult branches into the following cases. Handle it with a switch statement.

Response case	Description	App client handling
`Success`	Token issuance succeeded. `Data.Token` contains the token value.	Register the token with the Hive Axyl server
`Failure`	Token issuance failed. Identify the cause with `Code` of `Problem` (`HiveError`). This includes the simulator or an OS registration failure (`Unavailable`), the Push Notifications capability not being enabled (`FailedPrecondition`), and call cancellation (`Cancelled`).	Retry or show an error message depending on the cause

2. Check the push environment

APNs tokens are separated into development and production environments, so before you register a token, you must check the push environment that the current build uses.

public Task GetProviderEnvironmentAsync();

Checks the push environment by reading the build's aps-environment entitlement. It returns ApnsSandbox for a development (sandbox) build and Apns for a production build. Because the environment is determined at build time, you do not need to check it again even when the token is refreshed.

Call parameters

Field name	Type	Required	Description
`ct`	CancellationToken	Optional	The cancellation token used to cancel the call. If omitted, the default value is used.

Call example

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Push;
using Hive.Axyl.Push.Addon.APNS;

ApnsServiceGetProviderEnvironmentResult result = await apns.GetProviderEnvironmentAsync();

switch (result)
{
    case ApnsServiceGetProviderEnvironmentResult.Success success:
        UpsertTokenRequestProviderType providerType =
            success.Data.Environment == ProviderEnvironment.Apns
                ? UpsertTokenRequestProviderType.Apns
                : UpsertTokenRequestProviderType.ApnsSandbox;
        break;

    // Handle common failures - for the detailed error model, see [Error handling](PLACEHOLDER_에러처리_링크)
    case ApnsServiceGetProviderEnvironmentResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // Safety net: unknown new results
    default:
        Debug.LogWarning($"Unhandled result: {result.GetType().Name}");
        break;
}

Considerations when calling

Use GetProviderEnvironmentAsync() to decide the ProviderType of the token registration request.
In a build where the Push Notifications capability is not enabled, the environment check can fail.
Development builds and release builds use different APNs environments, so check the Hive Console settings and the build configuration together.

Response data

On success, Data of ApnsServiceGetProviderEnvironmentResult.Success contains the environment value.

Field name	Type	Required	Description
`Data.Environment`	ProviderEnvironment	Required	The push environment. It is `Apns` (production) or `ApnsSandbox` (development).

Response status

The return object ApnsServiceGetProviderEnvironmentResult branches into the following cases. Handle it with a switch statement.

Response case	Description	App client handling
`Success`	The environment check succeeded.	Use it to decide `ProviderType`
`Failure`	The check failed. In a build where the Push Notifications capability is not enabled, it fails with the `FailedPrecondition` code.	Check Set up the integration

3. Register the device token

Register the token issued by APNs with the Hive Axyl push server by calling the Register device tokens method. When you register on iOS, set UpsertTokenRequest.ProviderType to Apns or ApnsSandbox according to the result of GetProviderEnvironmentAsync().

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Push;

IPushService push = HiveCore.Resolve<IPushService>();

var request = new UpsertTokenRequest {
    Token        = apnsToken,
    TimezoneId   = "Asia/Seoul",
    Country      = "KR",
    Language     = LanguageCode.Ko,
    ProviderType = providerType,
    Agreement    = new Agreement {
        Info      = true,
        Advertise = false,
        Night     = false,
    },
    EventType    = "LOGIN",
};

PushUpsertTokenResult result = await push.UpsertTokenAsync(request);

For the registration request parameters and response status, see Register device tokens.

4. Handle token refresh

Every time the delegate calls NotifyDidRegisterForRemoteNotificationsAsync(), including the first issuance, the TokenRefreshed event occurs. The Hive Axyl SDK does not automatically register the new token with the Hive Axyl server, so the app client must always subscribe to this event and call the Register device tokens method again as soon as it receives a new token. The event is delivered on the engine main thread.

Unity

apns.TokenRefreshed += async newToken =>
{
    var result = await push.UpsertTokenAsync(new UpsertTokenRequest {
        Token        = newToken,
        ProviderType = providerType,
        // Fill in the remaining fields with the same values as the first registration.
    });
    // Branch on the response status the same way as in the [Register device tokens] document.
};

You can also receive the first issued token as the result of GetTokenAsync(), so register it from only one path to avoid registering the same token twice. Because the push environment is determined at build time, you do not need to check it again even when the token is refreshed.

For reference: Delegate callback forwarding methods

These are the methods through which the app's delegate forwards the OS registration result to the plugin. Call them inside the callbacks you connected in Prepare delegate code.

NotifyDidRegisterForRemoteNotificationsAsync(byte[] deviceToken): Forwards the original token bytes as is from the application(_:didRegisterForRemoteNotificationsWithDeviceToken:) callback. The pending GetTokenAsync() completes, and the TokenRefreshed event occurs.
NotifyDidFailToRegisterAsync(string errorDescription): Forwards the error description from the application(_:didFailToRegisterForRemoteNotificationsWithError:) callback. The pending GetTokenAsync() completes with a Failure with the Unavailable code.

Neither method returns response data on success. The return objects (ApnsServiceNotifyDidRegisterForRemoteNotificationsResult/ApnsServiceNotifyDidFailToRegisterResult) branch into Success/Failure.

Next steps

Implement Step 4. Send remote push notifications.

The following documents are related to the content of this document.

Step 3. Issue and register tokens

1. Issue an APNs token

Call parameters

Call example

Considerations when calling

Response data

Response status

2. Check the push environment

Call parameters

Call example

Considerations when calling

Response data

Response status

3. Register the device token

4. Handle token refresh

For reference: Delegate callback forwarding methods

Next steps

Related documents