Google Firebase Cloud Messaging 구현하기

Android에서 리모트 푸시 알림을 수신하려면 아래 절차를 순서대로 완료하세요.

시작하기 전에 공통 사전 준비를 마치세요.

전체 흐름

각 단계에서 무엇을 조작하고 무엇을 호출하는지는 아래와 같습니다.

순서	구분	하는 일
1	외부 콘솔	Firebase 콘솔에서 FCM 프로젝트와 Android 앱 설정
2	Hive 콘솔	FCM 발송 정보 등록
3	Hive Axyl SDK, OS 플러그인	푸시 모듈과 FCM 플러그인 설치 및 등록
4	레시피 코드	레시피 폴더 복사
5	앱 코드	`PushPreparation` 생성
6	레시피 코드	알림 권한 요청, FCM 토큰 발급, Hive Axyl 서버 등록
7	앱 코드, 레시피 코드	토큰 갱신 이벤트 대응
8	OS 플러그인, 앱 코드	수신 메시지와 콜드 스타트 처리
9	Hive 콘솔, Hive Axyl 서버 API	리모트 푸시 발송

수신 동의 값은 앱 정책의 최신 상태로 전달하세요

레시피는 전달받은 수신 동의 값을 그대로 Hive Axyl 서버에 등록합니다. 사용자가 광고성 알림이나 야간 광고성 알림 동의를 변경했다면 다음 등록 시점에 변경된 값을 넣어 다시 등록하세요.

1. Firebase 콘솔 설정

외부 콘솔 Firebase 콘솔에서 설정합니다.

상세 절차: Google Play 푸시 알림 연동, FCM 연동 환경 구성

Firebase 콘솔에서 FCM을 사용할 프로젝트와 Android 앱을 준비하세요. 앱 빌드에 포함할 google-services.json 파일도 내려받습니다.

google-services.json 파일은 앱 모듈 위치에 포함해야 합니다. 이 파일이 없으면 Firebase가 초기화되지 않아 FCM 토큰 발급이 실패합니다.

2. Hive 콘솔 설정

Hive 콘솔 Hive 콘솔에서 설정합니다.

1단계에서 준비한 FCM 발송 정보를 Hive 콘솔에 등록하세요.

설정 항목	필수 여부	확인할 곳
프로젝트 ID	필수	Google Play 푸시 알림 연동
서비스 Key 파일	필수	Google Play 푸시 알림 연동

앱에서 토큰 등록에 성공해도 Hive 콘솔의 FCM 발송 정보가 잘못되면 실제 푸시 발송이 실패할 수 있습니다.

3. SDK 모듈과 플러그인 준비

Hive Axyl SDK Hive Axyl SDK를 앱에서 호출합니다.

OS 플러그인 OS 플러그인을 앱에서 호출합니다.

상세 절차: 푸시 모듈 설치 및 초기화, FCM 연동 환경 구성

푸시 모듈과 FCM 플러그인을 설치한 뒤 SDK를 초기화할 때 등록하세요.

패키지	역할
`com.hive.axyl.core`	SDK 초기화와 공통 기능
`com.hive.axyl.auth`	토큰 등록에 필요한 로그인 세션
`com.hive.axyl.push`	Hive Axyl 서버의 디바이스 토큰 등록
`com.com2usplatform.hiveaxyl.push.addon.fcm`	FCM 토큰 발급, 토큰 갱신 이벤트, 수신 메시지 이벤트

아래는 SDK를 초기화할 때 푸시 모듈과 FCM 플러그인을 등록하는 예제 코드입니다.

Unity

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

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

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

AddPush()를 등록하지 않으면 레시피가 FailedPrecondition 오류로 실패합니다. AddFCM()을 등록하지 않으면 FCM 토큰 소스가 토큰을 발급받을 수 없습니다.

4. 레시피 코드 설치

레시피 코드 레시피 코드를 프로젝트에 복사합니다.

레시피는 패키지가 아니라 프로젝트에 복사해서 사용하는 소스 코드입니다. 아래 항목을 Unity 프로젝트의 Assets/Recipes/ 아래로 복사하세요.

복사 대상	역할
Recipes.asmdef	공통 어셈블리 정의
Helper/	여러 레시피가 함께 사용하는 공통 코드
Push/	`PushRecipe`, `PushPreparation`, 결과 타입
Push.Fcm/	Android FCM 권한 요청과 토큰 발급 코드

앱 코드에서 레시피를 호출하려면 앱 쪽 어셈블리 정의의 references에 Hive.Axyl.Samples.Recipes, Hive.Axyl.Samples.Recipes.Push, Hive.Axyl.Samples.Recipes.Push.Fcm을 추가하세요.

FCM 플러그인이 없으면 빌드에서 제외됩니다

Push.Fcm/의 어셈블리 정의는 FCM 플러그인 패키지가 설치되어 있을 때만 컴파일됩니다. 플러그인을 설치하지 않아도 공통 푸시 레시피는 남고, FCM 토큰 소스 어셈블리만 빌드에서 제외됩니다.

5. PushPreparation 생성

앱 코드 앱에서 직접 구현합니다.

PushPreparation은 이 디바이스를 어떤 조건과 수신 동의 값으로 등록할지를 담는 레시피 타입입니다.

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);

language는 Hive Axyl 서버가 지원하는 언어 코드로 전달하세요. country는 ISO 3166-1 alpha-2 형식으로 전달하고, timezoneId는 IANA 타임존 이름으로 전달하세요.

agreedToNightAdvertising은 agreedToAdvertising이 true일 때만 true로 설정할 수 있습니다. 잘못된 조합이면 레시피는 서버 호출 전에 실패로 반환합니다.

6. FCM 토큰 등록

레시피 코드 레시피 코드를 앱에서 호출합니다.

로그인을 완료한 뒤 PrepareAsync()를 호출하세요. 이 메서드 하나가 Android 알림 권한을 확인 또는 요청하고, FCM 토큰을 발급받고, Hive Axyl 서버에 토큰과 수신 동의 값을 등록합니다.

Unity

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

CancellationToken cancellationToken = default;
using IPushTokenSource source = new FcmPushTokenSource();
var recipe = new PushRecipe(source);

PreparePushOutcome prepared = await recipe.PrepareAsync(preparation, cancellationToken);

switch (prepared.Status)
{
    case PreparePushStatus.Success:
        // prepared.DeviceToken은 로그에 그대로 남기지 말고 마스킹하세요.
        break;

    case PreparePushStatus.PermissionDenied:
        // Android 13 이상에서 알림 권한이 허용되지 않아 토큰을 등록하지 않았습니다.
        break;

    case PreparePushStatus.BusinessOutcome:
        Debug.LogWarning($"{prepared.FailedStep}: {prepared.BusinessOutcome}");
        break;

    case PreparePushStatus.Failure:
        Debug.LogError($"{prepared.FailedStep}: {prepared.Error?.Message}");
        break;
}

레시피가 내부에서 수행하는 작업은 아래와 같습니다.

구분	호출	확인할 곳
OS 플러그인	Android 13 이상에서 `POST_NOTIFICATIONS` 권한 요청	FCM 연동 환경 구성
OS 플러그인	`GetTokenAsync()`로 FCM 토큰 발급	FCM 토큰 발급 및 등록
Hive Axyl SDK	`UpsertTokenAsync()`로 토큰과 수신 동의 등록	디바이스 토큰 등록

Android 12 이하에는 POST_NOTIFICATIONS 권한이 없으므로 레시피가 권한 요청을 건너뛰고 진행합니다. Android 13 이상에서는 사용자가 알림 권한을 허용하지 않으면 PermissionDenied를 반환하고 토큰을 등록하지 않습니다.

7. 토큰 갱신 대응

앱 코드 앱에서 직접 구현합니다.

레시피 코드 레시피 코드를 앱에서 호출합니다.

FCM이 새 토큰을 발급하면 앱은 새 토큰을 다시 Hive Axyl 서버에 등록해야 합니다. 레시피는 TokenRefreshed 이벤트를 직접 소유하지 않으므로, 앱의 생명주기 소유자가 이벤트를 구독하고 등록 호출을 직렬화하세요.

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);
}

한 번에 여러 등록을 동시에 실행하지 마세요. 성공한 뒤 최신 이벤트 토큰이 방금 등록한 토큰과 다를 때만 한 번 더 등록하세요.

8. 푸시 수신 처리

OS 플러그인 OS 플러그인을 앱에서 호출합니다.

앱 코드 앱에서 직접 구현합니다.

상세 절차: 푸시 수신 처리(Android)

레시피는 토큰을 등록할 뿐, 도착한 푸시 메시지를 화면에 표시하거나 알림 탭으로 앱이 열린 상황을 처리하지 않습니다. 토큰 등록 후에는 FCM 수신 처리를 구현하세요.

수신 메시지의 커스텀 데이터는 앱이 해석해 화면 이동, 상태 갱신, 이벤트 처리 같은 동작을 구현합니다.

9. 리모트 푸시 발송

Hive 콘솔 Hive 콘솔에서 리모트 푸시를 발송합니다.

Hive Axyl 서버 API 앱 서버에서 Hive Axyl 서버 API를 호출합니다.

상세 절차: 리모트 푸시 전송

리모트 푸시 메시지는 Hive 콘솔 또는 Hive Axyl 서버 API로 발송합니다. 앱 클라이언트는 발송 주체가 아닙니다.

캠페인 발송 대상 필터에는 토큰 등록 시 전달한 언어, 국가, 타임존, 수신 동의 값이 사용됩니다.

다음 단계

iOS에서도 리모트 푸시 알림을 구현하려면 Apple Push Notification Service 구현을 참조하세요. Unity Mobile Notifications 기반 로컬 알림 예시는 Notifications 예시 활용을 참조하세요.