Apple Push Notification service 푸시 알림 Add-on

iOS와 macOS에서 Apple Push Notification service(APNs)로 원격 푸시 알림을 받는 Add-on입니다. Apple UserNotifications 프레임워크의 UNUserNotificationCenter와 원격 알림 등록 기능을 감싸 알림 권한 요청, 디바이스 토큰 발급, APNs 환경 확인, 앱 아이콘 배지 설정, 앱을 실행시킨 알림 조회를 제공합니다. 알림 내용은 가공하지 않고 OS가 전달한 값을 그대로 전달합니다.

Add-on은 발급받은 토큰을 Hive Axyl 서버에 등록하지 않습니다. 토큰은 Push 모듈의 UpsertTokenAsync로 등록하고, ProviderType에는 GetProviderEnvironmentAsync()로 확인한 환경을 지정하세요.

모듈 정보

항목	값
패키지	`com.com2usplatform.hiveaxyl.push.addon.apns`
인터페이스	`IAPNSPlugin`
네임스페이스	`Hive.Axyl.Push.Addon.APNS`
등록 메서드	`AddAPNS()`
지원 플랫폼	iOS, macOS
최소 사양	iOS 17+, macOS 15+, Unity 6000.0+

사전 준비

이 Add-on을 설치하면 빌드할 때 생성되는 Xcode 프로젝트에 Push Notifications 기능과 APNs 환경 엔타이틀먼트가 자동으로 추가됩니다. 엔타이틀먼트는 앱이 사용할 Apple 기능을 서명에 선언하는 값입니다. Development Build로 빌드하면 샌드박스 환경을, 릴리스 빌드로 빌드하면 운영 환경을 사용합니다. macOS에서는 Xcode 프로젝트를 생성하도록 빌드해야 엔타이틀먼트가 추가됩니다. 하지만 Apple Developer에서 App ID의 Push Notifications 기능을 활성화하고 그에 맞는 프로비저닝 프로파일을 발급하는 작업은 직접 해야 합니다.

델리게이트는 원격 알림 등록 결과나 알림 도착 같은 이벤트가 생겼을 때 OS가 호출하는 앱의 객체입니다. Add-on은 iOS의 UIApplicationDelegate, macOS의 NSApplicationDelegate, UNUserNotificationCenterDelegate 같은 앱의 델리게이트를 설치하거나 대신하지 않습니다. 앱의 델리게이트가 OS 콜백을 OS 콜백 전달 메서드로 넘겨야 디바이스 토큰 발급이 완료되고 알림 이벤트가 발생합니다.

등록과 획득

HiveBootstrap.Initialize의 등록 단계에서 Push 모듈과 함께 등록한 뒤 HiveCore.TryResolve<T>()로 가져옵니다.

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Push;
using Hive.Axyl.Push.Addon.APNS;

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

if (HiveCore.TryResolve<IAPNSPlugin>(out var apns))
{
    // iOS · macOS 빌드에서만 실행되는 코드
}

Unity 에디터에서는 등록되지 않습니다

이 Add-on은 iOS 또는 macOS로 빌드한 플레이어에서만 등록됩니다. Unity 에디터에서는 플랫폼이 맞아도 등록되지 않으므로, HiveCore.Resolve<T>()를 쓰면 RegistrationNotFoundException이 발생합니다. 반드시 TryResolve<T>()로 확인한 뒤 사용하세요.

메서드 요약

모든 메서드는 마지막 파라미터로 CancellationToken ct = default를 받습니다. 호출 규약은 호출 컨텍스트를 참조하세요.

메서드	설명
RequestAuthorizationAsync()	알림 권한을 요청합니다.
GetNotificationSettingsAsync()	현재 알림 권한 상태를 조회합니다.
GetTokenAsync()	APNs 디바이스 토큰을 발급받습니다.
GetProviderEnvironmentAsync()	앱이 사용하는 APNs 환경을 확인합니다.
GetColdStartNotificationAsync()	앱을 실행시킨 알림을 조회합니다.
SetBadgeCountAsync()	앱 아이콘 배지 숫자를 설정합니다.

앱의 델리게이트가 OS 콜백을 넘길 때 호출하는 메서드는 OS 콜백 전달 메서드에서 따로 설명합니다.

메서드

RequestAuthorizationAsync

UNUserNotificationCenter.requestAuthorization(options:)로 알림 권한을 요청합니다. 시스템 권한 대화 상자는 처음 호출할 때만 표시되고, 이후에는 앱 사용자가 이전에 선택한 결과를 반환합니다.

앱 사용자가 권한을 거부하면 Failure가 아니라 Data.Granted가 false인 Success가 반환됩니다. macOS는 앱의 알림이 꺼진 뒤부터 권한 요청을 오류로 끝내지만, Add-on이 이 경우도 Granted가 false인 Success로 반환해 두 플랫폼의 결과를 맞춥니다. 거부 여부는 Granted로 판단하고, 알림 권한 상태가 필요하면 GetNotificationSettingsAsync()를 호출하세요.

알림 권한은 앱 전체에 하나이므로 Apple 로컬 푸시 알림 Add-on과 공유합니다. 두 Add-on 중 어느 쪽으로 권한을 받아도 양쪽에 적용됩니다.

Unity

Task<ApnsServiceRequestAuthorizationResult> RequestAuthorizationAsync(IReadOnlyList<UNAuthorizationOption> options, CancellationToken ct = default)

파라미터	타입	필수 여부	설명
`options`	IReadOnlyList<UNAuthorizationOption>	Required	요청할 권한 옵션 목록입니다. 빈 목록이면 아무 옵션도 요청하지 않습니다.

항목	값
응답	APNSServiceRequestAuthorizationResponse

결과 케이스 — ApnsServiceRequestAuthorizationResult

결과 케이스	와이어 코드	설명
`Success`	—	권한 요청을 마쳤습니다. 허용 여부는 `Data.Granted`에서 확인합니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

발생 예외

예외	발생 조건
`ArgumentNullException`	`options`가 `null`인 경우

GetNotificationSettingsAsync

getNotificationSettings로 현재 알림 권한 상태를 조회합니다. Add-on은 상태를 해석하지 않고 UNAuthorizationStatus 값을 그대로 반환하므로, 예를 들어 Denied일 때 앱 사용자를 설정 앱으로 안내할지는 앱이 결정합니다.

Unity

Task<ApnsServiceGetNotificationSettingsResult> GetNotificationSettingsAsync(CancellationToken ct = default)

항목	값
응답	APNSServiceGetNotificationSettingsResponse

결과 케이스 — ApnsServiceGetNotificationSettingsResult

결과 케이스	와이어 코드	설명
`Success`	—	조회에 성공했습니다. 권한 상태는 `Data.AuthorizationStatus`에서 확인합니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

GetTokenAsync

원격 알림 등록을 시작하고 APNs가 발급한 디바이스 토큰을 소문자 16진수 문자열로 반환합니다. 등록 결과는 앱의 델리게이트가 NotifyDidRegisterForRemoteNotificationsAsync() 또는 NotifyDidFailToRegisterAsync()로 전달할 때 돌아오므로, 델리게이트가 두 메서드 중 하나를 호출하지 않으면 GetTokenAsync()가 끝나지 않습니다.

Add-on은 토큰을 저장하지 않으므로 호출할 때마다 OS에 원격 알림 등록을 요청합니다. 토큰을 받으면 TokenRefreshed 이벤트도 함께 발생합니다. 결과를 기다리는 중에 다시 호출하면 이전 호출은 Code가 Cancelled인 Failure로 끝납니다.

Unity

Task<ApnsServiceGetTokenResult> GetTokenAsync(CancellationToken ct = default)

항목	값
응답	APNSServiceGetTokenResponse

결과 케이스 — ApnsServiceGetTokenResult

결과 케이스	와이어 코드	설명
`Success`	—	토큰을 발급받았습니다. 토큰은 `Data.Token`에 담깁니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

Failure의 원인은 Problem.Code로 구분합니다.

`Problem.Code`	원인
`Unavailable`	시뮬레이터에서 호출했거나, 델리게이트가 NotifyDidFailToRegisterAsync()로 등록 실패를 전달했습니다. 이 Add-on은 시뮬레이터에서 토큰을 발급하지 않으므로 실제 기기에서 확인하세요.
`FailedPrecondition`	Push Notifications 기능이 켜지지 않아 APNs 환경 엔타이틀먼트가 없습니다.
`Cancelled`	`CancellationToken`으로 취소했거나, 결과를 기다리는 중에 `GetTokenAsync()`를 다시 호출했습니다.

호출 예시

토큰을 등록하려면 토큰과 함께 APNs 환경이 필요합니다. GetProviderEnvironmentAsync()로 확인한 환경을 Push 모듈의 제공자 열거형으로 바꿔 UpsertTokenAsync에 넘깁니다.

Unity

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

// push: HiveCore.Resolve<IPushService>()로 가져온 IPushService
var tokenResult = await apns.GetTokenAsync();
var environmentResult = await apns.GetProviderEnvironmentAsync();

if (tokenResult is ApnsServiceGetTokenResult.Success token
    && environmentResult is ApnsServiceGetProviderEnvironmentResult.Success environment)
{
    var providerType = environment.Data.Environment == ProviderEnvironment.ApnsSandbox
        ? UpsertTokenRequestProviderType.ApnsSandbox
        : UpsertTokenRequestProviderType.Apns;

    var result = await push.UpsertTokenAsync(new UpsertTokenRequest
    {
        Token        = token.Data.Token,
        ProviderType = providerType,
        // TimezoneId, Country, Language, Agreement도 함께 지정합니다.
    });
}

GetProviderEnvironmentAsync

앱에 서명된 APNs 환경 엔타이틀먼트인 aps-environment를 읽어 앱이 사용하는 APNs 환경을 반환합니다. 값이 development이면 ApnsSandbox, production이면 Apns입니다. Push Notifications 기능이 켜지지 않아 엔타이틀먼트가 없으면 Code가 FailedPrecondition인 Failure를 반환합니다.

iOS에서는 앱에 포함된 프로비저닝 프로파일에서 이 값을 읽습니다. App Store나 TestFlight로 설치한 앱에는 프로비저닝 프로파일이 포함되지 않으므로 항상 운영 환경인 Apns를 반환합니다.

반환한 환경에 맞춰 UpsertTokenRequest.ProviderType을 지정하세요.

`Data.Environment`	`ProviderType`에 지정할 값
`ProviderEnvironment.Apns`	`UpsertTokenRequestProviderType.Apns`
`ProviderEnvironment.ApnsSandbox`	`UpsertTokenRequestProviderType.ApnsSandbox`

Unity

Task<ApnsServiceGetProviderEnvironmentResult> GetProviderEnvironmentAsync(CancellationToken ct = default)

항목	값
응답	APNSServiceGetProviderEnvironmentResponse

결과 케이스 — ApnsServiceGetProviderEnvironmentResult

결과 케이스	와이어 코드	설명
`Success`	—	조회에 성공했습니다. 환경은 `Data.Environment`에 담깁니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

GetColdStartNotificationAsync

앱이 종료된 상태에서 앱 사용자가 원격 푸시 알림을 탭해 앱이 실행된 경우, 그 알림을 반환합니다. 앱의 델리게이트가 앱 시작 시점에 NotifyColdStartNotificationAsync()로 알림을 전달해 두면 Add-on이 알림을 보관하며, 보관한 알림은 한 번 반환하면 비워집니다. 앱을 실행할 때마다 NotifyColdStartNotificationAsync()가 끝난 뒤 한 번 호출하세요.

반환하는 알림은 알림의 원본 페이로드로 만들므로 InterruptionLevel, RelevanceScore, LaunchImageName은 기본값입니다. 이 값들의 원본은 UserInfoJson의 aps 딕셔너리에서 확인하세요.

반환할 알림이 없어도 Data.Notification은 null이 아니라 모든 필드가 기본값인 빈 알림입니다. 알림이 있는지는 Data.Notification.UserInfoJson이 비어 있지 않은지로 확인하세요. 아래 경우에는 빈 알림이 반환됩니다.

알림을 탭하지 않은 일반 실행
알림을 이미 반환한 뒤의 호출
NotifyColdStartNotificationAsync()가 끝나기 전의 호출
앱을 실행시킨 알림을 델리게이트가 전달하지 않은 실행

Unity

Task<ApnsServiceGetColdStartNotificationResult> GetColdStartNotificationAsync(CancellationToken ct = default)

항목	값
응답	APNSServiceGetColdStartNotificationResponse

결과 케이스 — ApnsServiceGetColdStartNotificationResult

결과 케이스	와이어 코드	설명
`Success`	—	조회에 성공했습니다. 앱을 실행시킨 알림이 없으면 `Data.Notification`은 빈 알림입니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

호출 예시

Unity

using Hive.Axyl.Push.Addon.APNS;

var result = await apns.GetColdStartNotificationAsync();

if (result is ApnsServiceGetColdStartNotificationResult.Success success
    && !string.IsNullOrEmpty(success.Data.Notification.UserInfoJson))
{
    ApnsNotification launchNotification = success.Data.Notification;   // 앱을 실행시킨 알림
}

SetBadgeCountAsync

UNUserNotificationCenter.setBadgeCount(_:)로 앱 아이콘 배지 숫자를 설정합니다. 0을 지정하면 배지를 지웁니다. 앱 사용자가 알림을 탭해도 배지는 지워지지 않으므로, 배지를 지울 시점에 0으로 호출하세요.

앱 아이콘 배지는 앱 전체에 하나이므로 Apple 로컬 푸시 알림 Add-on과 공유합니다. 알림에 담긴 ApnsNotification.Badge 값과 별개로, 이 메서드는 현재 앱 아이콘 배지를 바로 바꿉니다.

Unity

Task<ApnsServiceSetBadgeCountResult> SetBadgeCountAsync(int count, CancellationToken ct = default)

파라미터	타입	필수 여부	설명
`count`	`int`	Required	앱 아이콘에 표시할 배지 숫자입니다. `0`이면 배지를 지웁니다. SDK는 값을 검증하지 않고 OS에 그대로 전달하며, 음수를 넣었을 때의 OS 동작은 정해져 있지 않으므로 0 이상의 값을 넣으세요.

항목	값
응답	APNSServiceSetBadgeCountResponse

결과 케이스 — ApnsServiceSetBadgeCountResult

결과 케이스	와이어 코드	설명
`Success`	—	배지를 설정했습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

OS 콜백 전달 메서드

앱의 델리게이트가 iOS와 macOS의 알림 콜백을 Add-on에 넘길 때 호출하는 메서드입니다. Add-on은 앱의 델리게이트를 설치하거나 가로채지 않으므로, 델리게이트가 이 메서드를 호출해야 GetTokenAsync()가 완료되고 이벤트가 발생합니다. 각 메서드는 아래 표의 콜백에서 호출합니다.

호출 시점	메서드	호출 결과
`application(_:didRegisterForRemoteNotificationsWithDeviceToken:)`	NotifyDidRegisterForRemoteNotificationsAsync()	기다리던 `GetTokenAsync()`가 토큰을 반환하고 TokenRefreshed 이벤트가 발생합니다.
`application(_:didFailToRegisterForRemoteNotificationsWithError:)`	NotifyDidFailToRegisterAsync()	기다리던 `GetTokenAsync()`가 `Code`가 `Unavailable`인 `Failure`로 끝납니다.
`userNotificationCenter(_:willPresent:withCompletionHandler:)`	NotifyWillPresentNotificationAsync()	NotificationPresented 이벤트가 발생합니다.
`userNotificationCenter(_:didReceive:withCompletionHandler:)`	NotifyDidReceiveResponseAsync()	NotificationOpened 이벤트가 발생합니다.
앱을 실행시킨 알림을 앱 시작 시점에 확인했을 때	NotifyColdStartNotificationAsync()	GetColdStartNotificationAsync()가 반환할 알림이 준비됩니다.

Add-on은 넘겨받은 알림이 원격 푸시 알림인지 확인하지 않습니다. 앱의 델리게이트 하나가 원격 푸시 알림과 로컬 푸시 알림을 모두 받으므로, 요청의 트리거가 UNPushNotificationTrigger인 알림만 NotifyWillPresentNotificationAsync()와 NotifyDidReceiveResponseAsync()로 넘기세요. 로컬 푸시 알림을 넘기면 로컬 알림에도 NotificationPresented와 NotificationOpened 이벤트가 발생합니다. macOS의 로컬 푸시 알림은 Apple 로컬 푸시 알림 Add-on으로 넘깁니다.

Unity Mobile Notifications 패키지를 함께 쓰는 경우

iOS에서 Unity Mobile Notifications 패키지는 알림 권한을 요청할 때 UNUserNotificationCenter의 델리게이트를 자신의 델리게이트로 바꾸고, 기존 델리게이트를 보관하지 않습니다. OS 권한 대화 상자가 처음 표시되는 권한 요청에서 앱의 델리게이트가 이렇게 교체되면 알림 콜백이 이 Add-on에 전달되지 않아 NotificationPresented와 NotificationOpened 이벤트가 발생하지 않습니다. 이 패키지를 함께 쓴다면 권한 요청이 끝난 직후 앱의 델리게이트를 다시 연결하세요.

NotifyDidRegisterForRemoteNotificationsAsync

application(_:didRegisterForRemoteNotificationsWithDeviceToken:)에서 OS가 전달한 디바이스 토큰을 Add-on에 넘깁니다. Add-on이 토큰을 소문자 16진수 문자열로 바꿔 기다리던 GetTokenAsync()에 반환하고 TokenRefreshed 이벤트를 발생시킵니다.

Unity

Task<ApnsServiceNotifyDidRegisterForRemoteNotificationsResult> NotifyDidRegisterForRemoteNotificationsAsync(byte[] deviceToken, CancellationToken ct = default)

파라미터	타입	필수 여부	설명
`deviceToken`	`byte[]`	Required	콜백으로 받은 디바이스 토큰의 원본 바이트입니다. 문자열로 바꾸지 않고 넣습니다.

항목	값
응답	APNSServiceNotifyDidRegisterForRemoteNotificationsResponse

결과 케이스 — ApnsServiceNotifyDidRegisterForRemoteNotificationsResult

결과 케이스	와이어 코드	설명
`Success`	—	토큰을 전달했습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

발생 예외

예외	발생 조건
`ArgumentNullException`	`deviceToken`이 `null`인 경우

NotifyDidFailToRegisterAsync

application(_:didFailToRegisterForRemoteNotificationsWithError:)에서 원격 알림 등록 실패를 Add-on에 넘깁니다. 기다리던 GetTokenAsync()는 Code가 Unavailable인 Failure로 끝납니다.

Unity

Task<ApnsServiceNotifyDidFailToRegisterResult> NotifyDidFailToRegisterAsync(string errorDescription, CancellationToken ct = default)

파라미터	타입	필수 여부	설명
`errorDescription`	`string`	Required	콜백으로 받은 오류의 설명입니다. 기다리던 `GetTokenAsync()`가 반환하는 `Failure`의 `Problem.Message`에 담깁니다.

항목	값
응답	APNSServiceNotifyDidFailToRegisterResponse

결과 케이스 — ApnsServiceNotifyDidFailToRegisterResult

결과 케이스	와이어 코드	설명
`Success`	—	등록 실패를 전달했습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

발생 예외

예외	발생 조건
`ArgumentNullException`	`errorDescription`이 `null`인 경우

NotifyWillPresentNotificationAsync

userNotificationCenter(_:willPresent:withCompletionHandler:)에서 앱이 포그라운드에 있을 때 도착한 원격 푸시 알림을 Add-on에 넘깁니다. Add-on은 NotificationPresented 이벤트를 발생시킵니다.

이 메서드는 알림 표시 방식을 정하지 않습니다. 배너, 알림음, 배지 같은 포그라운드 표시 옵션은 앱의 willPresent 델리게이트가 OS의 completionHandler에 직접 전달하며, 응답의 PresentationOptions는 항상 비어 있습니다.

Unity

Task<ApnsServiceNotifyWillPresentNotificationResult> NotifyWillPresentNotificationAsync(ApnsNotification notification, CancellationToken ct = default)

파라미터	타입	필수 여부	설명
`notification`	ApnsNotification	Required	콜백으로 받은 `UNNotification`의 내용을 담은 알림입니다.

항목	값
응답	APNSServiceNotifyWillPresentNotificationResponse

결과 케이스 — ApnsServiceNotifyWillPresentNotificationResult

결과 케이스	와이어 코드	설명
`Success`	—	알림을 전달했습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

발생 예외

예외	발생 조건
`ArgumentNullException`	`notification`이 `null`인 경우

NotifyDidReceiveResponseAsync

userNotificationCenter(_:didReceive:withCompletionHandler:)에서 앱 사용자가 탭하거나 닫은 원격 푸시 알림과 선택한 액션을 Add-on에 넘깁니다. 알림을 닫은 응답은 customDismissAction 옵션으로 등록한 알림 유형에서만 전달됩니다. Add-on은 NotificationOpened 이벤트를 발생시킵니다.

Unity

Task<ApnsServiceNotifyDidReceiveResponseResult> NotifyDidReceiveResponseAsync(ApnsNotification notification, string actionIdentifier, CancellationToken ct = default)

파라미터	타입	필수 여부	설명
`notification`	ApnsNotification	Required	콜백으로 받은 `UNNotificationResponse.notification`의 내용을 담은 알림입니다.
`actionIdentifier`	`string`	Required	콜백으로 받은 `UNNotificationResponse.actionIdentifier` 값입니다. 가공하지 않고 넣습니다.

항목	값
응답	APNSServiceNotifyDidReceiveResponseResponse

결과 케이스 — ApnsServiceNotifyDidReceiveResponseResult

결과 케이스	와이어 코드	설명
`Success`	—	알림과 액션을 전달했습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

발생 예외

예외	발생 조건
`ArgumentNullException`	`notification` 또는 `actionIdentifier`가 `null`인 경우

NotifyColdStartNotificationAsync

앱이 종료된 상태에서 알림을 탭해 앱이 실행되면, 앱 시작 시점에 그 알림의 원본 페이로드를 Add-on에 넘깁니다. Add-on은 이 알림을 보관했다가 GetColdStartNotificationAsync()가 호출되면 한 번 반환합니다.

앱을 실행시킨 알림은 iOS에서는 앱 실행 옵션의 launchOptions[.remoteNotification]에 담깁니다. macOS에서는 실행 알림의 응답에 페이로드가 없으므로, 앱 실행 직후 델리게이트의 userNotificationCenter(_:didReceive:withCompletionHandler:)로 전달되는 알림에서 페이로드를 가져옵니다.

Unity

Task<ApnsServiceNotifyColdStartNotificationResult> NotifyColdStartNotificationAsync(string userInfoJson, CancellationToken ct = default)

파라미터	타입	필수 여부	설명
`userInfoJson`	`string`	Required	앱을 실행시킨 알림의 `userInfo`를 JSON 객체 문자열로 바꾼 값입니다. 빈 문자열, 빈 JSON 객체, JSON 객체가 아닌 문자열을 넣으면 아무것도 보관하지 않으므로, 알림 없이 실행된 경우에는 빈 문자열을 넣습니다.

항목	값
응답	APNSServiceNotifyColdStartNotificationResponse

결과 케이스 — ApnsServiceNotifyColdStartNotificationResult

결과 케이스	와이어 코드	설명
`Success`	—	알림을 전달했습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

발생 예외

예외	발생 조건
`ArgumentNullException`	`userInfoJson`이 `null`인 경우

이벤트

세 이벤트 모두 엔진 메인 스레드에서 호출되므로 핸들러 안에서 엔진 API를 사용해도 됩니다.

NotificationPresented

앱이 포그라운드에 있을 때 원격 푸시 알림이 도착해, 앱의 델리게이트가 NotifyWillPresentNotificationAsync()로 알림을 넘기면 발생합니다. OS가 전달한 알림 내용을 가공하지 않고 전달합니다.

Unity

event Action<ApnsNotification> NotificationPresented

파라미터	타입	설명
—	ApnsNotification	포그라운드에서 받은 알림입니다.

NotificationOpened

앱 사용자가 원격 푸시 알림이나 알림의 액션을 탭하거나 customDismissAction 옵션으로 등록한 알림 유형의 알림을 닫아, 앱의 델리게이트가 NotifyDidReceiveResponseAsync()로 넘기면 발생합니다. 탭한 알림과 선택한 액션을 함께 전달합니다.

Unity

event Action<ApnsNotificationOpened> NotificationOpened

파라미터	타입	설명
—	ApnsNotificationOpened	탭한 알림과 선택한 액션입니다.

TokenRefreshed

앱의 델리게이트가 NotifyDidRegisterForRemoteNotificationsAsync()로 디바이스 토큰을 넘길 때마다 발생하며, 결과를 기다리던 GetTokenAsync()도 같은 토큰으로 완료됩니다. Add-on은 새 토큰을 Hive Axyl 서버에 등록하지 않으므로 이벤트로 받은 토큰을 UpsertTokenAsync로 다시 등록하세요.

Unity

event Action<string> TokenRefreshed

파라미터	타입	설명
—	`string`	소문자 16진수 문자열로 된 디바이스 토큰입니다.

데이터 타입

ApnsNotification

UNNotificationContent의 원본 정보입니다. 딥링크 추출이나 사용자 정의 키 해석 같은 필드의 의미 해석은 앱이 담당합니다.

필드	타입	필수 여부	설명
`Title`	`string`	Required	알림 제목인 `UNNotificationContent.title`입니다. SDK 로그에 기록되지 않습니다.
`Subtitle`	`string`	Required	알림 부제목인 `UNNotificationContent.subtitle`입니다. SDK 로그에 기록되지 않습니다.
`Body`	`string`	Required	알림 본문인 `UNNotificationContent.body`입니다. SDK 로그에 기록되지 않습니다.
`Badge`	`int`	Required	알림에 담긴 배지 숫자인 `UNNotificationContent.badge`입니다. 값이 없는 알림과 배지를 지우는 알림은 모두 `0`이므로 두 경우를 구분할 수 없습니다.
`Sound`	`string`	Required	알림음 이름입니다. `UNNotificationContent`에는 알림음 이름을 읽는 공개 API가 없어 알림 콜백으로 받은 알림에서는 빈 문자열이므로, 알림음 이름은 `UserInfoJson`의 `aps.sound`에서 확인하세요. GetColdStartNotificationAsync()가 반환한 알림에는 `aps.sound` 값이 담깁니다.
`CategoryIdentifier`	`string`	Required	알림에 지정된 알림 유형의 식별자인 `UNNotificationContent.categoryIdentifier`입니다.
`ThreadIdentifier`	`string`	Required	관련 알림을 묶어 표시하는 데 쓰는 `UNNotificationContent.threadIdentifier`입니다.
`LaunchImageName`	`string`	Required	알림으로 앱을 실행할 때 표시할 실행 이미지 이름인 `UNNotificationContent.launchImageName`입니다. iOS에서만 제공되며 macOS에서는 빈 문자열입니다.
`TargetContentIdentifier`	`string`	Required	알림을 처리할 앱 화면을 정하는 데 쓰는 `UNNotificationContent.targetContentIdentifier`입니다. 값이 없으면 빈 문자열입니다.
`InterruptionLevel`	UNNotificationInterruptionLevel	Required	알림의 중요도와 전달 시점을 나타내는 `UNNotificationContent.interruptionLevel`입니다.
`RelevanceScore`	`double`	Required	시스템이 알림의 우선순위를 판단할 때 참조하는 0.0~1.0 범위의 `UNNotificationContent.relevanceScore`입니다. 값이 없으면 `0.0`입니다.
`UserInfoJson`	`string`	Required	`aps` 딕셔너리와 사용자 정의 키를 포함한 알림 페이로드 전체를 JSON 문자열로 담은 값입니다. 중첩된 값도 그대로 담기므로 필요한 키는 앱이 파싱합니다. SDK 로그에 기록되지 않습니다.

ApnsNotificationOpened

NotificationOpened 이벤트로 전달되는 값입니다. 앱 사용자가 탭한 알림과 선택한 액션을 함께 담습니다.

프로퍼티	타입	필수 여부	설명
`Notification`	ApnsNotification	Required	앱 사용자가 탭한 알림입니다.
`ActionIdentifier`	`string`	Required	앱 사용자가 선택한 액션의 식별자인 `UNNotificationResponse.actionIdentifier`입니다. 알림 자체를 탭하면 `UNNotificationDefaultActionIdentifier` 상수의 값인 `com.apple.UNNotificationDefaultActionIdentifier`, 알림 유형에 등록한 사용자 정의 액션을 선택하면 그 액션의 식별자입니다. `customDismissAction` 옵션으로 등록한 알림 유형의 알림을 닫으면 `UNNotificationDismissActionIdentifier` 상수의 값인 `com.apple.UNNotificationDismissActionIdentifier`입니다. 델리게이트가 NotifyDidReceiveResponseAsync()에 빈 문자열을 넘기면 빈 문자열이며, 이 경우에도 이벤트는 발생합니다.

APNSServiceGetColdStartNotificationResponse

필드	타입	필수 여부	설명
`Notification`	ApnsNotification	Required	앱을 실행시킨 알림입니다. 반환할 알림이 없으면 `null`이 아니라 모든 필드가 기본값인 빈 알림이며, `UserInfoJson`이 비어 있는지로 구분합니다.

APNSServiceGetNotificationSettingsResponse

필드	타입	필수 여부	설명
`AuthorizationStatus`	UNAuthorizationStatus	Required	현재 알림 권한 상태인 `UNNotificationSettings.authorizationStatus`입니다.

APNSServiceGetProviderEnvironmentResponse

필드	타입	필수 여부	설명
`Environment`	ProviderEnvironment	Required	앱의 `aps-environment` 엔타이틀먼트로 확인한 APNs 환경입니다.

APNSServiceGetTokenResponse

필드	타입	필수 여부	설명
`Token`	`string`	Required	소문자 16진수 문자열로 된 APNs 디바이스 토큰입니다. Push 모듈의 UpsertTokenRequest.Token에 넣습니다. 민감 정보이므로 SDK 로그에 평문으로 기록되지 않습니다.

APNSServiceNotifyColdStartNotificationResponse

필드가 없습니다.

APNSServiceNotifyDidFailToRegisterResponse

필드가 없습니다.

APNSServiceNotifyDidReceiveResponseResponse

필드가 없습니다.

APNSServiceNotifyDidRegisterForRemoteNotificationsResponse

필드가 없습니다.

APNSServiceNotifyWillPresentNotificationResponse

필드	타입	필수 여부	설명
`PresentationOptions`	IReadOnlyList<UNNotificationPresentationOption>	Required	항상 빈 목록입니다. 포그라운드 표시 옵션은 앱의 `willPresent` 델리게이트가 OS의 `completionHandler`에 직접 전달합니다.

APNSServiceRequestAuthorizationResponse

필드	타입	필수 여부	설명
`Granted`	`bool`	Required	앱 사용자가 알림 권한을 허용했으면 `true`입니다. 옵션별 허용 여부는 반환하지 않으며, 알림 권한 상태는 GetNotificationSettingsAsync()의 `AuthorizationStatus`로 확인합니다.

APNSServiceSetBadgeCountResponse

필드가 없습니다.

열거형

Add-on 열거형은 C# 멤버 이름으로 지정합니다. 표의 '값'은 직렬화에 사용하는 정수입니다.

ProviderEnvironment

앱의 aps-environment 엔타이틀먼트로 확인한 APNs 환경입니다.

C# 멤버	값	설명
`Unspecified`	0	환경이 지정되지 않은 기본값입니다. 조회에 성공하면 이 값은 반환되지 않습니다.
`Apns`	1	운영 환경입니다. `aps-environment`가 `production`입니다.
`ApnsSandbox`	2	샌드박스 환경입니다. `aps-environment`가 `development`입니다.

UNAuthorizationOption

RequestAuthorizationAsync()로 요청할 권한 옵션인 UNAuthorizationOptions입니다.

C# 멤버	값	설명
`Unspecified`	0	옵션이 없는 기본값입니다.
`Badge`	1	앱 아이콘 배지를 바꿀 수 있는 권한입니다.
`Sound`	2	알림음을 재생할 수 있는 권한입니다.
`Alert`	3	알림을 화면에 표시할 수 있는 권한입니다.
`CarPlay`	4	CarPlay 환경에서 알림을 표시할 수 있는 권한입니다.
`CriticalAlert`	5	무음 스위치와 집중 모드를 무시하고 알림음을 재생하는 중요 알림 권한입니다. Apple의 승인을 받은 별도 엔타이틀먼트가 필요합니다.
`ProvidesAppNotificationSettings`	6	앱에 자체 알림 설정 화면이 있음을 OS에 알립니다. OS가 그 화면으로 이동하는 버튼을 표시합니다.
`Provisional`	7	권한 대화 상자 없이 알림 센터에 조용히 전달되는 임시 권한입니다.

UNAuthorizationStatus

GetNotificationSettingsAsync()로 조회한 알림 권한 상태인 UNAuthorizationStatus입니다.

C# 멤버	값	설명
`Unspecified`	0	상태가 지정되지 않은 기본값입니다. OS는 이 값을 반환하지 않습니다.
`NotDetermined`	1	앱 사용자가 아직 알림 권한을 선택하지 않았습니다.
`Denied`	2	앱 사용자가 알림 권한을 거부했습니다.
`Authorized`	3	앱 사용자가 알림 권한을 허용했습니다.
`Provisional`	4	임시 권한으로 알림을 알림 센터에 조용히 전달할 수 있습니다.
`Ephemeral`	5	App Clip처럼 제한된 시간 동안 알림을 예약하거나 받을 수 있습니다.

UNNotificationInterruptionLevel

알림의 중요도와 전달 시점인 UNNotificationInterruptionLevel입니다.

C# 멤버	값	설명
`Unspecified`	0	수준이 지정되지 않은 기본값입니다. GetColdStartNotificationAsync()가 반환한 알림과 빈 알림에서는 이 값입니다.
`Passive`	1	화면을 켜거나 소리를 내지 않고 알림 목록에만 추가합니다.
`Active`	2	기본 수준으로 표시합니다. 화면을 켜고, 알림음이 설정되어 있으면 소리를 냅니다.
`TimeSensitive`	3	즉시 표시하며 집중 모드나 방해 금지 모드에서도 알림을 표시할 수 있습니다. 앱이 `com.apple.developer.usernotifications.time-sensitive` 엔타이틀먼트를 선언하지 않으면 OS가 `Passive`로 낮춰 전달합니다.
`Critical`	4	무음 스위치와 집중 모드를 무시하고 소리를 냅니다. 중요 알림 엔타이틀먼트가 필요합니다.

UNNotificationPresentationOption

포그라운드 알림 표시 옵션인 UNNotificationPresentationOptions입니다. APNSServiceNotifyWillPresentNotificationResponse.PresentationOptions의 타입이며, 이 목록은 항상 비어 있습니다.

C# 멤버	값	설명
`Unspecified`	0	옵션이 없는 기본값입니다.
`Badge`	1	알림을 표시하면서 앱 아이콘 배지를 바꿉니다.
`Sound`	2	알림을 표시하면서 알림음을 재생합니다.
`List`	3	알림 센터에 표시합니다.
`Banner`	4	배너로 표시합니다.