Implement Apple Push Notification Service

To receive remote push notifications on iOS, 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	Prepare the Push Notifications capability and an APNs key in Apple Developer
2	Hive Console	Register APNs sending information
3	Hive Axyl SDK, OS plugin	Install and register the push module and the APNs plugin
4	App code	Connect APNs delegate callbacks
5	Recipe code	Copy the recipe folders
6	App code	Create a `PushPreparation`
7	Recipe code	Request notification permission, check the APNs environment, issue an APNs token, and register it with the Hive Axyl server
8	App code, Recipe code	Handle token refresh events
9	OS plugin, App code	Handle received notifications and cold starts
10	Hive Console, Hive Axyl Server API	Send remote push notifications

Do not set the APNs environment arbitrarily

Development-signed builds use APNs sandbox tokens, and distribution builds use APNs production tokens. The recipe reads the build's aps-environment value to decide the registration value. Do not arbitrarily hard-code Apns or ApnsSandbox in your app code.

1. Configure Apple Developer

External console Configure this in Apple Developer.

Detailed procedure: App Store push notification integration, Set up the APNs integration

Enable the Push Notifications capability in Apple Developer, and prepare the key information to use for sending through APNs.

After you change the capability, you must renew the Provisioning Profile. If you do not use Xcode automatic signing, download the renewed profile yourself and apply it to your build.

2. Configure the Hive Console

Hive Console Configure this in the Hive Console.

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

Setting	Required	Where to check
APNs certificate file	Required	App Store push notification integration
Key ID	Required	App Store push notification integration
Team ID	Required	App Store push notification integration

Even if token registration succeeds in the app, actual push sending can fail if the APNs 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 APNs integration

Install the push module and the APNs 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.apns`	APNs token issuance, APNs environment check, token refresh events, and received notification events
`com.unity.mobile.notifications`	iOS notification permission requests

The following example code registers the push module and the APNs 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.APNS;

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

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

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

4. Prepare the APNs delegate code

App code Implement this in the app.

Detailed procedure: Set up the APNs integration, Issue and register APNs tokens

The APNs plugin does not install the app's UIApplicationDelegate or UNUserNotificationCenterDelegate on its behalf. The app delegate must forward OS callbacks to the plugin's Notify* methods.

OS delegate callback	Plugin method to call
`application(_:didRegisterForRemoteNotificationsWithDeviceToken:)`	`NotifyDidRegisterForRemoteNotificationsAsync(deviceToken)`
`application(_:didFailToRegisterForRemoteNotificationsWithError:)`	`NotifyDidFailToRegisterAsync(errorDescription)`
`userNotificationCenter(_:willPresent:withCompletionHandler:)`	`NotifyWillPresentNotificationAsync(notification)`
`userNotificationCenter(_:didReceive:withCompletionHandler:)`	`NotifyDidReceiveResponseAsync(notification, actionIdentifier)`
Cold start launch options or the initial notification response	`NotifyColdStartNotificationAsync(userInfoJson)`

If you do not connect the delegate callbacks, the APNs token issuance call does not complete, and reception events are not delivered to the app either.

5. 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.Apns/	Code for Apple APNs permission requests, APNs environment checks, 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.Apns to references in your app's assembly definition.

Excluded from the build without the APNs plugin

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

6. 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.

7. Register the APNs token

Recipe code Call the recipe code from the app.

After login completes, call PrepareAsync(). This single method checks or requests iOS notification permission, checks the build's APNs environment, gets an APNs token issued, and registers the token and notification consent values with the Hive Axyl server.

Unity

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

CancellationToken cancellationToken = default;
Action restoreNotificationDelegate = () =>
{
    // Reinstall the APNs delegate forwarder that the app uses.
};
using IPushTokenSource source = new ApnsPushTokenSource();
var recipe = new PushRecipe(source);

PreparePushOutcome prepared;
try
{
    prepared = await recipe.PrepareAsync(preparation, cancellationToken);
}
finally
{
    restoreNotificationDelegate();
}

switch (prepared.Status)
{
    case PreparePushStatus.Success:
        // You can check whether prepared.Provider is Apns or ApnsSandbox.
        break;

    case PreparePushStatus.PermissionDenied:
        // 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	Check or request iOS notification permission	Set up the APNs integration
OS plugin	Check the APNs environment with `GetProviderEnvironmentAsync()`	Issue and register APNs tokens
OS plugin	Issue an APNs token with `GetTokenAsync()`	Issue and register APNs tokens
Hive Axyl SDK	Register the token and notification consent with `UpsertTokenAsync()`	Register device tokens

When Unity Mobile Notifications requests iOS notification permission, the notification center delegate may switch to the Unity side. If the app uses an APNs delegate forwarder, reinstall the forwarder in a finally block regardless of whether the recipe call ends in success, failure, or cancellation. recipes/Notifications/PushPreparationExample.cs provides an example that receives this restore callback.

8. Handle token refresh

App code Implement this in the app.

Recipe code Call the recipe code from the app.

When APNs 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.

9. Handle push reception

OS plugin Call the OS plugin from the app.

App code Implement this in the app.

Detailed procedure: Push reception handling (iOS)

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

The app interprets UserInfoJson of received notifications to implement actions such as screen navigation, state updates, and event handling.

10. 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 Android as well, see Implement Google Firebase Cloud Messaging. For a local notification example based on Unity Mobile Notifications, see Use the Notifications example.