Implement Google Firebase Cloud Messaging

To receive remote push notifications on Android, complete the following procedure in order.

Before you begin, complete the common prerequisites.

Overall flow

What you set up and call in each step is as follows.

Step	Category	What you do
1	External console	Set up the FCM project and the Android app in the Firebase console
2	Hive Console	Register FCM sending information
3	Hive Axyl SDK, OS plugin	Install and register the push module and the FCM plugin
4	Recipe code	Copy the recipe folders
5	App code	Create a `PushPreparation`
6	Recipe code	Request notification permission, issue an FCM token, and register it with the Hive Axyl server
7	App code, Recipe code	Handle token refresh events
8	OS plugin, App code	Handle received messages and cold starts
9	Hive Console, Hive Axyl Server API	Send remote push notifications

Pass the latest notification consent values from your app's policy

The recipe registers the notification consent values it receives with the Hive Axyl server as they are. If the user changed consent to advertising notifications or nighttime advertising notifications, register again with the changed values at the next registration.

1. Configure the Firebase console

External console Configure this in the Firebase console.

Detailed procedure: Google Play push notification integration, Set up the FCM integration

Prepare the project that will use FCM and the Android app in the Firebase console. Also download the google-services.json file to include in your app build.

You must include the google-services.json file in the app module location. Without this file, Firebase is not initialized, and FCM token issuance fails.

2. Configure the Hive Console

Hive Console Configure this in the Hive Console.

Register the FCM sending information you prepared in step 1 in the Hive Console.

Setting	Required	Where to check
Project ID	Required	Google Play push notification integration
Service Key file	Required	Google Play push notification integration

Even if token registration succeeds in the app, actual push sending can fail if the FCM sending information in the Hive Console is incorrect.

3. Prepare SDK modules and plugins

Hive Axyl SDK Call the Hive Axyl SDK from the app.

OS plugin Call the OS plugin from the app.

Detailed procedure: Install and initialize the push module, Set up the FCM integration

Install the push module and the FCM plugin, and then register them when you initialize the SDK.

Package	Role
`com.hive.axyl.core`	SDK initialization and common features
`com.hive.axyl.auth`	Login session required for token registration
`com.hive.axyl.push`	Device token registration with the Hive Axyl server
`com.com2usplatform.hiveaxyl.push.addon.fcm`	FCM token issuance, token refresh events, and received message events

The following example code registers the push module and the FCM plugin when initializing the SDK.

Unity

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

var config = CoreConfig.CreateBuilder("{appId}")
    .SetZone(Zone.Sandbox)
    .Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAuth();
    builder.AddPush();
    builder.AddFCM();
});

If you do not register AddPush(), the recipe fails with a FailedPrecondition error. If you do not register AddFCM(), the FCM token source cannot get a token issued.

4. Install the recipe code

Recipe code Copy the recipe code into your project.

A recipe is source code that you copy into your project instead of installing as a package. Copy the following items to Assets/Recipes/ in your Unity project.

Item to copy	Role
Recipes.asmdef	Common assembly definition
Helper/	Common code shared by multiple recipes
Push/	`PushRecipe`, `PushPreparation`, and result types
Push.Fcm/	Code for Android FCM permission requests and token issuance

To call recipes from your app code, add Hive.Axyl.Samples.Recipes, Hive.Axyl.Samples.Recipes.Push, and Hive.Axyl.Samples.Recipes.Push.Fcm to references in your app's assembly definition.

Excluded from the build without the FCM plugin

The assembly definition in Push.Fcm/ compiles only when the FCM plugin package is installed. Even if you do not install the plugin, the common push recipe remains, and only the FCM token source assembly is excluded from the build.

5. Create a PushPreparation

App code Implement this in the app.

PushPreparation is a recipe type that holds the conditions and notification consent values with which to register this device.

Unity

using Hive.Axyl.Samples.Recipes;

var preparation = new PushPreparation(
    language: "ko",
    country: "KR",
    timezoneId: "Asia/Seoul",
    agreedToInfo: true,
    agreedToAdvertising: false,
    agreedToNightAdvertising: false,
    serverId: "KR-01",
    appVersion: Application.version);

Pass language as a language code that the Hive Axyl server supports. Pass country in ISO 3166-1 alpha-2 format, and pass timezoneId as an IANA time zone name.

You can set agreedToNightAdvertising to true only when agreedToAdvertising is true. If the combination is invalid, the recipe returns a failure before calling the server.

6. Register the FCM token

Recipe code Call the recipe code from the app.

After login completes, call PrepareAsync(). This single method checks or requests Android notification permission, gets an FCM token issued, and registers the token and notification consent values with the Hive Axyl server.

Unity

using System.Threading;
using Hive.Axyl.Samples.Recipes;

CancellationToken cancellationToken = default;
using IPushTokenSource source = new FcmPushTokenSource();
var recipe = new PushRecipe(source);

PreparePushOutcome prepared = await recipe.PrepareAsync(preparation, cancellationToken);

switch (prepared.Status)
{
    case PreparePushStatus.Success:
        // Do not write prepared.DeviceToken to logs as is; mask it.
        break;

    case PreparePushStatus.PermissionDenied:
        // On Android 13 or later, notification permission was not granted, so the token was not registered.
        break;

    case PreparePushStatus.BusinessOutcome:
        Debug.LogWarning($"{prepared.FailedStep}: {prepared.BusinessOutcome}");
        break;

    case PreparePushStatus.Failure:
        Debug.LogError($"{prepared.FailedStep}: {prepared.Error?.Message}");
        break;
}

The recipe performs the following tasks internally.

Category	Call	Where to check
OS plugin	Request the `POST_NOTIFICATIONS` permission on Android 13 or later	Set up the FCM integration
OS plugin	Issue an FCM token with `GetTokenAsync()`	Issue and register FCM tokens
Hive Axyl SDK	Register the token and notification consent with `UpsertTokenAsync()`	Register device tokens

Android 12 and earlier do not have the POST_NOTIFICATIONS permission, so the recipe skips the permission request and proceeds. On Android 13 or later, if the user does not grant notification permission, the recipe returns PermissionDenied and does not register the token.

7. Handle token refresh

App code Implement this in the app.

Recipe code Call the recipe code from the app.

When FCM issues a new token, the app must register the new token with the Hive Axyl server again. The recipe does not own the TokenRefreshed event itself, so have the owner of the app's lifecycle subscribe to the event and serialize the registration calls.

Unity

string latestRefreshToken = null;

source.TokenRefreshed += refreshed =>
{
    latestRefreshToken = refreshed;
};

PreparePushOutcome prepared = await recipe.PrepareAsync(preparation, cancellationToken);

if (prepared.Status == PreparePushStatus.Success
    && !string.IsNullOrEmpty(latestRefreshToken)
    && latestRefreshToken != prepared.DeviceToken)
{
    prepared = await recipe.PrepareAsync(preparation, cancellationToken);
}

Do not run multiple registrations at the same time. After a registration succeeds, register once more only if the latest event token differs from the token you just registered.

8. Handle push reception

OS plugin Call the OS plugin from the app.

App code Implement this in the app.

Detailed procedure: Push reception handling (Android)

The recipe only registers the token; it does not display arriving push messages on the screen or handle cases where a notification tap opened the app. After registering the token, implement FCM reception handling.

The app interprets the custom data of received messages to implement actions such as screen navigation, state updates, and event handling.

9. Send remote push notifications

Hive Console Send remote push notifications from the Hive Console.

Hive Axyl Server API Call the Hive Axyl Server API from the app server.

Detailed procedure: Send remote push notifications

Remote push messages are sent from the Hive Console or with the Hive Axyl Server API. The app client is not the sender.

Campaign recipient filters use the language, country, time zone, and notification consent values passed at token registration.

Next steps

To implement remote push notifications on iOS as well, see Implement Apple Push Notification Service. For a local notification example based on Unity Mobile Notifications, see Use the Notifications example.