> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile SDK 문제 해결

> OneSignal Mobile SDK의 일반적인 문제를 해결하세요. iOS, Android 및 크로스 플랫폼 프레임워크 전반에 걸친 푸시 전달 실패, APNS 오류 및 인앱 메시지 문제가 포함됩니다.

<Note>
  웹사이트에 문제가 있는 경우 [Web Push 문제 해결 가이드](./troubleshooting-web-push)를 참조하세요.
</Note>

## 문제 해결 단계

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

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

<Card title="Mobile SDK 설정" icon="wrench" href="./mobile-sdk-setup">
  일반적인 문제를 방지하고 통합을 테스트하는 데 도움이 되는 설정 지침.
</Card>

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

<Columns cols={2}>
  <Card title="알림이 표시되지 않거나 지연됨" icon="bell-slash" href="./notifications-show-successful-but-are-not-being-shown">
    푸시 알림이 장치에 표시되지 않거나 지연됩니다.
  </Card>

  <Card title="알림 이미지가 표시되지 않음" icon="image" href="./notification-images-not-showing">
    이미지가 알림의 확장된 보기에 표시되지 않습니다.
  </Card>

  <Card title="알림 CTR" icon="arrow-pointer" href="./notification-ctr">
    알림 클릭률이 낮거나 클릭이 없습니다.
  </Card>

  <Card title="중복 알림" icon="copy" href="./duplicated-notifications">
    알림이 장치에 여러 번 표시됩니다.
  </Card>

  <Card title="In-app 메시지 문제 해결" icon="message" href="./in-app-message-troubleshooting">
    In-app 메시지가 예상대로 표시되거나 작동하지 않습니다.
  </Card>
</Columns>

### 앱의 일반적인 문제 확인

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

`OneSignal.User.pushSubscription.optOut()` 같은 `optOut()` 메서드가 있는지, 또는 REST API를 통해 `enabled: false`로 설정했는지 확인하세요. 이렇게 하면 푸시 구독 상태가 `unsubscribed`로 설정됩니다. 자세한 내용은 [Mobile SDK 참조](./mobile-sdk-reference#optout-%2C-optin-%2C-optedin)를 참조하세요.

푸시가 전송되는 동안 앱이 열려 있는 경우 `preventDefault()` 메서드를 통해 푸시 표시를 차단하고 있을 수 있습니다. 이는 일반적으로 [포그라운드 이벤트 리스너](./mobile-sdk-reference#addforegroundlifecyclelistener-push) 또는 [Android 알림 서비스 확장](./service-extensions)에서 설정됩니다.

#### 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](./mobile-sdk-reference#addobserver-push-subscription-changes)를 사용하여 구독/토큰 변경을 수신하세요.

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

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

* [iOS 예제 프로젝트](https://github.com/OneSignal/OneSignal-iOS-SDK/tree/main/OneSignalSwiftUIExample)
* [Android 예제 프로젝트](https://github.com/OneSignal/OneSignal-Android-SDK/tree/main/examples)
* [Cordova variants 예제 프로젝트](https://github.com/OneSignal/OneSignal-Cordova-SDK/tree/main/examples)
* [React Native 예제 프로젝트](https://github.com/OneSignal/react-native-onesignal/tree/main/examples)
* [Flutter 예제 프로젝트](https://github.com/OneSignal/OneSignal-Flutter-SDK/tree/main/examples)
* [Unity 예제 프로젝트](https://github.com/OneSignal/OneSignal-Unity-SDK/tree/main/examples)
* [.NET MAUI 예제 프로젝트](https://github.com/OneSignal/OneSignal-DotNet-SDK/tree/main/examples)

### 오류 로그 확인

추가 진단 전에 로그 데이터를 수집하세요:

* [디버그 로그 캡처](./capturing-a-debug-log) 가이드를 따르세요.
* 동작을 설명할 수 있는 오류, 경고 또는 사용 중단 알림을 찾으세요.

<Card title="디버그 로그 캡처" icon="bug" href="./capturing-a-debug-log">
  자세한 로깅을 활성화하고 문제 해결을 위한 SDK 출력을 캡처하는 방법.
</Card>

### 지원팀에 문의

여전히 문제가 있는 경우, `support@onesignal.com`에 다음 정보를 포함하여 문의하세요:

* OneSignal App ID
* 영향받는 장치의 External ID 및/또는 Subscription ID
* 해당하는 경우 알림 ID 또는 대시보드의 알림 링크
* 문제를 재현하는 [장치의 디버그 로그](./capturing-a-debug-log)

***

## 일반적인 오류

### 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. 자세한 내용은 [장치의 디버그 로그](./capturing-a-debug-log)를 확인하세요.
3. 오류가 지속되면 [지원팀에 문의](#문제-해결-단계)하세요.

Capacitor를 사용 중이라면 OneSignal이 푸시 알림을 처리할 수 있도록 이 설정을 추가하세요.

<CodeGroup>
  ```json json theme={null}
  {
    "ios": {
      "handleApplicationNotifications": false
    }
  }
  ```

  ```typescript capacitor.config.ts theme={null}
  const config: CapacitorConfig = {
    // ... additional configuration

    ios: {
      // ... additional configuration
      handleApplicationNotifications: false
    }
  };
  ```
</CodeGroup>

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

`Debug` 빌드에서 테스트하지 않는지 확인하세요. 예를 들어, Flutter 앱의 경우:

* Flutter를 통해 릴리스 빌드를 사용합니다. 예: `flutter run --release`(물리적 장치 필요)
* Xcode 스킴을 `Debug`가 아닌 `Release`로 업데이트합니다

***

## 관련 페이지

<Columns cols={2}>
  <Card title="Mobile SDK 설정" icon="wrench" href="./mobile-sdk-setup">
    지원되는 모든 모바일 및 크로스 플랫폼 SDK의 설정 지침.
  </Card>

  <Card title="디버그 로그 캡처" icon="bug" href="./capturing-a-debug-log">
    문제 해결을 위한 SDK 로그를 캡처하는 방법.
  </Card>

  <Card title="Web Push 문제 해결" icon="globe" href="./troubleshooting-web-push">
    웹 푸시 알림 문제를 해결합니다.
  </Card>

  <Card title="Mobile SDK 참조" icon="book" href="./mobile-sdk-reference">
    OneSignal Mobile SDK의 전체 API 참조.
  </Card>
</Columns>

***

## FAQ

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

앱의 초기화 코드에서 OneSignal App ID를 변경하면 사용자가 앱을 최신 버전으로 업데이트하고 열 때 새로운 App ID 아래에 완전히 새로운 사용자 및 푸시 Subscription이 생성됩니다.

iOS 번들 ID 및/또는 Android 패키지 ID가 동일한 경우 장치는 동일한 푸시 Subscription 상태를 유지합니다. 사용자 데이터는 완전히 새로운 것이므로 새 레코드에 Alias, 태그, 이메일 주소, 전화번호를 다시 추가해야 합니다.

iOS 번들 ID 또는 Android 패키지 ID가 다른 경우 이는 완전히 새로운 앱이며 다른 푸시 인증서/키가 있어야 합니다.

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

폐쇄형 네트워크의 컴퓨터가 지원하려는 푸시 게이트웨이 서버에 액세스할 수 있는 한 작동할 수 있습니다:

* [https://support.apple.com/en-us/HT203609](https://support.apple.com/en-us/HT203609)
* [https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

네트워크가 인터넷에서 완전히 분리된 경우 표준 OS/브라우저 서비스를 통해 푸시 알림을 전달할 수 없으며, 이는 당사가 지원하는 것입니다.

***