로컬 푸시 알림

Unity Mobile Notifications로 모바일 로컬 알림을 요청, 예약, 취소하는 예시를 안내합니다.

모바일 로컬 알림은 Hive Axyl 푸시 서버, FCM, APNs 발송 서버를 거치지 않고 앱이 기기 안에서 직접 예약하는 알림입니다. Hive Axyl 제공 푸시 서비스 범위에는 포함되지 않으며, 앱은 Unity Mobile Notifications와 앱 정책을 기준으로 권한, 예약, 취소, 식별자 저장을 직접 관리합니다.

전체 흐름

순서	구분	하는 일
1	Unity 패키지, 레시피 코드	Unity Mobile Notifications와 예시 코드 준비
2	앱 코드, 레시피 코드	로컬 알림 권한 요청
3	앱 코드, 레시피 코드	로컬 알림 예약
4	앱 코드, 레시피 코드	예약한 알림 취소
5	앱 코드	리모트 푸시와 함께 사용할 때 APNs 포워더 복구

Hive Axyl 서버 등록과 무관합니다

로컬 알림 예시는 Hive Axyl 서버에 디바이스 토큰을 등록하지 않습니다. 로그인 세션, AddPush(), FCM/APNs 발송 정보는 리모트 푸시 알림을 구현할 때만 필요합니다.

1. 예시 코드 준비

Unity 패키지 Unity Mobile Notifications 패키지를 프로젝트에 설치합니다.

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

Unity 프로젝트에 Unity Mobile Notifications 패키지를 설치하고, 레시피 예시 코드를 복사하세요.

항목	역할
`com.unity.mobile.notifications`	Android/iOS 로컬 알림 권한 요청, 예약, 취소
Notifications/PushPreparationExample.cs	리모트 푸시 준비 호출 뒤 APNs 포워더를 복구하는 예시
Notifications/LocalNotification/LocalNotificationExamples.cs	로컬 알림 권한 요청, 예약, 취소, 전체 취소 예시

앱 코드에서 예시를 호출하려면 앱 쪽 어셈블리 정의의 references에 예시 어셈블리와 로컬 알림 레시피 어셈블리를 추가하세요. LocalNotificationExamples.asmdef는 com.unity.mobile.notifications 패키지가 설치되어 있을 때 HIVE_AXYL_UNITY_MOBILE_NOTIFICATIONS define을 활성화합니다.

2. 권한 요청

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

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

알림을 표시하려면 먼저 OS 알림 권한을 확인하거나 요청하세요. 권한 요청 뒤 iOS의 notification center delegate가 Unity 쪽으로 바뀔 수 있으므로, 리모트 APNs 푸시를 함께 사용한다면 복구 콜백을 전달하세요. Android 또는 APNs 포워더를 사용하지 않는 플랫폼에서는 빈 콜백을 전달해도 됩니다.

Unity

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

CancellationToken cancellationToken = default;
ILocalNotificationSource source = CreateLocalNotificationSource();
Action restoreNotificationDelegate = () =>
{
    // 앱이 사용하는 APNs 델리게이트 포워더를 다시 설치합니다.
};

LocalNotificationOutcome outcome =
    await LocalNotificationExamples.RequestPermissionAsync(
        source,
        restoreNotificationDelegate,
        cancellationToken);

switch (outcome.Status)
{
    case LocalNotificationStatus.Success:
        // 로컬 알림 예약을 진행할 수 있습니다.
        break;

    case LocalNotificationStatus.PermissionDenied:
        // OS 설정 안내 등 앱 정책에 맞게 처리합니다.
        break;

    default:
        Debug.LogError($"{outcome.FailedStep}: {outcome.Error?.Message}");
        break;
}

권한 거부는 오류가 아니라 사용자의 OS 권한 상태입니다. 반복해서 권한 요청을 호출하기보다 앱 설정 또는 OS 설정 안내를 제공하세요.

3. 알림 예약

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

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

ScheduleAsync()는 권한을 확인한 뒤 지정한 시각에 로컬 알림을 예약합니다. 예약에 성공하면 반환된 알림 ID를 앱 저장소에 보관하세요. 이후 같은 알림을 취소할 때 이 ID를 사용합니다.

Unity

using System;

DateTime fireAt = DateTime.Now.AddHours(8);

LocalNotificationOutcome outcome =
    await LocalNotificationExamples.ScheduleAsync(
        source,
        title: "출석 보상",
        body: "오늘의 보상을 받을 시간입니다.",
        fireAt,
        restoreNotificationDelegate,
        cancellationToken);

if (outcome.Status == LocalNotificationStatus.Success)
{
    int notificationId = outcome.Id;
    // 같은 알림을 나중에 취소할 수 있도록 notificationId를 저장합니다.
}

DateTimeKind.Utc 값은 UTC로 처리하고, Local 또는 Unspecified 값은 로컬 시간으로 처리합니다. 과거 시각이나 앱 정책상 허용하지 않는 예약 조건은 앱에서 먼저 걸러내세요.

4. 예약 취소

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

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

저장해 둔 알림 ID로 특정 알림을 취소하거나, 앱이 소유한 로컬 알림을 모두 취소할 수 있습니다.

Unity

LocalNotificationOutcome canceled =
    LocalNotificationExamples.Cancel(source, savedNotificationId);

if (canceled.Status == LocalNotificationStatus.Success)
{
    // 저장소에서 savedNotificationId를 제거합니다.
}

LocalNotificationOutcome allCanceled =
    LocalNotificationExamples.CancelAll(source);

CancelAll()은 앱이 소유한 모든 로컬 알림을 지우는 의도적인 초기화 상황에서만 호출하세요. 취소에 실패하면 저장해 둔 알림 ID를 지우지 말고 오류를 확인하세요.

5. 리모트 푸시와 함께 사용

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

리모트 APNs 푸시와 Unity Mobile Notifications를 함께 사용하면 권한 요청 과정에서 notification center delegate가 Unity 쪽으로 바뀔 수 있습니다. 앱이 APNs 델리게이트 포워더를 사용한다면 권한 요청 또는 예약 호출이 성공, 실패, 취소 중 무엇으로 끝나더라도 finally 블록에서 포워더를 다시 설치하세요.

Notifications/PushPreparationExample.cs는 PushRecipe.PrepareAsync() 호출을 감싸고, 마지막에 restoreNotificationDelegate()를 호출하는 예시입니다.

Unity

IPushTokenSource pushSource = CreatePushTokenSource();

PreparePushOutcome prepared =
    await PushPreparationExample.RunAsync(
        pushSource,
        preparation,
        restoreNotificationDelegate,
        cancellationToken);

리모트 푸시 디바이스 토큰 등록은 Google Firebase Cloud Messaging 구현 또는 Apple Push Notification Service 구현을 참고하세요.

다음 단계

Android 리모트 푸시 알림을 구현하려면 Google Firebase Cloud Messaging 구현을 참조하세요. iOS 리모트 푸시 알림을 구현하려면 Apple Push Notification Service 구현을 참조하세요.