메인 콘텐츠로 건너뛰기
OSNotification 클래스는 OneSignal SDK에서 푸시 알림 payload를 나타냅니다. 앱에서 알림을 처리할 때 알림 제목, 본문, 사용자 지정 데이터, 플랫폼별 속성에 액세스하는 데 사용하세요.
푸시 알림 payload는 4096바이트로 제한됩니다. 잘림을 방지하려면 payload를 3500바이트 미만으로 유지하세요. additionalData 필드는 2048바이트로 제한됩니다.

​
앱에서 OSNotification에 액세스

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

​
Android 필드

PropertyTypeDescription
getBody()String알림의 본문 텍스트입니다.
getTitle()String알림의 제목입니다.
getLaunchURL()String알림을 클릭할 때 열리는 URL입니다.
getNotificationId()StringOneSignal 알림 UUID입니다.
getAdditionalData()JSONObject대시보드 또는 REST API를 통해 설정된 사용자 지정 key-value 데이터입니다. 최대 2048바이트입니다.
getTemplateId()String템플릿을 사용하여 보낸 경우 템플릿 UUID입니다.
getAndroidNotificationId()intAndroid 기본 알림 ID입니다.
getLargeIcon()StringLarge icon의 URL 또는 리소스 이름입니다.
getSmallIcon()StringSmall icon 리소스 이름입니다.
getSmallIconAccentColor()StringARGB 형식의 아이콘 강조 색상입니다.
getSound()String재생되는 사운드 리소스 이름입니다.
getCollapseId()String알림 교체를 위한 Collapse key입니다.
getPriority()intAndroid 우선순위(-2에서 2)입니다.
getLedColor()StringARGB 형식의 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()Stringpayload의 전체 원시 JSON 문자열입니다.

​
iOS 필드

PropertyTypeDescription
bodyNSString알림의 본문 텍스트입니다.
titleNSString알림의 제목입니다.
launchURLNSString알림을 클릭할 때 열리는 URL입니다.
notificationIdNSStringOneSignal 알림 UUID입니다.
additionalDataDictionary대시보드 또는 REST API를 통해 설정된 사용자 지정 key-value data입니다. 최대 2048바이트입니다.
templateIdNSString템플릿을 사용하여 보낸 경우 템플릿 UUID입니다.
subtitleNSString부제목 텍스트입니다.
categoryNSStringiOS 카테고리 식별자입니다.
threadIdNSString알림을 스레드로 그룹화하는 데 사용됩니다(iOS 10+).
badgeNSInteger절대 배지 값입니다.
badgeIncrementNSInteger배지를 증가시킬 양입니다.
contentAvailableBOOLcontent-available=1이면 백그라운드 fetch를 트리거합니다.
mutableContentBOOLmutable-content=1이면 Notification Service Extension을 트리거합니다.
actionButtonsNSArrayiOS Action 버튼입니다.
rawPayloadNSDictionarypayload의 전체 원시 JSON입니다.
parseWithApnsMethod원시 APNS payload를 OSNotification으로 변환합니다. Service Extension에서 사용합니다.

​
OSNotificationAction (클릭 이벤트)

알림과의 사용자 상호 작용을 설명합니다.
PropertyTypeDescription
actionIdString클릭된 Action 버튼의 ID입니다.
typeenumOpened(기본 탭) 또는 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는 디바이스 재부팅 또는 앱 재시작 후 알림을 복원합니다.
PropertyTypeDescription
restoringboolean디바이스/앱 재시작 후 알림이 복원된 경우 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 메서드 및 리스너에 대한 전체 참조입니다.