AI 코딩 어시스턴트를 사용하시나요?
AI 기반 설치를 위해 다음 프롬프트를 사용하세요:
0단계. OneSignal에서 FCM 구성 (푸시 전송에 필수)
이 단계를 완료하지 않아도 OneSignal Android SDK를 설치하고 초기화할 수 있습니다. 하지만 Firebase Cloud Messaging(FCM) 자격 증명이 OneSignal 앱에 구성될 때까지 푸시 알림은 전송되지 않습니다.회사에 이미 OneSignal 계정이 있는 경우, 앱을 구성하려면 관리자 역할로 초대를 요청하세요. 아직 계정이 없다면 무료 계정에 가입하여 시작하세요.
OneSignal 앱을 구성하는 단계.
OneSignal 앱을 구성하는 단계.
이 단계는 OneSignal 앱을 Firebase Cloud Messaging(FCM)에 연결합니다. 앱당 한 번만 수행하면 됩니다.
- https://onesignal.com에 로그인하고 앱을 생성하거나 선택하세요.
- Settings > Push & In-App으로 이동하세요.
- **Google Android (FCM)**을 선택하고 설정 마법사를 따라 Continue를 클릭하세요.
- Firebase 서버 키 또는 서비스 계정 정보를 입력하세요.
- 설정 마법사를 계속 진행하여 App ID를 받으세요. 이 ID는 SDK를 초기화하는 데 사용됩니다.
전체 설정 안내는 모바일 푸시 설정 가이드를 참조하세요.
설정 계약 및 요구 사항
이 섹션은 가이드 전체에서 사용되는 도구, 버전 및 전제 조건을 요약합니다.- SDK 버전:
5.6.1+(최신 버전: 릴리스 확인) - AI 설정 안내:
https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md - SDK 저장소:
https://github.com/OneSignal/OneSignal-Android-SDK - Android Studio: Meerkat+ (2024.2.1+)
- Android API: 최소 23+ (Android 6.0+), 권장 31+ (Android 12+)
- 기기/에뮬레이터: Google Play Services가 설치된 Android 7.0+
- 필수 의존성:
com.onesignal:OneSignal:[5.6.1, 5.6.99] - Application 클래스: 올바른 SDK 초기화에 필수
- App ID 형식: 36자 UUID (예:
12345678-1234-1234-1234-123456789012) — OneSignal Dashboard > Settings > Keys & IDs에서 확인 - 초기화:
OneSignal.initWithContext(this, "YOUR_APP_ID") - 배터리 최적화: 백그라운드 알림에 영향을 줄 수 있음
- 권장:
OneSignal.login("user_id")를 통해 External ID를 할당하여 기기 간 사용자 통합
Android 설정 단계
아래 단계를 완료하면 다음을 달성하게 됩니다:- OneSignal SDK가 Android 앱에 설치되고 초기화됨
- 실제 기기에서 푸시 알림 권한 요청이 올바르게 표시됨
- 테스트 푸시 및 인앱 메시지가 성공적으로 전송됨
**0단계(OneSignal에서 FCM 구성)**를 건너뛰었더라도 아래 Android Studio 설정을 완료할 수 있습니다. 푸시 알림을 테스트하거나 보내기 전에 0단계를 완료하세요.
1단계. OneSignal SDK 추가
- Android Studio에서
build.gradle.kts (Module: app)또는build.gradle (Module: app)파일을 여세요 dependencies섹션에 OneSignal을 추가하세요:

- Gradle 동기화: 표시되는 배너에서 Sync Now를 클릭하거나 File > Sync Project with Gradle Files로 이동하세요
Gradle 동기화가 의존성 충돌 없이 성공적으로 완료되었는지 확인하세요.
2단계. Application 클래스 생성 및 구성
모든 진입점에서 올바른 SDK 설정을 보장하려면Application 클래스의 onCreate 메서드에서 OneSignal을 초기화하는 것이 모범 사례입니다.
Application 클래스가 아직 없다면 생성하세요:
- File > New > Kotlin Class/File (또는 Java Class)
- 이름:
ApplicationClass(또는 원하는 이름)

YOUR_APP_ID를 Dashboard > Settings > Keys & IDs에서 확인한 실제 OneSignal App ID로 교체하세요.

- 앱의
AndroidManifest.xml을 여세요 <application>태그에android:name=".ApplicationClass"를 추가하세요 (클래스 이름을 다르게 설정한 경우.ApplicationClass를 실제 클래스 이름으로 교체하세요).
AndroidManifest.xml

앱이 오류 없이 빌드되고 실행되는지 확인하세요.
3단계. 기본 알림 아이콘 구성 (권장)
앱의 브랜딩에 맞게 알림 아이콘을 커스터마이즈하세요. 이 단계는 선택 사항이지만 전문적인 외관을 위해 권장됩니다.4단계. 통합 테스트
구독 생성 확인:- Google Play Services가 있는 기기 또는 에뮬레이터에서 앱을 실행하세요
- Dashboard > Audience > Subscriptions를 확인하세요 — 상태가 “Never Subscribed”로 표시됩니다
- 권한 요청 프롬프트가 나타나면 수락하세요
- 대시보드를 새로고침하세요 — 상태가 “Subscribed”로 변경됩니다



모바일 구독을 성공적으로 생성했습니다.
모바일 구독은 사용자가 기기에서 앱을 처음 열거나 같은 기기에서 앱을 삭제하고 다시 설치할 때 생성됩니다.
테스트 구독 및 세그먼트 생성
- 구독 옆의 **⋮**을 클릭 > Add to Test Subscriptions > 이름을 지정하세요
- Audience > Segments > New Segment로 이동하세요
- 이름:
Test Users, 필터 Test Users 추가 > Create Segment


테스트 사용자 세그먼트를 성공적으로 생성했습니다.이제 이 개별 기기와 테스트 사용자 그룹에 메시지 전송을 테스트할 수 있습니다.
API를 통한 테스트 푸시 전송
- **Settings > Keys & IDs**로 이동하세요.
- 아래 코드에서
YOUR_APP_API_KEY와YOUR_APP_ID를 실제 키로 교체하세요. 이 코드는 앞서 생성한Test Users세그먼트를 사용합니다.


테스트 기기가 다음 항목이 포함된 알림을 수신했는지 확인하세요:
- 커스텀 아이콘 (구성한 경우)
- 펼쳤을 때의 큰 이미지
- Dashboard > Delivery > Sent Messages에 “Confirmed” 상태 표시 (무료 플랜에서는 사용 불가).
인앱 메시지 테스트
- 30초 이상 앱을 종료하세요
- Dashboard > Messages > In-App > New In-App > Welcome 템플릿을 선택하세요
- 대상: Test Users 세그먼트
- 트리거: On app open
- 스케줄: Every time trigger conditions are satisfied
- Make Message Live를 클릭하세요
- 앱을 여세요




테스트 기기가 인앱 메시지를 수신했는지 확인하세요. 자세한 내용은 인앱 메시지 설정 가이드를 참조하세요.
일반적인 오류 및 해결 방법
| 오류 / 증상 | 원인 | 해결 방법 |
|---|---|---|
Cannot resolve symbol 'OneSignal' | SDK 의존성이 추가되지 않았거나 Gradle이 동기화되지 않음 | build.gradle에 의존성을 추가하고 프로젝트를 동기화하세요 |
Application class not found | Application 클래스가 매니페스트에 등록되지 않음 | <application> 태그에 android:name=".ApplicationClass"를 추가하세요 |
Google Play Services not available | 에뮬레이터/기기에 Play Services가 없음 | Play Store가 있는 기기 또는 Google APIs가 포함된 에뮬레이터를 사용하세요 |
| 푸시가 수신되지만 기본 Android 아이콘이 표시됨 | 커스텀 아이콘이 구성되지 않았거나 이름이 잘못됨 | onesignal_small_icon_default라는 이름의 알림 아이콘 에셋을 생성하세요 |
| 푸시 알림이 수신되지 않음 | OneSignal에서 FCM이 구성되지 않음 | 0단계를 완료하세요: OneSignal 대시보드에서 FCM 자격 증명을 구성하세요 |
| 인앱 메시지가 표시되지 않음 | 세션이 시작되지 않았거나 네트워크 문제 | 앱을 30초 이상 종료하고 다시 열고, 인터넷 연결을 확인하세요 |
Manifest merger failed | 매니페스트 속성 충돌 | 중복된 애플리케이션 이름이나 권한 충돌을 확인하세요 |
| 배터리 최적화로 알림이 차단됨 | 기기 전원 관리 | 사용자에게 앱의 배터리 최적화를 비활성화하도록 안내하세요 |
| 문제를 진단할 수 없음 | 로그 정보가 부족함 | 상세 로깅을 추가하고 logcat 출력에서 오류를 확인하세요 |
사용자 관리
이전에 모바일 구독을 생성하는 방법을 설명했습니다. 이제 OneSignal SDK를 사용하여 모든 구독(푸시, 이메일, SMS 포함)에서 사용자를 식별하는 방법으로 확장합니다.External ID 할당 (권장)
External ID를 사용하여 백엔드의 사용자 식별자를 통해 기기, 이메일 주소 및 전화번호에서 사용자를 일관되게 식별하세요. 이를 통해 채널 및 서드파티 시스템 간에 메시징이 통합된 상태로 유지됩니다. 자세한 내용과 Java 코드 예시는 모바일 SDK 레퍼런스를 참조하세요.Kotlin
OneSignal은 구독(Subscription ID)과 사용자(OneSignal ID)에 대해 고유한 읽기 전용 ID를 생성합니다.SDK를 통해 External ID를 설정하는 것은 생성 방식에 관계없이 모든 구독에서 사용자를 식별하기 위해 강력히 권장됩니다.SDK 레퍼런스 가이드에서
login 메서드에 대해 자세히 알아보세요.태그 및 커스텀 이벤트 추가
태그와 커스텀 이벤트는 사용자에게 데이터를 추가하는 두 가지 방법입니다. 태그는key-value 문자열이며 일반적으로 사용자 속성(예: username, role, status)과 연결되고, 커스텀 이벤트는 JSON 형식이며 일반적으로 동작(예: new_purchase, abandoned_cart 및 관련 속성)과 연결됩니다. 두 가지 모두 고급 메시지 개인화 및 Journeys를 구동하는 데 사용할 수 있습니다. 자세한 내용과 Java 코드 예시는 모바일 SDK 레퍼런스를 참조하세요.
Kotlin
이메일 및/또는 SMS 구독 추가
푸시 알림 외에도 이메일과 SMS 채널을 통해 사용자에게 도달할 수 있습니다. 이메일 주소 및/또는 전화번호가 이미 OneSignal 앱에 존재하는 경우, SDK는 이를 기존 사용자에게 추가하며 중복을 생성하지 않습니다. 자세한 내용과 Java 코드 예시는 모바일 SDK 레퍼런스를 참조하세요.Kotlin

멀티채널 커뮤니케이션 모범 사례
- 이메일 또는 SMS 구독을 추가하기 전에 명시적 동의를 받으세요.
- 각 커뮤니케이션 채널의 이점을 사용자에게 설명하세요.
- 사용자가 선호하는 채널을 선택할 수 있도록 채널 환경 설정을 제공하세요.
개인정보 보호 및 사용자 동의
OneSignal이 사용자 데이터를 수집하는 시점을 제어하려면 SDK의 동의 제어 메서드를 사용하세요. 자세한 내용과 Java 코드 예시는 모바일 SDK 레퍼런스를 참조하세요.Kotlin
개인정보 보호 및 보안 문서에서 자세히 알아보세요:
푸시 권한 요청
앱이 열릴 때 즉시requestPermission()을 호출하는 대신, 더 전략적인 접근 방식을 취하세요. 권한을 요청하기 전에 인앱 메시지를 사용하여 푸시 알림의 가치를 설명하세요.
모범 사례와 구현 세부 사항은 푸시 권한 요청 가이드를 참조하세요.
푸시, 사용자 및 인앱 이벤트 수신
SDK 리스너를 사용하여 사용자 동작 및 상태 변경에 반응하세요.OneSignal.initWithContext() 이후 Application 클래스에서 이를 추가하세요.
푸시 알림 이벤트
Kotlin
사용자 상태 변경
아래 예시는 푸시 구독 옵저버를 사용하는 방법을 보여줍니다. 사용자 상태 옵저버 및 알림 권한 옵저버와 같은 다른 사용자 상태 이벤트는 모바일 SDK 레퍼런스에서 확인할 수 있습니다.Kotlin
인앱 메시지 이벤트
추가 인앱 메시지 메서드는 모바일 SDK 레퍼런스에서 확인할 수 있습니다.Kotlin
고급 설정 및 기능
Android 전용 기능
- 알림 채널 — 알림을 카테고리별로 분류 (Android 8.0+)
- 서비스 확장 — 고급 알림 커스터마이즈
- Huawei/HMS 지원 — Google Play Services 대안
공통 기능
- 딥 링킹 — 알림에서 특정 화면으로 사용자 이동
- 액션 버튼 — 알림에 인터랙티브 버튼 추가
- 신원 확인 — 안전한 사용자 식별
- 위치 추적 — 위치 기반 타겟팅
- 연동 — 분석 및 데이터 플랫폼과 연결
- 다국어 메시징 — 현지화된 알림
도움이 필요하신가요?지원 팀과 채팅하거나
support@onesignal.com으로 이메일을 보내주세요.다음을 포함해 주세요:- 발생한 문제의 세부 정보 및 재현 단계(가능한 경우)
- OneSignal 앱 ID
- External ID 또는 Subscription ID(해당하는 경우)
- OneSignal 대시보드에서 테스트한 메시지의 URL(해당하는 경우)
- 관련 로그 또는 오류 메시지