OSNotification payload

OSNotification 클래스는 OneSignal SDK에서 푸시 알림 payload를 나타냅니다. 앱에서 알림을 처리할 때 알림 제목, 본문, 사용자 지정 데이터, 플랫폼별 속성에 액세스하는 데 사용하세요.

푸시 알림 payload는 4096바이트로 제한됩니다. 잘림을 방지하려면 payload를 3500바이트 미만으로 유지하세요. additionalData 필드는 2048바이트로 제한됩니다.

앱에서 `OSNotification`에 액세스

모든 OneSignal SDK는 OSNotification 객체를 반환하는 알림 이벤트 리스너를 제공합니다:

Android: notification lifecycle listener 사용
iOS: notification lifecycle listener 또는 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<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`	템플릿을 사용하여 보낸 경우 템플릿 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을 사용하는 디바이스에 다른 서비스에서 푸시를 보내는 경우, 중복 처리를 방지하기 위해 이 key로 필터링하세요. 자세한 내용은 Push payload handling을 참조하세요.

additionalData를 APNS 루트로 이동

iOS 앱의 경우 additionalData 필드를 custom 딕셔너리 내부 대신 APNS payload의 루트에 배치할 수 있습니다. 이렇게 하면 사용자 지정 알림 핸들러에서 더 간편하게 액세스할 수 있습니다. 1. API를 통해 활성화 Update an app API를 사용하여 다음을 설정하세요:

{
  "additional_data_is_root_payload": true
}

2. data로 푸시 전송 data 필드가 APNS 루트 payload에 표시됩니다:

{
  "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를 통해 additional_data_is_root_payload를 활성화하면 custom 딕셔너리 내부 대신 APNS 루트에 additionalData 필드를 배치할 수 있습니다. 자세한 내용은 additionalData를 APNS 루트로 이동을 참조하세요.

Android 알림 카테고리

Android 8.0 이상 디바이스용 알림 채널을 구성합니다.

Mobile Service Extensions

리치 미디어, 배지, 확인된 전달 추적을 추가합니다.

Mobile SDK 참조

OneSignal 모바일 SDK 메서드 및 리스너에 대한 전체 참조입니다.

개발자 문서

모바일 SDKs

웹 SDKs

실시간 현황

데스크탑 & 워치 설정

OSNotification payload

앱에서 `OSNotification`에 액세스

Android 필드

iOS 필드

`OSNotificationAction` (클릭 이벤트)

사용자 지정 OneSignal payload 구조

additionalData를 APNS 루트로 이동

복원된 알림 (Android)

푸시 토큰 형식

FAQ

최대 payload 크기는 얼마인가요?

원시 payload에서 OneSignal 알림을 어떻게 식별하나요?

APNS 루트 payload에서 additionalData에 액세스할 수 있나요?

Android 알림 카테고리

Mobile Service Extensions

Mobile SDK 참조

​앱에서 OSNotification에 액세스

​Android 필드

​iOS 필드

​OSNotificationAction (클릭 이벤트)

​사용자 지정 OneSignal payload 구조

​additionalData를 APNS 루트로 이동

​복원된 알림 (Android)

​푸시 토큰 형식

​FAQ

​최대 payload 크기는 얼마인가요?

​원시 payload에서 OneSignal 알림을 어떻게 식별하나요?

​APNS 루트 payload에서 additionalData에 액세스할 수 있나요?

Android 알림 카테고리

Mobile Service Extensions

Mobile SDK 참조

앱에서 `OSNotification`에 액세스

Android 필드

iOS 필드

`OSNotificationAction` (클릭 이벤트)

사용자 지정 OneSignal payload 구조

additionalData를 APNS 루트로 이동

복원된 알림 (Android)

푸시 토큰 형식

FAQ

최대 payload 크기는 얼마인가요?

원시 payload에서 OneSignal 알림을 어떻게 식별하나요?

APNS 루트 payload에서 additionalData에 액세스할 수 있나요?