1단계. 연동 환경 구성

Apple Developer에서 준비한 APNs 인증 정보를 Hive 콘솔에 입력하여 푸시 연동 기반을 마련하고, 전용 플러그인을 설치하여 iOS 리모트 푸시 구현 환경을 구성합니다.

1. Apple Developer 설정

Apple Developer에서 Hive Axyl 푸시 서비스와 연결할 APNs(Apple Push Notification service) 인증 정보를 생성합니다. 자세한 내용은 콘솔 가이드의 푸시 설정 문서를 참조하세요.

iOS에서 리모트 푸시를 수신하려면 Apple Developer Portal에서 앱의 푸시 기능을 활성화하고, 빌드 서명에 사용하는 프로비저닝 정보를 갱신해야 합니다.

• Apple Developer Portal에서 App ID의 Push Notifications Capability를 활성화합니다.
• Capability를 변경한 뒤 Provisioning Profile을 다시 발급합니다. Xcode 자동 서명을 사용하면 자동으로 갱신되고, 수동 서명이라면 직접 내려받습니다.
• APNs 발송에 사용할 인증서 또는 키 정보를 준비합니다.
• 최소 지원 버전은 iOS 17.0입니다. Unity Player Settings의 Target minimum iOS Version을 확인하세요.

2. Hive 콘솔 설정

Apple Developer 설정에서 생성한 APNs 인증 정보를 Hive 콘솔에 등록하여 Hive Axyl 푸시 서버가 iOS 디바이스로 푸시 메시지를 발송할 수 있도록 구성합니다. 자세한 내용은 콘솔 가이드의 푸시 설정 문서를 참조하세요.

Hive 콘솔에는 APNs 푸시 수단을 활성화하고, Apple Developer에서 준비한 APNs 인증서 또는 키 정보 등 푸시 발송에 필요한 값을 등록합니다.

3. Hive Axyl APNs 플러그인 설치

Hive Axyl SDK에서 제공하는 'APNs 플러그인'을 설치합니다.
iOS 리모트 푸시에서는 APNs 플러그인으로 디바이스 토큰을 발급받고, 앱 실행 중 수신된 메시지와 알림 탭 이벤트를 처리합니다.

해당 패키지를 아래 예시와 같이 프로젝트 의존성 필드에 추가합니다.

"dependencies": {
  "com.hive.axyl.core": "PLACEHOLDER_AXYL_CORE_VERSION",
  "com.hive.axyl.push": "PLACEHOLDER_AXYL_PUSH_VERSION",
  "com.hive.axyl.push.addon.apns": "PLACEHOLDER_AXYL_PUSH_APNS_VERSION"
}

iOS 빌드 시 플러그인이 생성된 Xcode 프로젝트에 다음을 자동으로 처리하므로 앱에서 추가할 작업이 없습니다.

• **Push Notifications capability 활성화**와 aps-environment entitlement 기록
• 빌드 구성에 따른 환경 분기 — Unity **Development Build**는 development(샌드박스), 릴리스 빌드는 production

UserNotifications 프레임워크는 플러그인의 네이티브 코드가 링크하므로 별도 의존성 추가가 필요 없고, 무음 푸시(silent push)를 지원하지 않으므로 Background Modes 설정도 필요 없습니다.

4. 알림 권한 및 델리게이트 코드 준비

APNs 플러그인은 토큰 발급, 알림 권한 요청, 알림 설정 조회, 수신 이벤트 전달을 담당합니다. 앱은 iOS에서 전달되는 알림 이벤트를 받을 코드를 직접 연결해야 합니다.

알림 권한 요청

알림을 표시하려면 사용자에게 알림 권한(requestAuthorization)을 요청해야 합니다. APNs 플러그인의 RequestAuthorizationAsync()로 시스템 권한 팝업을 요청하고, GetNotificationSettingsAsync()로 현재 권한 상태를 조회하세요.

Unity

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

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

ApnsServiceRequestAuthorizationResult result =
    await apns.RequestAuthorizationAsync(new[] {
        UNAuthorizationOption.Alert,
        UNAuthorizationOption.Badge,
        UNAuthorizationOption.Sound,
    });

if (result is ApnsServiceRequestAuthorizationResult.Success success)
{
    bool granted = success.Data.Granted;
    // granted가 false이면 사용자가 알림 권한을 거부한 상태입니다.
}

권한 거부는 실패가 아니라 Success의 Data.Granted == false로 처리합니다. 현재 OS 권한 상태 원문이 필요하면 GetNotificationSettingsAsync() 결과의 Data.AuthorizationStatus를 확인하세요.

델리게이트 코드 준비

APNs 플러그인은 앱의 UIApplicationDelegate/UNUserNotificationCenterDelegate를 대신 설치하거나 가로채지 않습니다. 앱이 자체 델리게이트를 설정하고, 델리게이트 콜백 안에서 플러그인의 Notify* 메서드를 직접 호출해야 합니다. 델리게이트 콜백을 연결하지 않으면 토큰 발급 결과와 수신 이벤트가 도착하지 않습니다.

연결할 콜백은 네 가지입니다. 각 메서드는 OS 콜백이 전달한 데이터(디바이스 토큰, 알림 객체 등)를 인자로 받아 플러그인에 넘깁니다. 시그니처 상세는 각 reference 페이지를 참고하세요.

OS 델리게이트 콜백	호출할 플러그인 메서드
application(_:didRegisterForRemoteNotificationsWithDeviceToken:)	NotifyDidRegisterForRemoteNotificationsAsync(deviceToken) — APNs 토큰 발급 참고
application(_:didFailToRegisterForRemoteNotificationsWithError:)	NotifyDidFailToRegisterAsync(errorDescription) — APNs 토큰 발급 참고
userNotificationCenter(_:willPresent:withCompletionHandler:)	NotifyWillPresentNotificationAsync(notification) — 푸시 수신 처리 참고
userNotificationCenter(_:didReceive:withCompletionHandler:)	NotifyDidReceiveResponseAsync(notification, actionIdentifier) — 푸시 수신 처리 참고
콜드 스타트 실행 옵션 또는 초기 알림 응답	NotifyColdStartNotificationAsync(userInfoJson) — 푸시 수신 처리 참고

알림을 탭해 앱이 실행된 경우(콜드 스타트)의 페이로드 캡처도 앱의 application(_:didFinishLaunchingWithOptions:) 델리게이트 코드가 수행합니다. 캡처한 원본 페이로드 JSON은 NotifyColdStartNotificationAsync(userInfoJson)로 전달한 뒤, 앱 시작 흐름에서 GetColdStartNotificationAsync()로 조회합니다. 자세한 내용은 푸시 수신 처리를 참고하세요.

다음 단계

2단계. 토큰 발급 및 등록을 구현합니다.