OSNotification payload 참조
이 페이지에서는 OSNotification 클래스를 통한 OneSignal 푸시 알림 payload의 구조와 필드를 설명합니다. 모바일 앱에서 알림을 받거나 처리할 때 이 참조를 사용하세요.
푸시 알림 payload는 4096바이트로 제한됩니다. 잘림을 방지하려면 payload를 3500바이트 미만으로 유지하세요. additionalData 필드는 2048바이트로 제한됩니다.
앱에서 OSNotification에 액세스
모든 OneSignal SDK는 OSNotification 객체를 반환하는 알림 이벤트 리스너를 트리거합니다.
- Android:
OneSignal.setNotificationWillShowInForegroundHandler(...)
- iOS:
notificationReceivedBlock 또는 UNNotificationServiceExtension
이 객체를 사용하여 알림 제목, 본문, 데이터 및 기타 속성에 액세스하세요.
OSNotification 클래스는 SDK 알림 이벤트 리스너 내에서 액세스할 수 있는 모든 알림 payload 데이터를 제공합니다. 원래의 OSNotification 및 OSNotificationPayload 클래스를 getter 기반의 단일 인터페이스로 병합합니다.
Android 필드
| Property | Type | Description |
|---|
getBody() | String | 알림의 본문 텍스트입니다. |
getTitle() | String | 알림의 제목입니다. |
getLaunchURL() | String | 알림을 클릭할 때 열리는 URL입니다. |
getNotificationId() | String | OneSignal 알림 UUID입니다. |
getAdditionalData() | JSONObject | 대시보드 또는 REST API를 통해 설정된 사용자 지정 key-value 데이터입니다. 최대 2048바이트입니다. |
getTemplateId() | String | Template을 사용하여 보낸 경우 Template 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<OSNotification> | 요약에 포함된 알림입니다. |
getGroupKey() | String | 요약에 사용되는 그룹 key입니다. |
getGroupMessage() | String | 요약 텍스트입니다. |
getBackgroundImageLayout() | BackgroundImageLayout | 배경 이미지 레이아웃 및 텍스트 색상에 대한 객체입니다. |
getActionButtons() | List<ActionButton> | 아이콘, 텍스트 및 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 | Template을 사용하여 보낸 경우 Template 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" 객체를 포함합니다:
{
"custom": {
"i": "the-notification-id"
}
}
이 key는 OneSignal SDK가 알림을 처리하는 데 필요합니다. 누락된 경우 알림이 클릭 이벤트 또는 Analytics를 트리거하지 않습니다.이미 OneSignal을 사용하는 장치에 다른 서비스에서 푸시를 보내는 경우 알림 중복을 피하세요.
선택 사항: additionalData를 APNS 루트로 이동
iOS 앱의 경우 사용자 지정 핸들러에서 더 쉽게 액세스할 수 있도록 additionalData를 APNS payload의 루트에서 사용할 수 있도록 설정할 수 있습니다.
- 앱 설정에서 활성화
Update an app API를 사용하여 다음을 설정하세요:
{
"additional_data_is_root_payload": true
}
data로 푸시 전송
APNS payload의 루트에서 사용할 수 있습니다. 예시:
{
"aps": {
"alert": { "title": "Sale", "body": "20% off all items!" }
},
"promo_code": "SPRING20"
}
promo_code에 직접 액세스할 수 있습니다.
복원된 알림
재부팅 또는 앱 재시작 후 Android SDK에서 알림이 복원됩니다.
| Property | Type | Description |
|---|
restoring | boolean | 장치/앱 재시작 후 알림이 복원된 경우 true입니다. |
복원된 알림은 restoring 플래그를 사용하여 건너뛸 수 있습니다. 오래된 콘텐츠가 복원되지 않도록 하려면 알림에 짧거나 0인 TTL(time-to-live)을 설정하세요.
관련 주제
