> ## 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.
# OSNotification payload
> 모든 payload 필드, Android 및 iOS 특정 속성, 사용자 지정 데이터 및 클릭 동작을 포함한 OneSignal의 OSNotification 객체에 대한 참조입니다.
`OSNotification` 클래스는 OneSignal SDK에서 푸시 알림 payload를 나타냅니다. 앱에서 알림을 처리할 때 알림 제목, 본문, 사용자 지정 데이터, 플랫폼별 속성에 액세스하는 데 사용하세요.
푸시 알림 payload는 `4096`바이트로 제한됩니다. 잘림을 방지하려면 payload를 `3500`바이트 미만으로 유지하세요. `additionalData` 필드는 `2048`바이트로 제한됩니다.
***
## 앱에서 `OSNotification`에 액세스
모든 OneSignal SDK는 `OSNotification` 객체를 반환하는 알림 이벤트 리스너를 제공합니다:
* **Android**: [notification lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) 사용
* **iOS**: [notification lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) 또는 `UNNotificationServiceExtension` 사용
### Android 필드
| Property | Type | Description |
| ---------------------------- | :---------------------: | ---------------------------------------------------------------- |
| `getBody()` | `String` | 알림의 본문 텍스트입니다. |
| `getTitle()` | `String` | 알림의 제목입니다. |
| `getLaunchURL()` | `String` | 알림을 클릭할 때 열리는 URL입니다. |
| `getNotificationId()` | `String` | OneSignal 알림 UUID입니다. |
| `getAdditionalData()` | `JSONObject` | 대시보드 또는 REST API를 통해 설정된 사용자 지정 key-value 데이터입니다. 최대 2048바이트입니다. |
| `getTemplateId()` | `String` | 템플릿을 사용하여 보낸 경우 템플릿 UUID입니다. |
| `getAndroidNotificationId()` | `int` | Android 기본 알림 ID입니다. |
| `getLargeIcon()` | `String` | Large icon의 URL 또는 리소스 이름입니다. |
| `getSmallIcon()` | `String` | Small icon 리소스 이름입니다. |
| `getSmallIconAccentColor()` | `String` | ARGB 형식의 아이콘 강조 색상입니다. |
| `getSound()` | `String` | 재생되는 사운드 리소스 이름입니다. |
| `getCollapseId()` | `String` | 알림 교체를 위한 Collapse key입니다. |
| `getPriority()` | `int` | Android 우선순위(-2에서 2)입니다. |
| `getLedColor()` | `String` | ARGB 형식의 LED 색상입니다. |
| `getLockScreenVisibility()` | `int` | 잠금 화면 가시성: `1 = public`, `0 = private`, `-1 = secret`입니다. |
| `getFromProjectNumber()` | `String` | 발신자 프로젝트 번호입니다. |
| `getGroupedNotifications()` | `List` | 요약에 포함된 알림입니다. |
| `getGroupKey()` | `String` | 요약에 사용되는 그룹 key입니다. |
| `getGroupMessage()` | `String` | 요약 텍스트입니다. |
| `getBackgroundImageLayout()` | `BackgroundImageLayout` | 배경 이미지 레이아웃 및 텍스트 색상에 대한 객체입니다. |
| `getActionButtons()` | `List` | 아이콘, 텍스트 및 ID가 있는 Action 버튼입니다. |
| `getRawPayload()` | `String` | payload의 전체 원시 JSON 문자열입니다. |
### iOS 필드
| Property | Type | Description |
| ------------------ | :------------: | ------------------------------------------------------------------- |
| `body` | `NSString` | 알림의 본문 텍스트입니다. |
| `title` | `NSString` | 알림의 제목입니다. |
| `launchURL` | `NSString` | 알림을 클릭할 때 열리는 URL입니다. |
| `notificationId` | `NSString` | OneSignal 알림 UUID입니다. |
| `additionalData` | `Dictionary` | 대시보드 또는 REST API를 통해 설정된 사용자 지정 key-value `data`입니다. 최대 2048바이트입니다. |
| `templateId` | `NSString` | 템플릿을 사용하여 보낸 경우 템플릿 UUID입니다. |
| `subtitle` | `NSString` | 부제목 텍스트입니다. |
| `category` | `NSString` | iOS 카테고리 식별자입니다. |
| `threadId` | `NSString` | 알림을 스레드로 그룹화하는 데 사용됩니다(iOS 10+). |
| `badge` | `NSInteger` | 절대 배지 값입니다. |
| `badgeIncrement` | `NSInteger` | 배지를 증가시킬 양입니다. |
| `contentAvailable` | `BOOL` | `content-available=1`이면 백그라운드 fetch를 트리거합니다. |
| `mutableContent` | `BOOL` | `mutable-content=1`이면 Notification Service Extension을 트리거합니다. |
| `actionButtons` | `NSArray` | iOS Action 버튼입니다. |
| `rawPayload` | `NSDictionary` | payload의 전체 원시 JSON입니다. |
| `parseWithApns` | *Method* | 원시 APNS payload를 OSNotification으로 변환합니다. Service Extension에서 사용합니다. |
***
## `OSNotificationAction` (클릭 이벤트)
알림과의 사용자 상호 작용을 설명합니다.
| Property | Type | Description |
| ---------- | :------: | ----------------------------------------- |
| `actionId` | `String` | 클릭된 Action 버튼의 ID입니다. |
| `type` | `enum` | `Opened`(기본 탭) 또는 `ActionTaken`(버튼 탭)입니다. |
***
## 사용자 지정 OneSignal payload 구조
모든 OneSignal 알림은 payload에 특별한 `"custom"` 객체를 포함합니다:
```json theme={null}
{
"custom": {
"i": "the-notification-id"
}
}
```
이 key는 OneSignal SDK가 알림을 처리하는 데 필요합니다. 누락된 경우 알림이 클릭 이벤트 또는 Analytics를 트리거하지 않습니다. OneSignal을 사용하는 디바이스에 다른 서비스에서 푸시를 보내는 경우, 중복 처리를 방지하기 위해 이 key로 필터링하세요. 자세한 내용은 [Push payload handling](./migrating-to-onesignal#push-payload-handling)을 참조하세요.
***
## additionalData를 APNS 루트로 이동
iOS 앱의 경우 `additionalData` 필드를 `custom` 딕셔너리 내부 대신 APNS payload의 루트에 배치할 수 있습니다. 이렇게 하면 사용자 지정 알림 핸들러에서 더 간편하게 액세스할 수 있습니다.
**1. API를 통해 활성화**
[Update an app API](/reference/update-an-app)를 사용하여 다음을 설정하세요:
```json theme={null}
{
"additional_data_is_root_payload": true
}
```
**2. `data`로 푸시 전송**
`data` 필드가 APNS 루트 payload에 표시됩니다:
```json theme={null}
{
"aps": {
"alert": { "title": "Sale", "body": "20% off all items!" }
},
"promo_code": "SPRING20"
}
```
이제 `custom` 딕셔너리를 확인하지 않고 `promo_code`에 직접 액세스할 수 있습니다.
***
## 복원된 알림 (Android)
Android SDK는 디바이스 재부팅 또는 앱 재시작 후 알림을 복원합니다.
| Property | Type | Description |
| ----------- | :-------: | ---------------------------------- |
| `restoring` | `boolean` | 디바이스/앱 재시작 후 알림이 복원된 경우 `true`입니다. |
복원된 알림을 건너뛰려면 `restoring` 플래그를 확인하세요. 오래된 알림이 완전히 복원되지 않도록 하려면 전송 시 짧거나 `0`인 TTL(time-to-live)을 설정하세요.
***
## 푸시 토큰 형식
* **iOS Push (APNS)**: 64자, 16진수 전용(0-9, a-f). `deviceToken.map {String(format: "%02x", $0)}.joined()`
* **Android Push (FCM)**: 일반적으로 163자, 영숫자이며 하이픈, 콜론, 밑줄을 포함할 수 있습니다.
***
## FAQ
### 최대 payload 크기는 얼마인가요?
푸시 알림 payload는 총 4096바이트로 제한됩니다. `additionalData` 필드는 2048바이트로 제한됩니다. 잘림을 방지하려면 전체 payload를 3500바이트 미만으로 유지하세요.
### 원시 payload에서 OneSignal 알림을 어떻게 식별하나요?
모든 OneSignal 알림은 알림 ID가 포함된 `"i"` key를 가진 `"custom"` 객체를 포함합니다. 이 key를 확인하여 OneSignal 알림과 다른 제공업체가 보낸 알림을 구별하세요.
### APNS 루트 payload에서 additionalData에 액세스할 수 있나요?
네. [Update an app API](/reference/update-an-app)를 통해 `additional_data_is_root_payload`를 활성화하면 `custom` 딕셔너리 내부 대신 APNS 루트에 `additionalData` 필드를 배치할 수 있습니다. 자세한 내용은 [additionalData를 APNS 루트로 이동](#move-additionaldata-to-apns-root)을 참조하세요.
***
Android 8.0 이상 디바이스용 알림 채널을 구성합니다.
리치 미디어, 배지, 확인된 전달 추적을 추가합니다.
OneSignal 모바일 SDK 메서드 및 리스너에 대한 전체 참조입니다.