Skip to content

Step 3. Issue and register tokens

On Android, device tokens for receiving remote push messages are issued through FCM (Firebase Cloud Messaging).

This document describes how to get a device token issued with the Hive Axyl FCM plugin and register it with the Hive Axyl push server.


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

※ Prerequisites: See the FCM Set up the integration page and complete these steps: install the FCM plugin, include the google-services.json file, and request runtime notification permission.

  1. Issue an FCM token
  2. Register the device token
  3. Handle token refresh

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

Note
  • The FCM plugin is for Android devices only. In other environments, including the Unity Editor, the port is not registered, so guard it with OS branching or HiveCore.TryResolve<T>().


1. Issue an FCM token

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

Method

public Task GetTokenAsync();


Gets the FCM token registered on the current device.

  • Each call queries the OS directly to fetch the latest token, and the plugin does not cache the token internally.
  • 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(), FcmServiceGetTokenResult, 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.

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

IFCMPlugin fcm = HiveCore.Resolve<IFCMPlugin>();

FcmServiceGetTokenResult result = await fcm.GetTokenAsync();

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

    // Handle common failures - for the detailed error model, see [Error handling](PLACEHOLDER_에러처리_링크)
    case FcmServiceGetTokenResult.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 Android device. In the Unity Editor or on unsupported OSs, the FCM port is not registered.
  • Before calling, complete HiveBootstrap.Initialize, and prepare the FCM integration environment and the notification permission request.
  • The token can change for reasons such as app installation, data deletion, or Firebase settings changes. Even after the first issuance, you must handle the token refresh event.


Response data

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

Field name Type Required Description
Data.Token string Required The issued FCM registration token.


Response status

The return object FcmServiceGetTokenResult 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 Firebase not being initialized (FailedPrecondition), missing Google Play services, network errors (Unavailable), and call cancellation (Cancelled). Retry or show an error message depending on the cause


2. Register the device token

Register the token issued by FCM with the Hive Axyl push server by calling the Register device tokens method. When you register on Android, set UpsertTokenRequest.ProviderType to Fcm.

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

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

var request = new UpsertTokenRequest {
    Token        = fcmToken,
    TimezoneId   = "Asia/Seoul",
    Country      = "KR",
    Language     = LanguageCode.Ko,
    ProviderType = UpsertTokenRequestProviderType.Fcm,
    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.


3. Handle token refresh

When the existing FCM token expires for reasons such as a change in the device's security state, an app data reset, or the passage of a certain period, and FCM issues a new token, 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.

fcm.TokenRefreshed += async newToken =>
{
    var result = await push.UpsertTokenAsync(new UpsertTokenRequest {
        Token        = newToken,
        ProviderType = UpsertTokenRequestProviderType.Fcm,
        // 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.
};


For reference: Delete tokens

Method

public Task DeleteTokenAsync();


Forcibly revokes the FCM registration token currently generated on the local device.

  • Internally, it works by calling FirebaseMessaging.deleteToken() of the Firebase FCM SDK.
  • When the token is successfully revoked, receiving push notifications with the existing token stops immediately. After that, FCM raises the TokenRefreshed event and issues a new device token again when the GetTokenAsync() method is next called or based on the system's internal decision.


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.


Response status

The return object FcmServiceDeleteTokenResult branches into the following cases. There is no response data on success.

Response case Description App client handling
Success The local token was revoked. Reissue and re-register if needed
Failure Token revocation failed. Identify the cause with Code of Problem (HiveError). This includes cases such as Firebase not being initialized (FailedPrecondition). Retry or show an error message depending on the cause


Next steps

Implement Step 4. Send remote push notifications.


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