- 전달됨은 OneSignal이 알림을 푸시 서비스(FCM, APNs 또는 HMS)에 성공적으로 전달하고 성공 응답을 받았음을 의미합니다.
- 확인됨은 기기의 OneSignal SDK가 알림을 수신했음을 의미합니다.
시작하기 전에
문제 해결에 도움이 되도록 다음 정보를 수집하세요. 올바른 구독을 식별하고 전달 상태를 확인하는 데 필요합니다.- OneSignal App ID
- 표시되지 않은 알림의 Message ID
- 영향받은 사용자의 Subscription ID
External ID만 있는 경우 Audience > Subscriptions에서 Device Type, Last Session 또는 IP Address로 필터링하여 구독을 찾으세요.
기기 설정
이 섹션은 모든 플랫폼에 적용됩니다. 플랫폼별 또는 코드 수준 원인을 조사하기 전에 먼저 이것을 확인하세요.권한 및 구독 상태
기기에서:- 설정 > 알림으로 이동하여 앱의 알림 설정을 엽니다.
- 알림 권한이 활성화되어 있는지 확인합니다.
- 그런 다음 앱을 여세요. SDK가 초기화되면 구독 상태를 OneSignal에 다시 동기화합니다.
- Audience > Subscriptions으로 이동합니다.
- Subscription ID 또는 External ID로 검색하거나 Device Type, Last Session 또는 IP Address로 정렬합니다.
- 푸시 상태가 Subscribed로 표시되는지 확인합니다. 구독 취소로 표시되거나 나타나지 않으면 무엇을 보내도 기기는 알림을 받지 못합니다. 상태가 예상과 다른 경우 아래 문제 해결을 참조하세요.
방해 금지 및 집중 모드
Android와 iOS의 방해 금지 및 집중 모드는 알림을 완전히 억제하거나 모드가 해제될 때까지 보이지 않는 방식으로 그룹화할 수 있습니다. 테스트 전에 이 모드를 비활성화하세요:- iOS: 설정 > 집중 > 방해 금지 > 끄기
- Android: 설정 > 알림 > 방해 금지 > 끄기
iOS에서 집중 모드 중에 알림이 도착하고 사용자가 그룹화된 알림 요약을 스와이프하여 닫으면 해당 알림은 나중에 개별적으로 다시 나타나지 않습니다.
저전력 모드 및 배터리 최적화
iOS: 테스트 전에 설정 > 배터리에서 저전력 모드를 비활성화합니다. Android 기기: 배터리 설정에서 앱을 “제한 없음” 또는 “최적화 안함”으로 설정합니다. 해당 옵션이 없으면 배터리 최적화, 절전 모드, 에너지 절약, 백그라운드 사용 제한 또는 적응형 배터리 설정을 검색하여 앱에 대해 비활성화하세요.네트워크 및 연결
기기는 푸시 알림을 받으려면 온라인 상태여야 합니다. 기기가 꺼져 있거나 비행기 모드이거나 불안정하거나 인터넷 연결이 없는 경우 적절한 연결이 이루어질 때까지 푸시가 표시되지 않습니다. FCM과 APNs가 연결을 기다리는 기간은 Time To Live (TTL) 매개변수로 설정할 수 있습니다(기본값은 3일). 방화벽이나 VPN이 있는 WiFi 네트워크의 기기는 Apple 또는 Google 서버 연결이 차단될 수 있습니다. 모바일 데이터로 전환하여 테스트하세요. 방화벽을 통해 네트워크 트래픽을 관리하는 경우 다음을 허용하도록 구성하세요:- FCM (Android): 아웃바운드 TCP 포트 5228, 5229, 5230. 전체 요구 사항은 FCM 문서를 참조하세요.
- APNs (iOS): 아웃바운드 TCP 포트 5223 및 TCP 포트 443 또는 2197. 전체 요구 사항은 Apple 문서를 참조하세요.
알림 그룹화 동작
Android와 iOS의 다른 버전에는 각자의 알림 그룹화 동작이 있습니다. 알림 그룹화는 동일한 앱 또는 여러 앱의 알림이 알림 센터에서 함께 묶이는 경우입니다. 그룹화된 알림이 함께 닫히면 사용자가 개별 알림을 놓치는 것이 일반적입니다.Android 문제
이 섹션은 Android 기기에만 적용됩니다. iOS 문제를 해결하는 경우 iOS 문제로 건너뛰세요.Android 강제 중지
Android 앱이 강제 중지되면 OS는 사용자가 수동으로 다시 열 때까지 푸시 알림 수신을 차단합니다. 이것은 Android에서 알림이 누락되는 가장 일반적인 원인 중 하나입니다. Samsung, Xiaomi, Huawei를 포함한 일부 제조업체는 사용자가 최근 앱 목록에서 앱을 스와이프하면 앱을 적극적으로 강제 중지하지만 Gmail, WhatsApp과 같은 대형 앱은 제외합니다. 기기별 동작은 dontkillmyapp.com을 참조하세요. 영향받은 기기의 강제 중지 동작을 줄이려면 다음 단계를 순서대로 시도하세요:- 백그라운드 활동 허용: Settings > Apps > Your App > Battery > Allow background activity.
- Sleeping Apps 비활성화: Settings > Battery and Device Care > Battery > Background Usage Limits > Sleeping Apps > 이 목록에서 앱을 제거합니다.
- Recent Apps에서 앱 잠금: 앱을 열고 Recent Apps 버튼을 탭한 다음 앱 창을 길게 눌러 Lock this app을 선택합니다(일부 Samsung 모델에서 사용 가능).
- Auto-Start 활성화 (일부 기기): Settings > Apps > Your App > Permissions > Auto-Start > Enable.
- Adaptive Battery Optimization 비활성화: Settings > Battery and Device Care > Battery > More Battery Settings > Adaptive Battery > 끄기(또는 앱 제외).
com.company.appname을 패키지 이름으로 바꾸세요:
stopped=false는 앱이 강제 중지되지 않았음을 의미합니다. stopped=true는 강제 중지되었음을 의미합니다.
몇 개의 알림을 보내고 logcat에서 이 항목을 확인할 수도 있습니다:
FCM은 기기가 FCM 서버에 마지막으로 연결된 시간을 확인하는 API를 제공합니다. 이를 통해 기기가 전혀 도달 가능한지 확인할 수 있습니다. 자세한 내용은 앱 인스턴스 정보에 관한 Google 문서를 참조하세요.사용자가 스스로 해결할 수 있도록 앱 내 메시지를 사용하여 알려진 Android 기기 사용자에게 백그라운드 활동 활성화 방법을 안내하세요. 예: 특정 Android 제조업체 및 기기 타겟팅을 참조하세요.
Android 알림 카테고리 비활성화
Android 알림 카테고리(채널이라고도 함)를 사용하면 사용자가 앱의 특정 유형의 알림을 비활성화할 수 있습니다. 카테고리가 비활성화되면 해당 카테고리로 전송된 알림은 기기에 표시되지 않습니다 — 앱에 알림 권한이 있어도 마찬가지입니다. 기기에서 카테고리 상태 확인: 설정 > 알림 > 앱. “알림 표시”가 활성화되어 있고 모든 카테고리가 켜져 있는지 확인하세요.
앱 내 메시지를 사용하여 Samsung 사용자에게 카테고리 재활성화 방법을 안내할 수 있습니다. 예: 특정 Android 제조업체 및 기기 타겟팅을 참조하세요.
Android Doze 모드, 우선순위 및 우선순위 낮춤 메시지
Android의 Doze 모드 및 App Standby 기능은 기기가 플러그를 뽑고 정지 상태일 때 백그라운드 프로세스(푸시 전달 포함)를 지연시킵니다. 이 모드는 자동으로 활성화되며 사용자에게는 보이지 않습니다. 높은 우선순위 메시지를 보내면 기기가 깨어나 Doze 모드를 우회합니다. 그러나 표시 가능한 알림을 생성하지 않는 높은 우선순위 메시지를 너무 많이 보내면 FCM이 자동으로 메시지를 일반 우선순위로 낮출 수 있습니다. FCM 문서에서:Android의 높은 우선순위 메시지는 시간에 민감한 사용자 표시 콘텐츠를 위한 것입니다. FCM이 메시지가 사용자 대면 알림을 생성하지 않는 패턴을 감지하면 메시지의 우선순위가 일반 우선순위로 낮아질 수 있습니다.우선순위 낮춤이 의심되면 높은 우선순위 사용을 시간에 민감한 메시지로만 제한하세요.
Android 에뮬레이터 설정
Android 에뮬레이터에서 푸시 알림을 받으려면 Google Play Services가 필요합니다. 에뮬레이터에서 테스트 중인데 알림을 받지 못하면 다음을 확인하세요:- 에뮬레이터 이미지에 Google Play Store가 포함되어 있을 것
- 에뮬레이터가 Cold Boot를 사용하도록 구성되어 있을 것
iOS 문제
이 섹션은 iOS 기기에만 적용됩니다. Android 문제를 해결하는 경우 Android 문제를 참조하세요.APNs 알림 병합
iOS 기기가 오프라인이거나 연결할 수 없는 동안 여러 알림이 전송된 경우, 기기가 다시 연결되면 가장 최근 알림만 표시될 수 있습니다. APNs는 기기가 오프라인인 동안 앱당 하나의 알림만 저장하고 이전 알림은 삭제합니다. 이는 예상된 APNs 동작이며 OneSignal이나 앱에서 변경할 수 없습니다.iOS 포그라운드 차단
iOS UNUserNotificationCenterDelegate를 설정한 경우 앱이 포그라운드에 있는 동안 알림 표시를 차단하는 코드가 있을 수 있습니다. 이 커스텀 코드를 제거하고 대신 SDK의 Foreground Event Listener를 사용하세요.iOS 배지 지우기
앱이 배지 카운트를 지우면 iOS는 알림 센터에서 해당 앱의 모든 알림을 제거합니다. OneSignal SDK는 앱이 열릴 때 자동으로 배지를 지우므로 이전에 전달된 알림이 사용자가 다음에 앱을 열 때 사라질 수 있습니다. 테스트 중에 이것이 혼란을 일으키는 경우 이 동작을 제어하는 방법은 Badges를 참조하세요.메시지 구성
이 섹션은 기기가 아닌 OneSignal에서 알림이 구성된 방식으로 인한 문제를 다룹니다.구독이 타겟 오디언스에 없음
메시지 오디언스를 확인하여 모바일 구독이 포함되어 있는지 확인하세요:- 세그먼트: 구독이 모든 오디언스 필터 조건을 충족하는지 확인합니다.
- 직접 전송: 타겟팅하는 ID가 올바른지 확인합니다:
- 구독이 여전히 푸시를 구독하고 있을 것.
- 최근 마지막 세션 날짜가 있을 것 — 오래되거나 비활성 구독으로 보내고 있을 수 있습니다.
Collapse ID로 인한 알림 교체
메시지에 Collapse ID를 설정하는 경우 동일한 Collapse ID를 가진 새 알림이 해당 ID의 읽지 않은 알림을 자동으로 교체합니다. 사용자가 이전 알림을 열지 않았다면 최신 알림만 보게 됩니다. Collapse ID 작동 방식에 대한 자세한 내용은 알림 제거 및 TTL을 참조하세요.코드 수준 원인
이 섹션은 앱의 소스 코드에 대한 접근이 필요합니다. 코드 접근 권한이 없는 경우 이 확인 사항을 개발팀과 공유하세요.OneSignal 포그라운드 알림 방지
OneSignal SDK의 Foreground Event Listener에는 앱이 포그라운드에 있는 동안 알림을 억제하는event.preventDefault() 메서드가 포함되어 있습니다. 이 메서드가 코드에서 무조건적으로 호출되면 모든 포그라운드 알림이 자동으로 차단됩니다.
테스트 시 포그라운드 억제를 원인으로 배제하기 위해 앱을 백그라운드에 두거나 완전히 닫아두세요.
Android Notification Service Extension
Android Notification Service Extension을 구현한 경우 이것이 앱에서 수신 알림의 첫 번째 진입점입니다. 이 Extension 내에서event.preventDefault()가 호출되면 앱 상태와 관계없이 알림이 차단됩니다. Extension 코드를 검토하고 이 메서드가 의도적으로만 호출되는지 확인하세요.
Firebase Messaging SDK 충돌
앱에 Firebase Messaging SDK도 포함되어 있다면, OneSignal이 FCM 메시지를 처리하기 전에 Firebase가 이를 가로채고 있지 않은지 확인하세요. 이 문제는 주로 다음 경우에 발생합니다:- OneSignal에서 알림이 전달됨으로 표시되지만 기기에는 나타나지 않습니다.
- 앱에 OneSignal과
firebase_messaging(또는 커스텀FirebaseMessagingService)이 모두 포함되어 있습니다. - Firebase Messaging을 제거하면 푸시가 작동하지만, 두 SDK가 모두 있으면 실패합니다.
-
AndroidManifest.xml에서com.google.firebase.iid.FirebaseInstanceIdReceiver와 같은 레거시 Firebase 리시버를 확인하고, OneSignal이 푸시 전달을 담당하는 경우 제거하거나 조건부로 제외하세요. -
onMessageReceived를 재정의하는 커스텀FirebaseMessagingService구현(또는 Flutter의firebase_messaging과 같은 라이브러리)을 확인하세요. 다른 서비스가 메시지를 완전히 처리하거나 억제하면 OneSignal이 알림을 표시하기 전에 FCM 페이로드를 소비할 수 있습니다. -
FirebaseMessaging.getToken()또는FirebaseMessaging.deleteToken()과 같은 Firebase 토큰 관리 API 호출을 피하세요.
User.pushSubscription.token). 그리고 SDK의 옵저버 API를 사용하여 구독/토큰 변경을 감지하세요.
문제 해결
위 섹션을 검토했지만 문제가 해결되지 않은 경우 디버그 로그를 캡처하세요. 이것이 전달이 실패하는 위치를 정확히 파악하는 가장 빠른 방법입니다. 디버그 로그 받기에 따라 앱에서 상세 로깅을 활성화하세요. 그런 다음:- 앱을 백그라운드에 두기
- 영향받은 기기에 테스트 알림 보내기
- 오류가 있는지 로그 확인. OneSignal이 초기화되었고 로그의
subscription-id가 푸시를 구독하고 있으며 메시지를 보내는 것과 동일한지 확인하세요.
도움이 필요하신가요?
support@onesignal.com의 지원팀에 문의하세요다음 내용을 포함해 주세요:- OneSignal App ID
- Subscription ID 또는 External ID
- OneSignal 대시보드에서 테스트한 메시지의 URL
- 디버그 로그 받기의 전체 디버그 로그