콘텐츠로 이동

3단계. 토큰 발급 및 등록

Android 환경에서 리모트 푸시 메시지 수신을 위한 디바이스 토큰은 FCM(Firebase Cloud Messaging)을 통해 발급합니다.

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


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

※ 사전 요구 사항: FCM 연동 환경 구성을 참조하여 FCM 플러그인 설치, google-services.json 파일 포함, 그리고 런타임 알림 권한 요청을 완료하세요.

  1. FCM 토큰 발급
  2. 디바이스 토큰 등록
  3. 토큰 갱신 대응

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

Note
  • FCM 플러그인은 Android 디바이스 전용입니다. Unity Editor를 포함한 다른 환경에서는 포트가 등록되지 않으므로 OS 분기 또는 HiveCore.TryResolve<T>()로 보호하세요.


1. FCM 토큰 발급

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

Method

public Task GetTokenAsync();


현재 기기에 등록된 FCM 토큰을 조회합니다.

  • 호출할 때마다 OS에 직접 질의해 최신 토큰을 새로 받아오며, 플러그인 내부에서는 토큰을 캐시하지 않습니다.
  • 발급받은 토큰은 디바이스 토큰 등록 메서드를 호출하여 Hive Axyl 푸시 서버에 등록해야 최종 푸시 메시지 발송 대상에 포함됩니다.


호출 파라미터

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


호출 예시

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

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

IFCMPlugin fcm = HiveCore.Resolve<IFCMPlugin>();

FcmServiceGetTokenResult result = await fcm.GetTokenAsync();

switch (result)
{
    case FcmServiceGetTokenResult.Success success:
        string fcmToken = success.Data.Token;
        // 발급받은 토큰을 Axyl 서버에 등록합니다.
        break;

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

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


호출 시 고려 사항

  • GetTokenAsync()는 Android 실기기에서 호출하세요. Unity Editor나 지원하지 않는 OS에서는 FCM 포트가 등록되지 않습니다.
  • 호출 전에 HiveBootstrap.Initialize를 완료하고, FCM 연동 환경과 알림 권한 요청을 준비하세요.
  • 토큰은 앱 설치, 데이터 삭제, Firebase 설정 변경 등의 이유로 변경될 수 있습니다. 최초 발급 이후에도 토큰 갱신 이벤트에 대응해야 합니다.


응답 데이터

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

필드명 타입 필수 여부 설명
Data.Token string Required 발급된 FCM 등록 토큰입니다.


응답 상태

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

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


2. 디바이스 토큰 등록

FCM에서 발급받은 토큰은 디바이스 토큰 등록 메서드를 호출하여 Hive Axyl 푸시 서버에 등록합니다. Android 환경에서 등록할 때는 UpsertTokenRequest.ProviderType에 Fcm을 지정합니다.

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

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

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

PushUpsertTokenResult result = await push.UpsertTokenAsync(request);

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


3. 토큰 갱신 대응

기기의 보안 상태 변화, 앱 데이터 초기화, 혹은 일정 주기 경과 등의 이유로 기존의 FCM 토큰이 만료되어 FCM에서 토큰을 새로 발급하면, TokenRefreshed 이벤트가 발생합니다. Hive Axyl SDK는 새 토큰을 자동으로 Hive Axyl 서버에 등록하지 않으므로, 앱 클라이언트가 이 이벤트를 상시 구독하여 새 토큰을 받는 즉시 디바이스 토큰 등록 메서드를 다시 호출해야 합니다. 이벤트는 엔진 메인 스레드로 전달됩니다.

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


참고: 토큰 삭제하기

Method

public Task DeleteTokenAsync();


현재 로컬 기기에 생성되어 있는 FCM 등록 토큰을 강제로 폐기합니다.

  • 내부적으로 Firebase FCM SDK의 FirebaseMessaging.deleteToken()을 호출하여 동작합니다.
  • 토큰이 성공적으로 폐기되면 기존 토큰을 이용한 푸시 알림 수신이 즉시 중단됩니다. 이후 FCM은 다음 GetTokenAsync() 메서드가 호출되는 시점이나 시스템 내부 판단에 따라 TokenRefreshed 이벤트를 발생시켜 새로운 디바이스 토큰을 다시 발급합니다.


호출 파라미터

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


응답 상태

반환 객체 FcmServiceDeleteTokenResult는 아래 케이스로 분기됩니다. 성공 시 별도의 응답 데이터는 없습니다.

응답 케이스 설명 앱 클라이언트 대응
Success 로컬 토큰이 폐기되었습니다. 필요 시 재발급 및 재등록
Failure 토큰 폐기 실패. Problem(HiveError)의 Code로 원인을 구분합니다. Firebase 미초기화(FailedPrecondition) 등이 포함됩니다. 원인별 재시도 또는 오류 안내


다음 단계

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


연관 문서

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