메인 콘텐츠로 건너뛰기
웹사이트에 문제가 있는 경우 Web Push 문제 해결 가이드를 참조하세요.

​
문제 해결 단계

​
설정 지침 검토 및 SDK 업데이트

업데이트를 정기적으로 릴리스하여 버그 수정, 개선 사항 및 최신 운영 체제 변경 사항을 지원합니다. 최신 SDK 버전을 사용하고 설정 지침을 따랐는지 확인하세요.

Mobile SDK 설정

일반적인 문제를 방지하고 통합을 테스트하는 데 도움이 되는 설정 지침.

​
일반적인 문제 해결 가이드 확인

알림이 표시되지 않거나 지연됨

푸시 알림이 장치에 표시되지 않거나 지연됩니다.

알림 이미지가 표시되지 않음

이미지가 알림의 확장된 보기에 표시되지 않습니다.

알림 CTR

알림 클릭률이 낮거나 클릭이 없습니다.

중복 알림

알림이 장치에 여러 번 표시됩니다.

In-app 메시지 문제 해결

In-app 메시지가 예상대로 표시되거나 작동하지 않습니다.

​
앱의 일반적인 문제 확인

​
푸시 표시를 차단하는 OneSignal 메서드

OneSignal.User.pushSubscription.optOut() 같은 optOut() 메서드가 있는지, 또는 REST API를 통해 enabled: false로 설정했는지 확인하세요. 이렇게 하면 푸시 구독 상태가 unsubscribed로 설정됩니다. 자세한 내용은 Mobile SDK 참조를 참조하세요. 푸시가 전송되는 동안 앱이 열려 있는 경우 preventDefault() 메서드를 통해 푸시 표시를 차단하고 있을 수 있습니다. 이는 일반적으로 포그라운드 이벤트 리스너 또는 Android 알림 서비스 확장에서 설정됩니다.

​
Firebase Messaging 또는 다른 SDK 충돌

앱에 Firebase Messaging SDK 또는 다른 푸시 알림 SDK도 포함되어 있는 경우, OneSignal이 메시지를 처리하기 전에 해당 SDK가 메시지를 가로채지 않는지 확인하세요. 이 문제는 다음과 같은 경우에 흔히 발생합니다:
  • 알림이 OneSignal에서 배달됨으로 표시되지만 장치에 표시되지 않음.
  • 앱에 OneSignal과 firebase_messaging(또는 커스텀 FirebaseMessagingService)가 모두 포함되어 있음.
  • Firebase Messaging을 제거하면 푸시가 작동하지만 두 SDK가 모두 있을 때 실패함.
  1. AndroidManifest.xml에서 com.google.firebase.iid.FirebaseInstanceIdReceiver 같은 레거시 Firebase 수신기를 확인하고, OneSignal이 푸시 전달을 담당하는 경우 제거하거나 조건부로 제외하세요.
  2. onMessageReceived를 재정의하는 커스텀 FirebaseMessagingService 구현(또는 Flutter의 firebase_messaging 같은 라이브러리)이 없는지 확인하세요. 다른 서비스가 메시지를 완전히 처리하거나 억제하면 OneSignal이 알림을 표시하기 전에 FCM 페이로드를 소비할 수 있습니다.
  3. FirebaseMessaging.getToken() 또는 FirebaseMessaging.deleteToken() 같은 Firebase 토큰 관리 API 호출을 피하세요.
OneSignal이 푸시 전달을 담당하는 경우, 푸시 토큰 수명 주기를 관리하는 유일한 SDK여야 합니다. FCM 토큰을 직접 가져오거나 관리하면 토큰 소유권 충돌 및 일관성 없는 전달 동작이 발생할 수 있습니다. 다른 시스템을 위해 장치 푸시 토큰이 필요한 경우, OneSignal에서 읽고(예: User.pushSubscription.token) SDK의 옵저버 API를 사용하여 구독/토큰 변경을 수신하세요.

​
SDK용 예제 프로젝트 테스트

엔지니어링 팀에서 각 SDK용으로 유지 관리하는 예제 프로젝트를 사용하여 문제를 재현할 수 있는지 확인하세요.

​
오류 로그 확인

추가 진단 전에 로그 데이터를 수집하세요:
  • 디버그 로그 캡처 가이드를 따르세요.
  • 동작을 설명할 수 있는 오류, 경고 또는 사용 중단 알림을 찾으세요.

디버그 로그 캡처

자세한 로깅을 활성화하고 문제 해결을 위한 SDK 출력을 캡처하는 방법.

​
지원팀에 문의

여전히 문제가 있는 경우, support@onesignal.com에 다음 정보를 포함하여 문의하세요:
  • OneSignal App ID
  • 영향받는 장치의 External ID 및/또는 Subscription ID
  • 해당하는 경우 알림 ID 또는 대시보드의 알림 링크
  • 문제를 재현하는 장치의 디버그 로그

​
일반적인 오류

​
APNS Delegate never fired

“APNS Delegate Never Fired” 및 “APNS 3000”과 같은 오류는 Apple에서 제공하는 타임아웃 메시지로, 장치가 Apple의 APNS 서버에 연결할 수 없음을 나타냅니다. 다음과 같은 경우에 가장 일반적입니다:
  • APNS 개발 환경에서 테스트하는 경우
  • OneSignal과 함께 여러 푸시 알림 종속성 또는 네이티브 iOS 푸시 API를 사용하는 경우
  • 일시적인 연결 문제 — 사용자가 다음에 새 세션을 시작할 때(앱이 30초 이상 백그라운드에 있다가 다시 열림) 자동으로 해결되는 경우가 많습니다
해결 단계:
  1. 다른 푸시 알림 종속성 또는 네이티브 iOS 푸시 API를 제거하고 OneSignal만 사용하세요. 오류가 해결되면 다른 코드를 다시 추가할 수 있습니다. 공존 모범 사례는 support@onesignal.com에 문의하세요.
  2. 자세한 내용은 장치의 디버그 로그를 확인하세요.
  3. 오류가 지속되면 지원팀에 문의하세요.
Capacitor를 사용 중이라면 OneSignal이 푸시 알림을 처리할 수 있도록 이 설정을 추가하세요. 
{
  "ios": {
    "handleApplicationNotifications": false
  }
}

​
앱이 강제 종료되었을 때 알림을 클릭해도 앱이 열리지 않음

Debug 빌드에서 테스트하지 않는지 확인하세요. 예를 들어, Flutter 앱의 경우:
  • Flutter를 통해 릴리스 빌드를 사용합니다. 예: flutter run --release(물리적 장치 필요)
  • Xcode 스킴을 Debug가 아닌 Release로 업데이트합니다

​
관련 페이지

Mobile SDK 설정

지원되는 모든 모바일 및 크로스 플랫폼 SDK의 설정 지침.

디버그 로그 캡처

문제 해결을 위한 SDK 로그를 캡처하는 방법.

Web Push 문제 해결

웹 푸시 알림 문제를 해결합니다.

Mobile SDK 참조

OneSignal Mobile SDK의 전체 API 참조.

​
FAQ

​
앱에서 OneSignal App ID를 변경하면 어떻게 되나요?

앱의 초기화 코드에서 OneSignal App ID를 변경하면 사용자가 앱을 최신 버전으로 업데이트하고 열 때 새로운 App ID 아래에 완전히 새로운 사용자 및 푸시 Subscription이 생성됩니다. iOS 번들 ID 및/또는 Android 패키지 ID가 동일한 경우 장치는 동일한 푸시 Subscription 상태를 유지합니다. 사용자 데이터는 완전히 새로운 것이므로 새 레코드에 Alias, 태그, 이메일 주소, 전화번호를 다시 추가해야 합니다. iOS 번들 ID 또는 Android 패키지 ID가 다른 경우 이는 완전히 새로운 앱이며 다른 푸시 인증서/키가 있어야 합니다.

​
OneSignal이 온프레미스 폐쇄형 네트워크에서 푸시 알림을 보낼 수 있나요?

폐쇄형 네트워크의 컴퓨터가 지원하려는 푸시 게이트웨이 서버에 액세스할 수 있는 한 작동할 수 있습니다: 네트워크가 인터넷에서 완전히 분리된 경우 표준 OS/브라우저 서비스를 통해 푸시 알림을 전달할 수 없으며, 이는 당사가 지원하는 것입니다.