0단계. OneSignal에서 FCM 구성 (푸시 전송에 필수)
이 단계를 완료하지 않아도 OneSignal Android SDK를 설치하고 초기화할 수 있습니다. 하지만 Firebase Cloud Messaging(FCM) 자격 증명이 OneSignal 앱에 구성될 때까지 푸시 알림은 전송되지 않습니다.OneSignal 앱을 구성하는 단계.
OneSignal 앱을 구성하는 단계.
- 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.9.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 앱에 설치되고 초기화됨
- 실제 기기에서 푸시 알림 권한 요청이 올바르게 표시됨
- 테스트 푸시 및 인앱 메시지가 성공적으로 전송됨
1단계. OneSignal SDK 추가
- Android Studio에서
build.gradle.kts (Module: app)또는build.gradle (Module: app)파일을 여세요 dependencies섹션에 OneSignal을 추가하세요:

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

ApplicationClass라는 이름의 새 Kotlin 클래스를 생성하는 예시.
YOUR_APP_ID를 Dashboard > Settings > Keys & IDs에서 확인한 실제 OneSignal App ID로 교체하세요.

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

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

iOS 및 Android 푸시 권한 요청 프롬프트 예시

'Never Subscribed' 상태의 구독을 보여주는 대시보드

푸시 권한을 허용한 후 대시보드를 새로고침하면 구독 상태가 'Subscribed'로 업데이트됩니다
테스트 구독 및 세그먼트 생성
- 구독 옆의 **⋮**을 클릭 > Add to Test Users > 이름을 지정하세요
- Audience > Segments > New Segment로 이동하세요
- 이름:
Test Users, 필터 Test Users 추가 > Create Segment

테스트 구독 추가

Test Users 필터로 'Test Users' 세그먼트 생성
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를 클릭하세요
- 앱을 여세요

인앱 메시지로 'Test Users' 세그먼트 타겟팅

인앱 Welcome 메시지 커스터마이즈 예시

인앱 메시지 스케줄링 옵션

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