notifee

React Native에서 로컬 알림(앱이 직접 띄우는 알림)을 다루기 좋은 라이브러리가 Notifee다. 원격 푸시(FCM/APNs로 서버가 쏘는 것)와 별개로, 채널·권한·즉시 표시·예약(트리거)을 JS에서 일관되게 다룰 수 있다.

1. 가이드 영상

2. 한눈에 구조

• 권한: iOS는 기본이 꺼져 있어서 requestPermission()을 먼저 호출한다. Android 13+도 런타임 알림 권한이 필요하다.
• 채널(Android): 알림을 카테고리로 묶는 단위. createChannel({ id, name })으로 만들고, 표시할 때 android.channelId에 그 id를 넣는다. iOS에는 채널 개념이 없어서 호출해도 바로 resolve된다.
• 즉시 표시: displayNotification({ title, body, android: { channelId, ... } }).
• 예약(트리거): createTriggerNotification(notification, trigger) — 특정 시각·간격에 띄운다.
• 보류 알림: 아직 안 뜬 트리거 알림은 TriggerNotification(notification + trigger) 형태로 관리한다. id 목록은 getTriggerNotificationIds()로 본다.

3. 바로 띄우기 — displayNotification

대략 흐름은 권한 → 채널 → 표시다.

import notifee from '@notifee/react-native';

async function onDisplayNotification() {
  await notifee.requestPermission(); // iOS 필수

  const channelId = await notifee.createChannel({
    id: 'default',
    name: 'Default Channel',
  });

  await notifee.displayNotification({
    title: '알림 제목',
    body: '본문 내용',
    android: {
      channelId,
      // smallIcon 생략 시 ic_launcher
      pressAction: { id: 'default' }, // 탭 시 앱 열기
    },
  });
}

같은 id로 다시 displayNotification을 호출하면 이미 떠 있는 알림을 갱신한다. 부분 필드만 넘기지 말고, 전체 payload를 새로 넘긴다. 지울 때는 cancelNotification(notificationId).

4. 예약 — createTriggerNotification / TriggerNotification

특정 시각에 띄우려면 TimestampTrigger를 쓴다.

import notifee, { TimestampTrigger, TriggerType, RepeatFrequency } from '@notifee/react-native';

const date = new Date();
date.setHours(11);
date.setMinutes(10);

const trigger: TimestampTrigger = {
  type: TriggerType.TIMESTAMP,
  timestamp: date.getTime(),
  // repeatFrequency: RepeatFrequency.WEEKLY, // 매주 반복
};

await notifee.createTriggerNotification(
  {
    title: '미팅 리마인더',
    body: '오늘 11:20',
    android: { channelId: 'your-channel-id' },
  },
  trigger,
);

• TriggerNotification: “아직 안 뜬 예약 알림”을 나타내는 인터페이스(알림 본문 + trigger).
• 대기 목록 id: getTriggerNotificationIds().
• 취소: cancelNotification(id) 또는 cancelTriggerNotifications() / cancelAllNotifications().
• Android에서 저전력 모드에도 맞추려면 alarmManager: { allowWhileIdle: true } 옵션을 본다.
• Android 12+는 정확한 알람 권한(SCHEDULE_EXACT_ALARM)이 없으면 타임스탬프 트리거를 못 만든다. getNotificationSettings()로 확인하고, 꺼져 있으면 openAlarmPermissionSettings()로 설정 화면을 연다.
• 시스템 한도: Android는 타임스탬프 트리거 동시 약 50개, iOS는 대략 64개 전후로 알려져 있다.

간격 반복은 IntervalTrigger(type: INTERVAL, interval + timeUnit)로 타이머처럼 쓸 수 있다.

5. 실무에서 자주 걸리는 점

• Android는 채널 없이 알림을 못 띄운다. 앱 시작 시 채널을 한 번 만들어 두는 편이 편하다.
• iOS 반복 트리거는 “첫 발화 시각” 해석이 Android와 다르다(시간·요일만 보고 시작일을 무시하는 식). 문서의 iOS Initial Trigger Limitations를 한 번 읽어 두는 게 좋다.
• 원격 푸시(서버 → FCM/APNs)는 Notifee만으로 끝내지 않고, Firebase Messaging 등과 역할을 나눠 쓴다. Notifee는 표시·채널·로컬 예약 쪽에 강하다.