시작하기
'푸시 알림'은 사용자 기기에 정보성·광고성 메시지를 전달하는 기능입니다. Hive Axyl 푸시 서버와 FCM(Firebase Cloud Messaging), APNs(Apple Push Notification service) 같은 OS별 외부 푸시 서비스를 이용해 원격으로 메시지를 전달하는 리모트 푸시를 제공합니다.
본 문서에서는 '푸시 알림' 구현에 앞서 기능 동작 방식과 구현 순서를 안내합니다.
리모트 푸시 알림
'리모트 푸시 알림'은 Hive Axyl 푸시 서버에서 메시지를 생성하고, FCM 또는 APNs를 거쳐 사용자 기기에 전달하는 방식으로 동작합니다. 앱 클라이언트는 OS별 푸시 서비스에서 발급받은 디바이스 토큰을 Hive Axyl 서버에 등록하고, 도착한 메시지 또는 알림 탭 이벤트를 처리합니다.
푸시 메시지 발송은 Hive 콘솔 또는 서버 API에서 수행하며, 앱 클라이언트에서 직접 발송하지 않습니다.
서버 API 요청 시, Hive Axyl 푸시 서버에서 푸시를 전송하도록, Hive 콘솔에 로그인 후 FCM 토큰을 Hive Axyl 푸시 서버에 등록하세요. 서버 발송 API는 Hive Axyl Push 서버 API를 참고하세요.
OS별 지원 범위
'리모트 푸시 알림'은 OS별 푸시 서비스와 전용 플러그인을 사용합니다.
| OS | 푸시 서비스 | 연동 환경 구성 | 토큰 발급 | 수신 처리 |
|---|---|---|---|---|
| Android | FCM | FCM 연동 환경 구성 | FCM 토큰 발급 | 푸시 수신 처리(Android) |
| iOS | APNs | APNs 연동 환경 구성 | APNs 토큰 발급 | 푸시 수신 처리(iOS) |
Android에서 FCM을 사용하려면 Firebase 콘솔 설정과 FCM 플러그인 설치가 필요합니다. iOS에서 APNs를 사용하려면 Apple Developer 설정, APNs 플러그인 설치, 알림 권한 요청, 델리게이트 콜백 연결이 필요합니다.
SDK 구성 요소
Hive Axyl SDK의 리모트 푸시 알림 기능은 서버 토큰 등록 및 관리 기능을 제공하는 공통 모듈과 OS별 토큰 발급·수신 처리를 담당하는 애드온으로 구성됩니다.
| 역할 | Android | iOS |
|---|---|---|
| 서버 토큰 등록/관리 | AddPush() / IPushService | AddPush() / IPushService |
| OS 토큰 발급 | AddFCM() / IFCMPlugin.GetTokenAsync() | AddAPNS() / IAPNSPlugin.GetTokenAsync() |
| OS 권한 | 앱에서 POST_NOTIFICATIONS 직접 요청 | IAPNSPlugin.RequestAuthorizationAsync() |
| 콜드 스타트 조회 | GetColdStartMessageAsync() | GetColdStartNotificationAsync() |
| 수신 이벤트 | NotificationReceived | 델리게이트가 Notify* 호출 후 NotificationPresented 또는 NotificationOpened 발생 |
OS 애드온은 지원 OS에서만 등록됩니다. Editor, 서버 빌드, 다른 OS에서 같은 코드를 실행할 수 있다면 OS 분기 또는 HiveCore.TryResolve<T>()로 보호하세요.
디바이스 토큰 등록과 관리
디바이스 토큰은 푸시 메시지를 수신할 기기를 식별하는 값입니다. Android에서는 FCM이, iOS에서는 APNs가 토큰을 발급합니다. 앱 클라이언트는 발급받은 토큰을 디바이스 토큰 등록으로 Hive Axyl 서버에 저장합니다.
토큰 등록은 로그인된 세션을 사용합니다. 토큰은 로그인한 사용자(Player ID)와 연결되므로, 특정 사용자를 대상으로 하는 싱글 푸시 발송에 사용할 수 있습니다.
토큰 설정 변경을 참조하여 등록한 토큰의 언어와 수신 동의를 변경하며, 로그아웃 등으로 해당 사용자 대상 알림을 발송하지 않으려면 토큰 식별자 연결을 해제합니다.
수신 동의
푸시 수신 동의는 토큰 단위로 관리합니다. 토큰을 등록할 때 아래 세 항목을 함께 전달하고, 사용자가 앱 안의 알림 설정을 바꾸면 수신 동의 변경으로 갱신합니다.
- 정보성 알림 수신 동의
- 광고성 알림 수신 동의
- 야간 광고성 알림 수신 동의
야간 광고성 알림 수신 동의는 광고성 알림 수신 동의가 꺼져 있으면 켤 수 없습니다.
수신 처리
앱이 실행 중일 때 도착한 메시지와, 사용자가 알림을 탭해 앱이 실행된 경우(콜드 스타트)는 OS별 수신 처리 문서에서 구현합니다.
- Android: 푸시 수신 처리(Android)
- iOS: 푸시 수신 처리(iOS)
알림에 동봉된 데이터는 앱 클라이언트가 해석해 화면 이동, 상태 갱신, 이벤트 처리 같은 동작을 구현합니다.
구현 순서
앱 클라이언트에서 '리모트 푸시 알림'을 구현하는 순서는 아래와 같습니다.
- '푸시 알림' 모듈을 설치하고 초기화합니다.
- OS별 연동 환경을 구성합니다.
- Android: FCM 연동 환경 구성
- iOS: APNs 연동 환경 구성
- 푸시 권한 요청: OS별 기기를 대상으로 푸시 알림 권한을 요청합니다.
- Android: Android 13 이상 기기를 위한 런타임 알림 권한을 요청합니다.
- iOS: iOS/macOS 시스템 알림 권한 팝업을 요청합니다.
- 각 메시징 인프라 서비스에서 디바이스 토큰을 발급받습니다.
- Android: FCM 토큰 발급
- iOS: APNs 토큰 발급
- [OS 공통] 디바이스 토큰 등록: 발급받은 디바이스 토큰을 Hive Axyl 서버에 등록합니다.
- 푸시 전송: Hive 콘솔 또는 서버 API로 푸시 메시지를 발송합니다. Hive Axyl SDK는 리모트 푸시 전송 메서드를 제공하지 않습니다.
- 푸시 수신 처리: OS별 도착한 푸시 메시지를 처리합니다.
- [OS 공통] 토큰 설정 변경: 필요 시, 등록한 토큰의 언어와 수신 동의를 변경하거나, 토큰에 연결된 사용자 식별자를 해제합니다.
다음 단계
'푸시 알림' 기능을 구현하려면 먼저 '푸시 알림' 모듈 설치 및 초기화를 진행하세요.