> ## 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.

# 데이터 및 백그라운드 알림

> iOS 및 Android에서 가시적인 메시지 없이 데이터를 동기화하거나 백그라운드 작업을 트리거하는 사일런트 푸시 알림을 전송합니다.

## 사일런트 알림이란 무엇인가요?

사일런트 알림을 사용하면 가시적인 메시지를 표시하거나 소리를 재생하지 않고도 앱을 깨우고 백그라운드 작업(예: 동기화 또는 데이터 새로 고침)을 수행할 수 있습니다.

iOS에서는 이를 **백그라운드 알림**이라고 하며, Android에서는 **데이터 알림**이라고 합니다. 이들을 통칭하여 사일런트 푸시라고 하며, 일반 가시 알림과는 다르게 동작합니다.

### 제한 사항

* **앱이 사일런트 푸시를 받을 수 없는 경우**:
  * **iOS**: 앱 전환기에서 스와이프하여 삭제할 때와 같이 사용자가 앱을 닫은 경우. ([Apple 지원](https://support.apple.com/en-us/HT201330) 참조).
  * **Android**: 기기 설정을 통해 앱이 강제 종료되었거나 스와이프하여 삭제할 때 일부 제조업체에 의해 자동으로 종료된 경우. ([자세한 내용](./notifications-show-successful-but-are-not-being-shown#android-app-is-force-stopped)).
* **전달이 보장되지 않음**:
  * Apple과 Google 모두 사일런트 알림을 *최선의 노력*으로 처리합니다. iOS는 저전력 모드, 백그라운드 앱 새로 고침 꺼짐 또는 사용자가 앱을 닫은 경우 전달을 지연하거나 삭제할 수 있습니다. Android는 Doze 또는 OEM 절전 규칙에 따라 전달을 제한하거나 일괄 처리할 수 있습니다.
  * 따라서 **사일런트 알림은 중요한 업데이트에 사용해서는 안 됩니다**.
* **구독된 사용자만**: OneSignal SDK는 구독된 [구독](./subscriptions)에만 데이터 알림을 보냅니다. 구독하지 않은 사용자에게 도달하려면 [이 해결 방법](https://github.com/OneSignal/OneSignal-iOS-SDK/issues/302)을 따르세요.
* **크로스 플랫폼 SDK에 대한 제한된 지원**:
  * 사일런트 알림은 네이티브 코드(Android용 Java/Kotlin, iOS용 Swift/Obj-C)에서 처리해야 합니다.
  * iOS는 [`application:didReceiveRemoteNotification:fetchCompletionHandler:`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application) 구현이 필요합니다.
  * Android는 [알림 서비스 확장](./service-extensions) 구현이 필요합니다.

***

## OneSignal에서 사일런트 알림 전송

OneSignal에서 사일런트 알림을 전송하려면 다음 단계를 따르세요:

<Steps>
  <Step title="가시적인 콘텐츠 생략">
    메시지에서 가시적인 텍스트나 제목을 제거합니다. 여기에는 다음이 포함됩니다:

    * **API**: [Create notification](/reference/create-message) API 요청의 `contents`, `headings`, `subtitle`.
    * **Dashboard**: Message, Title, Subtitle
  </Step>

  <Step title="content_available 설정">
    * **API**: `content_available`을 `true`로 설정.
    * **Dashboard**: "Send to Apple iOS"에서 **Content available**을 선택. 이것은 모든 플랫폼에 적용되며 메시지가 전송되지 않음을 시스템에 알립니다.
  </Step>

  <Step title="알림에 데이터 추가">
    * **API**: `data` 매개변수 사용.
    * **Dashboard**: **Additional Data** 필드 사용.
  </Step>
</Steps>

### API 페이로드 예시

```bash theme={null}
curl -X POST https://api.onesignal.com/notifications \
  -H "Authorization: Key YOUR_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "include_aliases": { "external_id": ["user-123"] },
    "target_channel": "push",
    "content_available": true,
    "data": {
      "action": "sync_data",
      "version": "2"
    }
  }'
```

***

## 플랫폼별 설정

### iOS 백그라운드 알림 설정

백그라운드 알림을 처리하려면 iOS 앱에서 Xcode의 **Background Modes > Remote Notifications** 기능을 활성화해야 합니다. 이는 [모바일 SDK 설정](./mobile-sdk-setup)을 따랐다면 일반적으로 포함됩니다.

알림을 처리하려면 `AppDelegate` 메서드 [`application(_:didReceiveRemoteNotification:fetchCompletionHandler:)`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application)를 구현하세요.

Apple 문서:

* [Pushing Background Updates to Your App](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app?language=objc)
* [Generating a Remote Notification](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification)

<Warning>
  사용자가 앱을 닫은 경우(앱 전환기에서 스와이프하여 삭제) iOS는 알림을 전달하지 않습니다.

  이러한 경우 가시적인 `contents` 메시지를 포함하고 [`UNNotificationServiceExtension.didReceive`](./service-extensions#ios-notification-service-extension)에서 데이터를 처리하세요.
</Warning>

***

### Android 데이터 알림 설정

[알림 서비스 확장](./service-extensions)을 사용하여 Android에서 데이터 알림을 처리합니다.

이를 통해:

* 앱이 강제 종료되지 않은 경우 알림 처리
* 알림 표시 또는 억제 방법 사용자 지정

Android 문서:

* [FCM 데이터 메시지](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages)
* [Doze 및 앱 대기 상태 최적화](https://developer.android.com/training/monitoring-device-state/doze-standby)

<Warning>
  앱이 강제 종료된 경우(기기 설정 또는 일부 OEM 배터리 최적화에 의해), Android는 알림을 전달하지 않습니다. [Android 강제 종료 동작](./notifications-show-successful-but-are-not-being-shown#android-app-is-force-stopped)을 참조하세요.
</Warning>

***

## VoIP 알림 전송

VoIP 알림은 지원되지만 표준 OneSignal SDK 외부에서 추가 구성이 필요합니다. OneSignal은 VoIP 토큰을 자동으로 등록하지 않습니다.

<Card title="VoIP 알림 설정 가이드" icon="phone" href="./voip-notifications">
  iOS에서 실시간 통화를 위한 VoIP 푸시 알림을 구성합니다.
</Card>

***

## FAQ

### 사일런트 알림을 사용하여 제거 또는 구독 취소를 감지할 수 있나요?

기술적으로는 가능하지만 신뢰할 수 없습니다. 위의 [제한 사항](#제한-사항) 섹션에서 설명한 것처럼 사일런트 알림의 전달은 보장되지 않습니다.

대신:

* 한 달에 한 번 이상 모든 사용자에게 가시적인 알림(콘텐츠 포함)을 보내세요.
* 선택적으로 사일런트 알림을 보완 확인으로 보내세요.

구독 상태 변경 처리에 대한 자세한 내용은 [구독](./subscriptions) 가이드를 참조하세요.

### 확인된 전달이 사일런트 알림과 작동하나요?

확인된 전달은 사일런트 알림과 작동하지 않습니다.

### 사일런트 알림을 사용하여 도달 가능한 사용자 수를 측정할 수 있나요?

아니요, 신뢰할 수 없습니다. 사일런트 알림은 전달이 보장되지 않습니다.

1. **전달이 보장되지 않음** — Apple과 Google 모두 사일런트 알림을 최선의 노력으로 처리하며 지연하거나 삭제할 수 있습니다. 예를 들어 앱이 닫혀 있는 경우(강제 종료) iOS는 삭제하고, Android와 iOS는 절전 규칙에 따라 제한합니다.

2. **전달이 확인되지 않음** — 확인된 전달은 사일런트 알림에서 작동하지 않으므로 어떤 사용자가 실제로 푸시를 받았는지 알 수 없습니다.

도달 가능한 사용자를 측정하려면 가시적인 알림을 보내고 [Analytics](./analytics-overview)에서 전달 지표를 추적하세요.

***

<Columns cols={2}>
  <Card title="서비스 확장" icon="puzzle-piece" href="./service-extensions">
    iOS 및 Android에서 네이티브 코드로 알림 처리를 다룹니다.
  </Card>

  <Card title="구독" icon="address-book" href="./subscriptions">
    구독 유형과 사용자와의 연결 방법을 이해합니다.
  </Card>

  <Card title="메시지 생성 API" icon="code" href="/reference/create-message">
    사일런트 푸시를 포함한 알림을 프로그래밍 방식으로 전송합니다.
  </Card>
</Columns>