3단계. 토큰 발급 및 등록

iOS 환경에서 리모트 푸시 메시지 수신을 위한 디바이스 토큰은 APNs(Apple Push Notification service)를 통해 발급합니다.

본 문서에서는 Hive Axyl APNs 플러그인으로 디바이스 토큰을 발급받고, 푸시 환경을 확인한 뒤 Hive Axyl 푸시 서버에 등록하는 과정을 안내합니다.

APNs 토큰 발급 및 등록 순서는 아래와 같습니다.

※ 사전 요구 사항: APNs 연동 환경 구성을 참조하여 APNs 플러그인 설치, 알림 권한 요청, 그리고 델리게이트 코드 연결을 완료하세요.

1. APNs 토큰 발급
2. 푸시 환경 확인
3. 디바이스 토큰 등록
4. 토큰 갱신 대응

APNs 플러그인은 토큰 발급과 이벤트 전달만 담당합니다. 발급받은 토큰의 서버 등록, 토큰 저장, 알림 권한 요청은 앱 클라이언트에서 직접 수행합니다.

Note

• 시뮬레이터는 APNs 토큰을 발급할 수 없습니다. 토큰 발급은 iOS 실기기에서 확인하세요.
• 델리게이트가 Notify* 메서드를 호출하지 않으면 GetTokenAsync()가 완료되지 않습니다.

1. APNs 토큰 발급

플러그인 인스턴스는 SDK 초기화에서 AddAPNS()를 등록한 뒤 HiveCore.Resolve<IAPNSPlugin>()으로 가져옵니다. HiveBootstrap.Initialize를 먼저 완료해야 합니다.

public Task GetTokenAsync();

현재 기기에 등록된 APNs 디바이스 토큰을 조회합니다.

• OS에 원격 알림 등록(UIApplication.registerForRemoteNotifications)을 요청합니다.
• 앱의 델리게이트가 OS 콜백을 NotifyDidRegisterForRemoteNotificationsAsync()로 전달하면 호출이 완료됩니다.
• 발급받은 토큰은 디바이스 토큰 등록 메서드를 호출하여 Hive Axyl 푸시 서버에 등록해야 최종 푸시 메시지 발송 대상에 포함됩니다.

호출 파라미터

필드명	타입	필수 여부	설명
ct	CancellationToken	Optional	호출을 취소할 때 사용하는 취소 토큰입니다. 생략하면 기본값이 사용됩니다.

호출 예시

GetTokenAsync()의 반환 객체 ApnsServiceGetTokenResult는 성공, 실패 상태로 나뉩니다. 메서드 호출 시 예외(Exception)를 발생시키지 않으며, 모든 처리 결과가 반환 객체로 전달됩니다. 따라서 별도의 try/catch 구문을 사용하지 않고 switch 구문으로 응답 상태를 분기해 처리합니다.

Unity

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

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

ApnsServiceGetTokenResult result = await apns.GetTokenAsync();

switch (result)
{
    case ApnsServiceGetTokenResult.Success success:
        string apnsToken = success.Data.Token;   // 소문자 16진수 문자열
        // 발급받은 토큰을 Axyl 서버에 등록합니다.
        break;

    // 공통 실패 처리 - 자세한 에러 모델은 [에러 처리](PLACEHOLDER_에러처리_링크) 참고
    case ApnsServiceGetTokenResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // 안전망: 알 수 없는 신규 결과
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

호출 시 고려 사항

• GetTokenAsync()는 iOS 실기기에서 호출하세요. 시뮬레이터에서는 APNs 토큰을 발급할 수 없습니다.
• 호출 전에 HiveBootstrap.Initialize를 완료하고, APNs 연동 환경과 알림 권한 요청을 준비하세요.
• 앱 델리게이트에서 OS 등록 결과를 플러그인의 Notify* 메서드로 전달해야 합니다.
• 토큰은 앱 설치, 프로비저닝 정보 변경, OS 판단 등의 이유로 변경될 수 있습니다. 최초 발급 이후에도 토큰 갱신 이벤트에 대응해야 합니다.

응답 데이터

성공 시 ApnsServiceGetTokenResult.Success의 Data에 발급된 토큰이 담깁니다.

필드명	타입	필수 여부	설명
Data.Token	string	Required	발급된 APNs 디바이스 토큰입니다. 소문자 16진수 문자열로 반환됩니다.

응답 상태

반환 객체 ApnsServiceGetTokenResult는 아래 케이스로 분기됩니다. switch 구문으로 처리하세요.

응답 케이스	설명	앱 클라이언트 대응
Success	토큰 발급에 성공했습니다. Data.Token에 토큰 값이 담깁니다.	토큰을 Hive Axyl 서버에 등록
Failure	토큰 발급 실패. Problem(HiveError)의 Code로 원인을 구분합니다. 시뮬레이터 또는 OS 등록 실패(Unavailable), Push Notifications capability 미활성화(FailedPrecondition), 호출 취소(Cancelled) 등이 포함됩니다.	원인별 재시도 또는 오류 안내

2. 푸시 환경 확인

APNs 토큰은 개발 환경과 운영 환경이 분리되어 있으므로, 토큰을 등록하기 전에 현재 빌드가 사용하는 푸시 환경을 확인해야 합니다.

public Task GetProviderEnvironmentAsync();

빌드의 aps-environment entitlement를 읽어 푸시 환경을 확인합니다. development(샌드박스) 빌드는 ApnsSandbox, production 빌드는 Apns를 반환합니다. 환경은 빌드 시점에 결정되므로 토큰이 갱신되어도 다시 확인할 필요는 없습니다.

호출 파라미터

필드명	타입	필수 여부	설명
ct	CancellationToken	Optional	호출을 취소할 때 사용하는 취소 토큰입니다. 생략하면 기본값이 사용됩니다.

호출 예시

Unity

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

ApnsServiceGetProviderEnvironmentResult result = await apns.GetProviderEnvironmentAsync();

switch (result)
{
    case ApnsServiceGetProviderEnvironmentResult.Success success:
        UpsertTokenRequestProviderType providerType =
            success.Data.Environment == ProviderEnvironment.Apns
                ? UpsertTokenRequestProviderType.Apns
                : UpsertTokenRequestProviderType.ApnsSandbox;
        break;

    // 공통 실패 처리 - 자세한 에러 모델은 [에러 처리](PLACEHOLDER_에러처리_링크) 참고
    case ApnsServiceGetProviderEnvironmentResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // 안전망: 알 수 없는 신규 결과
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

호출 시 고려 사항

• GetProviderEnvironmentAsync()는 토큰 등록 요청의 ProviderType을 결정할 때 사용합니다.
• Push Notifications capability가 활성화되지 않은 빌드에서는 환경 확인에 실패할 수 있습니다.
• 개발 빌드와 릴리스 빌드가 서로 다른 APNs 환경을 사용하므로, Hive 콘솔 설정과 빌드 구성을 함께 확인하세요.

응답 데이터

성공 시 ApnsServiceGetProviderEnvironmentResult.Success의 Data에 환경 값이 담깁니다.

필드명	타입	필수 여부	설명
Data.Environment	ProviderEnvironment	Required	푸시 환경입니다. Apns(production) 또는 ApnsSandbox(development)입니다.

응답 상태

반환 객체 ApnsServiceGetProviderEnvironmentResult는 아래 케이스로 분기됩니다. switch 구문으로 처리하세요.

응답 케이스	설명	앱 클라이언트 대응
Success	환경 확인에 성공했습니다.	ProviderType 결정에 사용
Failure	확인 실패. Push Notifications capability가 활성화되지 않은 빌드면 FailedPrecondition 코드로 실패합니다.	연동 환경 구성 확인

3. 디바이스 토큰 등록

APNs에서 발급받은 토큰은 디바이스 토큰 등록 메서드를 호출하여 Hive Axyl 푸시 서버에 등록합니다. iOS 환경에서 등록할 때는 GetProviderEnvironmentAsync() 결과에 따라 UpsertTokenRequest.ProviderType에 Apns 또는 ApnsSandbox를 지정합니다.

Unity

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

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

var request = new UpsertTokenRequest {
    Token        = apnsToken,
    TimezoneId   = "Asia/Seoul",
    Country      = "KR",
    Language     = LanguageCode.Ko,
    ProviderType = providerType,
    Agreement    = new Agreement {
        Info      = true,
        Advertise = false,
        Night     = false,
    },
    EventType    = "LOGIN",
};

PushUpsertTokenResult result = await push.UpsertTokenAsync(request);

등록 요청 파라미터와 응답 상태는 디바이스 토큰 등록을 참고하세요.

4. 토큰 갱신 대응

델리게이트가 NotifyDidRegisterForRemoteNotificationsAsync()를 호출할 때마다, 최초 발급을 포함해 TokenRefreshed 이벤트가 발생합니다. Hive Axyl SDK는 새 토큰을 자동으로 Hive Axyl 서버에 등록하지 않으므로, 앱 클라이언트가 이 이벤트를 상시 구독하여 새 토큰을 받는 즉시 디바이스 토큰 등록 메서드를 다시 호출해야 합니다. 이벤트는 엔진 메인 스레드로 전달됩니다.

Unity

apns.TokenRefreshed += async newToken =>
{
    var result = await push.UpsertTokenAsync(new UpsertTokenRequest {
        Token        = newToken,
        ProviderType = providerType,
        // 나머지 필드는 최초 등록과 같은 값으로 채웁니다.
    });
    // 응답 상태 분기는 [디바이스 토큰 등록] 문서와 동일합니다.
};

최초 발급 토큰은 GetTokenAsync()의 결과로도 받을 수 있으므로, 같은 토큰을 중복 등록하지 않도록 한 경로에서만 등록하세요. 푸시 환경은 빌드 시점에 결정되므로 토큰이 갱신되어도 다시 확인할 필요는 없습니다.

참고: 델리게이트 콜백 전달 메서드

앱의 델리게이트가 OS 등록 결과를 플러그인에 전달하는 메서드입니다. 델리게이트 코드 준비에서 연결한 콜백 안에서 호출합니다.

• NotifyDidRegisterForRemoteNotificationsAsync(byte[] deviceToken): application(_:didRegisterForRemoteNotificationsWithDeviceToken:) 콜백에서 원본 토큰 바이트를 그대로 전달합니다. 대기 중인 GetTokenAsync()가 완료되고 TokenRefreshed 이벤트가 발생합니다.
• NotifyDidFailToRegisterAsync(string errorDescription): application(_:didFailToRegisterForRemoteNotificationsWithError:) 콜백에서 오류 설명을 전달합니다. 대기 중인 GetTokenAsync()가 Unavailable 코드의 Failure로 완료됩니다.

두 메서드 모두 성공 시 별도의 응답 데이터는 없습니다. 반환 객체(ApnsServiceNotifyDidRegisterForRemoteNotificationsResult/ApnsServiceNotifyDidFailToRegisterResult)는 Success/Failure로 분기됩니다.

다음 단계

4단계. 리모트 푸시 전송을 구현합니다.

연관 문서

본 문서의 내용과 관련하여 참조하는 문서는 아래와 같습니다.

• APNs 연동 환경 구성
• 디바이스 토큰 등록
• 푸시 수신 처리