Skip to main content
사용자가 알림 창과 잠금 화면에서 앱을 인식할 수 있도록 푸시 알림 아이콘을 설정하세요. Android, iOS 및 웹은 각각 다른 아이콘 소스를 사용합니다. 알림에 첨부되는 대형 이미지는 이미지 및 리치 미디어를 참조하세요.
작은 뱃지 아이콘, 큰 아이콘 및 이미지가 포함된 푸시 알림

작은 뱃지 아이콘, 큰 아이콘 및 이미지가 포함된 Android Chrome 웹 푸시 알림의 예시입니다.

Android 알림 아이콘

Android(Amazon 및 Huawei 기기 포함)는 소형대형 알림 아이콘을 지원합니다. Android 8.0+ (API 26+)에서는 알림 카테고리와 제조업체 UI도 알림의 모양에 영향을 줍니다. Android는 또한 아이콘 대신 사람의 프로필 이미지를 표시할 수 있는 대화 알림을 지원합니다.
소형 아이콘, 대형 아이콘 및 강조 색상 배치를 보여주는 Android 알림

소형 알림 아이콘

소형 알림 아이콘은 필수입니다. 상태 표시줄에 단색 실루엣으로 표시됩니다. 사용자 정의 소형 아이콘을 제공하지 않으면 OneSignal은 기본 벨 아이콘을 사용합니다. Android 17(API 37)에서는 알림에서 아이콘이 배치되는 위치가 변경됩니다. 알림의 런처 아이콘을 참조하세요. Android는 색상 데이터가 아닌 아이콘의 알파 채널을 사용하여 소형 알림 아이콘을 렌더링합니다. Android 12(API 31)부터 시스템은 설정한 알림 강조 색상으로 해당 실루엣에 틴트를 적용합니다. 색상을 설정하지 않으면 시스템 테마 색상을 사용합니다. Android 알림 디자인을 참조하세요. 요구 사항:
  • 투명한 배경단색 실루엣 아이콘을 사용하세요
  • 색상이 아닌 투명도로 모양이 정의되도록 아이콘을 디자인하세요
  • 그라디언트, 그림자 또는 다색 아트워크는 피하세요
  • 매우 작은 크기에서도 단순하고 인식 가능한 디자인을 유지하세요
일반적인 접근 방식은 투명한 배경에 흰색 아트워크입니다. Android는 흰색 자체가 아닌 알파 마스크를 사용합니다.
단색 배경이나 풀 컬러 아트워크가 있는 아이콘은 흰색 사각형, 잘린 모양 또는 예상치 못한 실루엣으로 렌더링되는 경우가 많습니다. Android는 소형 알림 아이콘의 색상을 무시하고 알파 채널과 시스템 또는 앱 틴팅에서 모양을 파생합니다.
스톡 Android에서는 풀 컬러 소형 아이콘을 강제할 수 없습니다. Android 12(API 31) 이상에서는 사용자 정의 알림 레이아웃에서도 시스템 틴트가 적용된 소형 아이콘이 계속 표시됩니다. 일부 제조업체는 알파 채널을 무시하고 풀 컬러 이미지를 표시합니다. 이에 의존하지 마세요. 항상 규정을 준수하는 알파 채널 아이콘을 제공하세요.

알림의 런처 아이콘 (Android 17)

Android 17(API 37)부터 Android는 알림에 소형 아이콘 대신 앱의 런처 아이콘을 표시합니다. 소형 아이콘은 여전히 상태 표시줄에 표시됩니다. 이는 모든 알림에 적용되는 Android 시스템 동작이며, 정확한 모양은 기기 제조업체에 따라 다를 수 있습니다. 알림에 소형 아이콘을 대신 표시하려면 Android의 EXTRA_PREFER_SMALL_ICON extra를 설정하세요. OneSignal SDK는 기본적으로 이 extra를 설정하지 않습니다. 알림 서비스 확장에서 추가하세요. 해당 페이지에 나온 대로 클래스에 @Keep 어노테이션을 추가하고 매니페스트에 등록하세요.
이 문자열 키는 모든 compileSdk 버전에서 작동합니다. Android 16(API 36) 이하는 이 extra를 무시하므로 조건 없이 설정해도 안전합니다.

소형 아이콘 강조 색상

Android 12(API 31) 이상이 소형 아이콘에 틴트를 적용하는 데 사용하는 알림 강조 색상을 설정할 수 있습니다. 이는 Android의 Notification.color(setColor)에 매핑됩니다. Android가 우선순위가 높은 진행 중인 작업을 위해 예약한 알림 배경 색상 지정(setColorized)과는 다릅니다. 강조 색상은 채널 속성이 아닌 알림별 속성입니다. Android 알림 카테고리는 사운드, 중요도, 진동, LED 색상 및 배지를 제어합니다. 카테고리에는 강조 색상 설정이 없으며, 알림이 어떤 카테고리에 표시되든 관계없이 강조 색상이 적용됩니다.
Android 17(API 37) 이상에서는 런처 아이콘이 표시될 때 알림에 강조 색상이 보이지 않을 수 있습니다. 상태 표시줄의 소형 아이콘에는 틴트가 계속 적용됩니다.
소형 아이콘 강조 색상을 보여주는 Android 알림
SDK는 다음 순서로 강조 색상을 결정합니다. 처음 발견되는 값이 우선합니다:
  1. 메시지별: 메시지 생성 API의 android_accent_color(Google Android) 또는 huawei_accent_color(Huawei) 매개변수, 또는 Messages > Push > New Push > Platform Settings > Google Android Options 아래의 Accent color 필드.
  2. 리소스를 통한 앱 기본값: onesignal_notification_accent_color 문자열 리소스.
  3. 매니페스트를 통한 앱 기본값: AndroidManifest.xmlcom.onesignal.NotificationAccentColor.DEFAULT meta-data 항목.
# 없이 ARGB 16진수 값을 사용하세요(예: FF00FF00). Android Asset Studio에서 색상을 미리 볼 수 있습니다. 리소스로 기본 색상을 설정하려면 res/values/strings.xml 파일에 다음 줄을 추가하세요. 다크 모드에서 다른 색상을 사용하려면 res/values-night/strings.xml에 동일한 키를 추가하세요.
대신 매니페스트에서 기본값을 설정하려면 <application> 태그 안에 다음을 추가하세요:
표시 시점에 완전한 제어가 필요하면 알림 서비스 확장에서 notification.setExtenderbuilder.setColor()를 사용하여 색상을 설정하세요. extender는 SDK가 위의 값을 적용한 후에 실행되므로 모든 값을 재정의합니다.

대형 알림 아이콘

대형 아이콘은 선택 사항입니다. 알림의 오른쪽에 표시됩니다. Android의 디자인 지침은 발신자 사진, 서드파티 소스 로고 또는 의미 있는 심볼처럼 이미지가 알림 내용을 보강하는 경우에만 사용하는 것입니다. 대형 아이콘을 두 번째 앱 아이콘이나 브랜딩 용도로 사용하지 마세요. The large icon을 참조하세요.
  • 권장 크기: 256×256 픽셀
  • 형식: PNG 또는 JPG
  • 색상이 허용됩니다. 알파 전용일 필요는 없습니다.
대형 아이콘을 설정하지 않으면 스톡 Android에서는 해당 슬롯이 비어 있습니다. 일부 제조업체는 대신 앱 런처 아이콘을 표시합니다.

Android 기본 아이콘 추가 방법

모든 Android 기반 앱(Google Play, Amazon, Huawei)에 대해 기본 아이콘을 구성하세요. 먼저 Android SDK 설정(또는 사용하는 크로스 플랫폼 설정)을 완료하세요. 프로젝트의 리소스 디렉토리(또는 Expo의 경우 플러그인 구성)에 파일을 추가하고 다시 빌드한 후 릴리스하세요. 누락되거나 잘못된 이름의 파일이 렌더링이 깨지는 가장 일반적인 원인입니다. 기본 아이콘은 앱 바이너리에 포함되어 배포됩니다. OneSignal 대시보드에 업로드되지 않습니다. 출시 후에는 새 아이콘 이름에 의존하는 알림을 보내기 전에 대부분의 사용자가 업데이트할 때까지 기다리세요.
1

소형 알림 아이콘 생성

Android Asset Studio – 알림 아이콘을 사용하여 투명한 배경의 실루엣을 생성하세요. 소형 아이콘 요구 사항을 따르세요.아이콘 이름 지정: ic_stat_onesignal_default
2

필수 소형 아이콘 크기 생성

소형 아이콘에 대한 모든 밀도 변형을 포함하세요. 크기가 하나라도 누락되면 Android가 시스템 기본 아이콘으로 대체할 수 있습니다. 이 크기들은 각 밀도에서 24dp이며, 이는 Android의 상태 표시줄 아이콘 크기입니다.
3

대형 알림 아이콘 생성 (선택 사항)

256×256 PNG 또는 JPG를 사용하세요. 색상이 허용됩니다. 하나의 크기만 필요합니다.필수 파일 이름: ic_onesignal_large_icon_default.png
4

올바른 프로젝트 경로에 아이콘 배치

누락된 폴더는 생성하세요. 모든 소형 아이콘 밀도를 해당 drawable 폴더에 배치하세요. 대형 아이콘은 XXXHDPI 소형 아이콘 옆의 drawable-xxxhdpi/에 배치하세요. 두 파일은 폴더를 공유하며 서로 다른 이름을 사용합니다.
소형 아이콘 (ic_stat_onesignal_default):
  • res/drawable-mdpi/ (24×24)
  • res/drawable-hdpi/ (36×36)
  • res/drawable-xhdpi/ (48×48)
  • res/drawable-xxhdpi/ (72×72)
  • res/drawable-xxxhdpi/ (96×96)
대형 아이콘 (ic_onesignal_large_icon_default.png, 256×256):
  • res/drawable-xxxhdpi/
프로젝트는 다음과 유사하게 보여야 합니다(SDK에 따라 다름):
drawable 폴더의 아이콘 파일을 보여주는 Android 프로젝트 디렉토리 구조

drawable 폴더에 아이콘 파일이 있는 Android Native 프로젝트

이제 Android 앱이 기본 알림 아이콘으로 구성되었습니다. 단색 사각형이나 OneSignal 벨이 표시되면 FAQ를 참조하세요.

iOS 알림 아이콘

iOS 알림은 항상 앱 아이콘을 사용합니다. 시스템은 각 알림의 앞쪽 가장자리에 해당 아이콘의 큰 버전을 표시하며 앱 아이콘 에셋에서 크기를 조정합니다. 메시지별로 변경할 수 없습니다. 변경하려면 앱 아이콘을 업데이트하고 새 앱 버전을 출시하세요. Human Interface Guidelines: Notifications를 참조하세요.
APNs 페이로드에는 alert, badge, sound가 있습니다. 사용자 정의 알림 아이콘을 위한 필드는 없습니다. Apple은 aps 딕셔너리 내의 사용자 정의 키를 무시합니다. 이는 표준 푸시 알림과 중요 알림에 적용됩니다. 라이브 활동 UI는 ActivityKit을 통해 자체 이미지를 표시할 수 있습니다. 이는 알림 아이콘을 대체하지 않습니다.

커뮤니케이션 알림

iOS 15 이상에서 Apple은 메시징 및 통화 앱을 위한 커뮤니케이션 알림을 지원합니다. INSendMessageIntent 또는 INStartCallIntent를 기부(donate)한 후 시스템은 큰 앱 아이콘 대신 발신자 또는 전화 건 사람의 아바타(INImage)를 표시할 수 있습니다. 앱 아이콘은 해당 아바타에 작은 배지로 계속 표시됩니다. 이를 위해서는 Communication Notifications capability, SiriKit 인텐트, 알림 콘텐츠를 업데이트하는 Notification Service Extension이 필요합니다. 일반 용도 알림에는 사용할 수 없습니다.

웹 알림 아이콘

웹 푸시 알림은 전송 시 제공되거나 사이트 설정에서 기본값으로 설정된 아이콘을 표시합니다. 아이콘이 제공되지 않으면 기본 벨 아이콘이 사용됩니다.
  • 지원 형식: PNG, JPG, GIF (애니메이션 제외)
  • 아이콘은 정사각형이어야 합니다. 권장 크기는 256×256 픽셀입니다. web.dev는 Android에서 64dp를 언급하므로 192×192 이상이 일반적인 최소 크기입니다. 256×256이 Chrome, Firefox, Edge, Safari 전반에서 가장 일관된 크기입니다.
  • 브라우저와 운영 체제는 아이콘을 서로 다르게 자르고 크기를 조정합니다. Chrome과 Firefox는 플랫폼 알림 UI가 있는 경우 이를 사용합니다.
Settings > Push & In-App > Web에서 Default Icon URL을 설정하세요. 웹 SDK 설정을 참조하세요. 대시보드나 REST API를 사용하여 알림별로 아이콘을 재정의할 수도 있습니다. 기본이 아닌 아이콘으로 알림 보내기를 참조하세요.

Android 웹 푸시 뱃지 아이콘

Android에서 Chrome 웹 푸시는 전체 알림을 표시할 공간이 부족할 때 상태 표시줄에 더 작은 뱃지 아이콘을 표시할 수 있습니다. OneSignal은 Notifications API의 badge 옵션에 매핑되는 chrome_web_badge로 이를 전송합니다. Android용 Chrome은 이 뱃지를 사용합니다. 뱃지를 설정하지 않으면 Chrome은 브라우저 아이콘을 사용합니다. 다른 브라우저는 일반적으로 브라우저 아이콘을 표시합니다. Notification: badge를 참조하세요. 이는 앱 아이콘 배지(점 또는 숫자)가 아닙니다. 앱 아이콘 배지는 배지를 참조하세요. 뱃지를 단색 아이콘으로 취급하세요. MDN은 Android가 이미지를 자동으로 마스킹한다고 명시합니다. 투명한 배경에 정사각형 PNG 실루엣을 사용하세요(Android 소형 아이콘과 동일한 규칙). 텍스트, 세밀한 디테일 및 풀 컬러 아트워크는 피하세요. MDN은 이미지가 4x에서도 유지되도록 약 96×96 픽셀을 권장합니다. 72×72가 일반적인 최소 크기입니다(3x에서 24dp). 더 큰 이미지는 축소됩니다.
웹 푸시 뱃지 아이콘을 보여주는 Android 상태 표시줄

Android 상태 표시줄에 뱃지 아이콘이 표시되는 방법의 예시입니다.

기본이 아닌 아이콘으로 알림 보내기

OneSignal 대시보드 또는 REST API에서 푸시를 보낼 때 Android, Amazon, Huawei 및 Web Push의 기본 아이콘을 재정의할 수 있습니다. iOS 알림의 아이콘은 재정의할 수 없습니다.

REST API 매개변수

Android, Amazon 및 Huawei:
string
파일 확장자가 없는 아이콘 리소스 이름입니다. 이미지는 기본 소형 아이콘과 동일한 프로젝트 폴더에 존재해야 합니다. 원격 URL은 지원되지 않습니다. Android 기본 아이콘 추가 방법을 참조하세요.Amazon은 adm_small_icon을 사용하세요. Huawei는 huawei_small_icon을 사용하세요.예시: "small_icon": "my_custom_icon"
string
파일 확장자가 없는 아이콘 리소스 이름 또는 원격 URL입니다. 리소스 이름을 사용하는 경우 이미지가 기본 대형 아이콘과 동일한 프로젝트 폴더에 존재해야 합니다. Android 기본 아이콘 추가 방법을 참조하세요.Amazon은 adm_large_icon을 사용하세요. Huawei는 huawei_large_icon을 사용하세요.예시: "large_icon": "my_custom_icon"
Web Push:
string
이미지 리소스에 대한 직접 URL입니다.Firefox는 firefox_icon을 사용하세요.예시: "chrome_web_icon": "https://example.com/my_custom_icon.png"
string
Chrome 웹 알림의 Android 상태 표시줄 뱃지로 사용되는 이미지 리소스에 대한 직접 URL입니다.예시: "chrome_web_badge": "https://example.com/badge.png"

대시보드

Messages > Push > New Push 또는 Templates에서 플랫폼별 옵션을 여세요. Android, Amazon 및 Huawei의 경우 파일이 기본 아이콘과 동일한 프로젝트 경로에 존재하면 파일 확장자 없이 아이콘 이름을 설정하세요. 대형 알림 아이콘의 경우 직접 URL을 제공할 수도 있습니다.
Android 플랫폼 설정에서 아이콘 재정의 필드를 보여주는 OneSignal 대시보드

기본 아이콘을 재정의하는 OneSignal 대시보드.

FAQ

Android 소형 아이콘이 흰색 또는 회색 사각형으로 표시되는 이유는 무엇인가요?

이미지에 적절한 투명도가 없습니다. Android는 알파 채널만 사용하여 소형 알림 아이콘을 렌더링합니다. 단색 배경의 완전히 불투명한 픽셀은 채워진 사각형으로 나타납니다. Android Asset Studio를 사용하여 투명한 배경의 단색 실루엣으로 아이콘을 다시 생성하세요.

사용자 정의 아이콘 대신 OneSignal 벨 아이콘이 표시되는 이유는 무엇인가요?

소형 아이콘의 하나 이상의 필수 밀도 변형이 누락되었거나 잘못된 drawable 디렉토리에 배치되어 있거나 이름이 잘못되었습니다. 정확한 파일 이름 ic_stat_onesignal_default로 다섯 가지 크기(MDPI부터 XXXHDPI까지) 모두를 포함해야 합니다. 올바른 경로는 Android 기본 아이콘 추가 방법을 참조하세요.

알림에 소형 아이콘 대신 앱 아이콘이 표시되는 이유는 무엇인가요?

Android 17(API 37)부터 Android는 기본적으로 알림에 앱의 런처 아이콘을 표시합니다. 소형 아이콘은 여전히 상태 표시줄에 표시됩니다. 알림에 소형 아이콘을 표시하려면 알림 서비스 확장에서 EXTRA_PREFER_SMALL_ICON extra를 설정하세요. 알림의 런처 아이콘을 참조하세요.

메시지별로 iOS 알림 아이콘을 변경할 수 있나요?

아니요. iOS는 푸시 알림에 항상 앱 아이콘을 사용합니다. APNs 페이로드에는 아이콘 필드가 없습니다. 아이콘을 변경하려면 앱 아이콘 에셋을 업데이트하고 새 앱 버전을 출시해야 합니다. 메시징 및 통화 앱은 커뮤니케이션 알림을 채택해야만 발신자 아바타를 표시할 수 있습니다.

웹 푸시 아이콘의 권장 크기는 무엇인가요?

256×256 픽셀의 정사각형 PNG, JPG 또는 애니메이션이 아닌 GIF를 사용하세요. 브라우저와 운영 체제마다 아이콘을 자르거나 크기를 조정할 수 있지만, 256×256은 Chrome, Firefox, Edge, Safari에서 가장 일관된 크기입니다.

Android 소형 아이콘에 URL을 사용할 수 있나요?

아니요. Android 소형 아이콘은 앱과 함께 번들된 로컬 리소스 파일이어야 합니다. 대형 아이콘만 원격 URL을 지원합니다.

Expo에서 알림 아이콘을 추가하는 방법은 무엇인가요?

app.json 또는 app.config.js에서 96×96 소형 아이콘 PNG와 256×256 대형 아이콘 PNG로 onesignal-expo-plugin을 사용하세요. 플러그인이 빌드 시 밀도 변형을 생성합니다. 구성은 Expo 탭을 참조하세요.

기본 아이콘을 OneSignal 대시보드에 업로드해야 하나요?

아니요. 기본 알림 아이콘은 OneSignal에 업로드되는 것이 아니라 앱 바이너리 내에 번들됩니다. 프로젝트의 리소스 디렉토리(또는 Expo의 경우 플러그인 구성)에 추가하면 OneSignal SDK가 자동으로 사용합니다. OneSignal 대시보드는 Android 및 Web Push에 대해 메시지별로만 아이콘을 재정의할 수 있습니다.

관련 페이지

이미지 및 리치 미디어

푸시 알림에 대형 이미지, GIF, 동영상을 첨부하세요.

Android SDK 설정

Android SDK를 설치한 다음 drawable 폴더에 기본 알림 아이콘을 추가하세요.

React Native / Expo SDK 설정

OneSignal Expo 플러그인에서 smallIconslargeIcons를 구성하세요.

Android 알림 카테고리

사운드, 진동 및 중요도를 위한 Android 알림 채널을 생성하고 관리하세요.

웹 SDK 설정

Settings > Push & In-App > Web에서 Default Icon URL을 설정하세요.

메시지 생성 API

REST API를 사용하여 사용자 정의 아이콘으로 푸시 알림을 보내세요.