Skip to main content
이 가이드는 Android Studio를 사용하여 Android 앱에 OneSignal을 추가하는 과정을 안내합니다. SDK를 설치하고, 푸시 및 인앱 메시지를 설정하며, 테스트 메시지를 보내 모든 것이 올바르게 작동하는지 확인합니다. OneSignal을 처음 사용하시는 경우 순서대로 단계를 따르세요. 이미 경험이 있으시다면 필요한 섹션으로 바로 이동하셔도 됩니다.
AI 코딩 어시스턴트를 사용하시나요? AI 기반 설치를 위해 다음 프롬프트를 사용하세요:

0단계. OneSignal에서 FCM 구성 (푸시 전송에 필수)

이 단계를 완료하지 않아도 OneSignal Android SDK를 설치하고 초기화할 수 있습니다. 하지만 Firebase Cloud Messaging(FCM) 자격 증명이 OneSignal 앱에 구성될 때까지 푸시 알림은 전송되지 않습니다.
회사에 이미 OneSignal 계정이 있는 경우, 앱을 구성하려면 관리자 역할로 초대를 요청하세요. 아직 계정이 없다면 무료 계정에 가입하여 시작하세요.
이 단계는 OneSignal 앱을 Firebase Cloud Messaging(FCM)에 연결합니다. 앱당 한 번만 수행하면 됩니다.
  1. https://onesignal.com에 로그인하고 앱을 생성하거나 선택하세요.
  2. Settings > Push & In-App으로 이동하세요.
  3. **Google Android (FCM)**을 선택하고 설정 마법사를 따라 Continue를 클릭하세요.
  4. FCM 서비스 계정 JSON을 업로드하세요.
  5. 설정 마법사를 계속 진행하여 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.3.1+
  • Android API: 최소 23+ (Android 6.0+), 권장 31+ (Android 12+)
  • 기기/에뮬레이터: Google Play Services가 설치된 Android 7.0+
  • 필수 의존성: com.onesignal:OneSignal:[5.6.1, 5.99.99]
  • Application 클래스: 올바른 SDK 초기화에 필수
  • App ID 형식: 36자 UUID (예: 12345678-1234-1234-1234-123456789012). 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 추가

  1. Android Studio에서 build.gradle.kts (Module: app) 또는 build.gradle (Module: app) 파일을 여세요
  2. dependencies 섹션에 OneSignal을 추가하세요:
OneSignal implementation 의존성이 추가된 Android Studio 앱 build.gradle.kts

앱의 build.gradle.kts 파일에 OneSignal을 추가하는 예시.

  1. Gradle 동기화: 표시되는 배너에서 Sync Now를 클릭하거나 File > Sync Project with Gradle Files로 이동하세요
Gradle 동기화가 의존성 충돌 없이 성공적으로 완료되었는지 확인하세요.

2단계. Application 클래스 생성 및 구성

모든 진입점에서 올바른 SDK 설정을 보장하려면 Application 클래스의 onCreate 메서드에서 OneSignal을 초기화하는 것이 모범 사례입니다. Application 클래스가 아직 없다면 생성하세요:
  1. File > New > Kotlin Class/File (또는 Java Class)
  2. 이름: ApplicationClass (또는 원하는 이름)
ApplicationClass라는 이름이 입력된 Android Studio New Kotlin Class 대화 상자

ApplicationClass라는 이름의 새 Kotlin 클래스를 생성하는 예시.

Application 클래스에 다음 OneSignal 코드를 추가하세요. YOUR_APP_ID를 Dashboard > Settings > Keys & IDs에서 확인한 실제 OneSignal App ID로 교체하세요.
OneSignal initWithContext와 requestPermission을 보여주는 Android Studio의 ApplicationClass.kt

ApplicationClass.kt 파일 예시.

Activity(예: MainActivity)에서 초기화하는 것은 딥 링크나 알림으로부터의 앱 콜드 스타트 시 호출되지 않을 수 있으므로 권장하지 않습니다. 안정성을 위해 항상 Application 클래스에서 OneSignal을 초기화하세요.
Application 클래스 등록:
  1. 앱의 AndroidManifest.xml을 여세요
  2. <application> 태그에 android:name=".ApplicationClass"를 추가하세요 (클래스 이름을 다르게 설정한 경우 .ApplicationClass를 실제 클래스 이름으로 교체하세요).
AndroidManifest.xml
<application> 태그에 tools:node="replace"가 있는지 확인하세요. 이 마커는 OneSignal의 PermissionsActivity를 포함해 라이브러리에서 병합된 컴포넌트를 제거합니다. 그러면 알림 권한 흐름이 ActivityNotFoundException으로 충돌합니다. tools:node="replace"를 제거하세요. 속성 하나만 재정의하려면 tools:replace="android:theme"(또는 변경 중인 속성)을 사용하세요.
android:name이 .ApplicationClass로 설정된 AndroidManifest.xml application 태그

.ApplicationClass 이름이 포함된 AndroidManifest.xml.

앱이 오류 없이 빌드되고 실행되는지 확인하세요.

3단계. 기본 알림 아이콘 구성 (권장)

기본 종 모양 아이콘을 ic_stat_onesignal_default라는 이름의 작은 아이콘으로 교체하세요. 투명한 배경 위에 단색 실루엣을 사용하세요. 그렇지 않으면 Android가 흰색 사각형으로 렌더링합니다.
  1. Android Asset Studio로 밀도별 아이콘을 생성하세요.
  2. ic_stat_onesignal_default를 각 밀도 폴더에 배치하세요: res/drawable-mdpi/(24×24)부터 res/drawable-xxxhdpi/(96×96)까지.
큰 아이콘, 강조 색상, Android 17 런처 아이콘 동작에 대해서는 알림 아이콘을 참조하세요.

4단계. 통합 테스트

구독 생성 확인:
  1. Google Play Services가 있는 기기 또는 에뮬레이터에서 앱을 실행하세요.
  2. Dashboard > Audience > Subscriptions를 확인하세요. 상태가 Never Subscribed로 표시됩니다.
  3. 권한 요청 프롬프트가 나타나면 수락하세요.
  4. 대시보드를 새로고침하세요. 상태가 Subscribed로 변경됩니다.
알림 허용을 요청하는 Android 푸시 권한 프롬프트

Android 푸시 권한 요청 프롬프트

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

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

푸시 권한을 허용한 후 대시보드를 새로고침하면 구독 상태가 'Subscribed'로 업데이트됩니다.

푸시 권한을 허용한 후 대시보드를 새로고침하면 구독 상태가 'Subscribed'로 업데이트됩니다

모바일 구독은 사용자가 기기에서 앱을 처음 열거나 같은 기기에서 앱을 삭제하고 다시 설치할 때 생성됩니다. 권한 요청 프롬프트를 수락하면 대시보드 상태가 Subscribed로 표시되어야 합니다.

테스트 사용자 및 세그먼트 생성

  1. 구독 옆에서 Options > Add as test user를 선택하고 이름을 입력하세요.
  2. Audience > Segments > New Segment로 이동하세요.
  3. 이름: Test Users, 필터 Test Users 추가 > Create Segment.
구독 레코드의 Options 메뉴에서 Add as test user가 강조 표시됨

테스트 사용자 추가

Test Users 필터로 'Test Users' 세그먼트 생성.

Test Users 필터로 'Test Users' 세그먼트 생성

이제 이 기기와 Test Users 세그먼트로 테스트 메시지를 보낼 수 있습니다.

API를 통한 테스트 푸시 전송

  1. **Settings > Keys & IDs**로 이동하세요.
  2. 제공된 코드에서 아래의 YOUR_APP_API_KEYYOUR_APP_ID를 실제 키로 교체하세요. 이 코드는 앞서 생성한 Test Users 세그먼트를 사용합니다.
푸시 알림의 이미지는 축소된 알림 보기에서 작게 표시됩니다. 알림을 펼치면 전체 이미지를 볼 수 있습니다.

이미지는 축소된 알림 보기에서 작게 표시됩니다. 알림을 펼치면 전체 이미지를 볼 수 있습니다.

확인된 수신을 보여주는 전송 통계 (무료 플랜에서는 사용 불가).

확인된 수신을 보여주는 전송 통계 (무료 플랜에서는 사용 불가)

테스트 기기가 커스텀 아이콘(구성한 경우)과 펼쳤을 때의 큰 이미지가 포함된 알림을 수신했는지 확인하세요. 유료 플랜에서는 Dashboard > Delivery > Sent Messages에서 확인된 수신(Confirmed receipt)을 볼 수 있습니다.
  • 알림이 수신되지 않나요? 모바일 푸시가 표시되지 않음을 참조하세요.
  • 커스텀 아이콘이 표시되지 않나요? 아이콘 이름이 ic_stat_onesignal_default이고 올바른 drawable 폴더에 있는지 확인하세요.
  • 문제가 있나요? API 요청과 앱 실행 처음부터 끝까지의 로그를 .txt 파일에 복사하세요. 두 파일을 support@onesignal.com으로 공유하세요.

인앱 메시지 테스트

  1. 30초 이상 앱을 종료하세요
  2. Dashboard > Messages > In-App > New In-App > Welcome 템플릿을 선택하세요
  3. 대상: Test Users 세그먼트
  4. 트리거: On app open
  5. 스케줄: Every time trigger conditions are satisfied
  6. Make Message Live를 클릭하세요
  7. 앱을 여세요
인앱 메시지로 'Test Users' 세그먼트 타겟팅.

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

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

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

인앱 메시지 스케줄링 옵션.

인앱 메시지 스케줄링 옵션

기기에 표시된 Welcome 인앱 메시지.

기기에 표시된 Welcome 인앱 메시지

테스트 기기에 Welcome 인앱 메시지가 표시되어야 합니다. 자세한 내용은 인앱 메시지 설정을 참조하세요.
메시지가 보이지 않나요?
  • 새 세션 시작
    • 앱을 강제 종료한 후 다시 열거나, 최소 30초 이상 종료 또는 백그라운드로 전환한 후 다시 여세요. 두 방법 모두 새 세션이 시작됩니다. 세션을 참조하세요.
    • 자세한 내용은 인앱 메시지가 표시되는 방식을 참조하세요.
  • Test Users 세그먼트에 여전히 포함되어 있나요?
    • 앱을 재설치하거나 기기를 변경한 경우, 테스트 사용자에 기기를 다시 추가하고 Test Users 세그먼트에 포함되어 있는지 확인하세요.
  • 문제가 있나요?
    • 위의 단계를 재현하면서 디버그 로그 가져오기를 따르세요. 이렇게 하면 support@onesignal.com으로 공유할 수 있는 추가 로그가 생성되며, 저희가 문제를 조사하는 데 도움을 드리겠습니다.
이제 구독, 테스트 사용자, 세그먼트를 갖추었습니다. 메시지 생성 API를 통해 이미지가 포함된 푸시인앱 메시지를 전송했습니다. 아래 내용을 계속 진행하여 사용자를 식별하고 더 많은 기능을 추가하세요.
OneSignal SDK를 성공적으로 설정하고 다음과 같은 중요한 개념을 배웠습니다:이 가이드를 계속 진행하여 앱에서 사용자를 식별하고 추가 기능을 설정하세요.

일반적인 오류 및 해결 방법

사용자 관리

이전에 모바일 구독을 생성하는 방법을 설명했습니다. 이제 OneSignal SDK를 사용하여 모든 구독(푸시, 이메일, SMS 포함)에서 사용자를 식별하는 방법으로 확장합니다.

External ID 할당 (권장)

External ID를 사용하여 백엔드의 사용자 식별자를 통해 기기, 이메일 주소 및 전화번호에서 사용자를 일관되게 식별하세요. 이를 통해 채널 및 서드파티 시스템 간에 메시징이 통합된 상태로 유지됩니다.
OneSignal은 구독(Subscription ID)과 사용자(OneSignal ID)에 대해 고유한 읽기 전용 ID를 생성합니다.SDK를 통해 External ID를 설정하는 것은 생성 방식에 관계없이 모든 구독에서 사용자를 식별하기 위해 강력히 권장됩니다.SDK 레퍼런스에서 login 메서드에 대해 자세히 알아보세요.

태그 및 커스텀 이벤트 추가

태그와 커스텀 이벤트는 모두 사용자에게 데이터를 추가합니다. 태그는 사용자 속성(예: username, role, status)을 위한 key-value 문자열입니다. 커스텀 이벤트는 JSON을 사용하며 일반적으로 동작(예: new_purchase 또는 abandoned_cart)을 나타냅니다. 두 가지 모두 메시지 개인화와 Journeys를 구동할 수 있습니다.
자세한 내용은 태그커스텀 이벤트를 참조하세요.

이메일 및/또는 SMS 구독 추가

푸시 외에도 이메일과 SMS를 통해 사용자에게 도달할 수 있습니다. 이메일 주소 또는 전화번호가 이미 OneSignal 앱에 존재하는 경우, SDK는 이를 기존 사용자에게 추가하며 중복을 생성하지 않습니다. 주소가 식별된 사용자에게 연결되도록 먼저 login()을 호출하세요.
External ID로 통합된 푸시, 이메일, SMS 구독이 있는 사용자 프로필.

External ID로 통합된 푸시, 이메일, SMS 구독이 있는 사용자 프로필

멀티채널 커뮤니케이션 모범 사례
  • 이메일 또는 SMS 구독을 추가하기 전에 명시적 동의를 받으세요.
  • 각 커뮤니케이션 채널의 이점을 사용자에게 설명하세요.
  • 사용자가 선호하는 채널을 선택할 수 있도록 채널 환경 설정을 제공하세요.

개인정보 보호 및 사용자 동의

OneSignal이 사용자 데이터를 수집하는 시점을 제어하려면 SDK의 동의 제어 메서드를 사용하세요. consentRequiredinitWithContext 전에 호출하세요.

푸시 권한 요청

앱이 열릴 때 즉시 requestPermission()을 호출하는 대신, 더 전략적인 접근 방식을 취하세요. 권한을 요청하기 전에 인앱 메시지를 사용하여 푸시 알림의 가치를 설명하세요. 모범 사례와 구현 세부 사항은 푸시 권한 요청 가이드를 참조하세요.

푸시, 사용자 및 인앱 이벤트 수신

SDK 리스너를 사용하여 사용자 동작 및 상태 변경에 반응하세요. OneSignal.initWithContext() 이후 Application 클래스에서 이를 추가하세요.

푸시 알림 이벤트

사용자 상태 변경

이 예시는 푸시 구독 옵저버를 사용합니다. 사용자 상태 옵저버와 알림 권한 옵저버는 모바일 SDK 레퍼런스에서 확인할 수 있습니다.

인앱 메시지 이벤트

추가 인앱 메시지 메서드는 모바일 SDK 레퍼런스에서 확인할 수 있습니다.

고급 설정 및 기능

Android 전용 기능

공통 기능

전체 SDK 메서드 문서는 모바일 SDK 레퍼런스를 참조하세요.

FAQ

Android Studio가 OneSignal을 확인할 수 없는 이유는 무엇인가요?

SDK 의존성이 누락되었거나 Gradle이 동기화되지 않았습니다. 앱 모듈의 build.gradlecom.onesignal:OneSignal:[5.6.1, 5.99.99]를 추가하고 File > Sync Project with Gradle Files를 사용하세요.

Application 클래스를 찾을 수 없는 이유는 무엇인가요?

클래스가 매니페스트에 등록되지 않았습니다. AndroidManifest.xml<application> 태그에 android:name=".ApplicationClass"(또는 사용 중인 클래스 이름)를 추가하세요.

에뮬레이터에서 Google Play Services를 사용할 수 없다고 표시되는 이유는 무엇인가요?

에뮬레이터 이미지에 Play Services가 포함되어 있지 않습니다. Play Store가 있는 기기 또는 Google APIs가 포함된 에뮬레이터 시스템 이미지를 사용하세요.

알림에 기본 Android 아이콘이 표시되는 이유는 무엇인가요?

작은 아이콘이 누락되었거나 이름이 잘못되었습니다. 각 res/drawable-* 밀도 폴더에 ic_stat_onesignal_default를 추가하세요. 알림 아이콘을 참조하세요.

테스트 기기가 푸시를 수신하지 못한 이유는 무엇인가요?

FCM 자격 증명이 구성되지 않았거나 기기가 구독되지 않았습니다. 0단계를 완료하고 구독 상태가 Subscribed인지 확인하세요. 그런 다음 모바일 푸시가 표시되지 않음을 참조하세요.

인앱 메시지가 표시되지 않는 이유는 무엇인가요?

인앱 메시지는 새 세션이 필요합니다. 앱을 강제 종료하거나 최소 30초 이상 백그라운드로 전환한 후 다시 여세요. 기기가 여전히 Test Users 세그먼트에 포함되어 있는지 확인하세요. 세션인앱 메시지가 표시되는 방식을 참조하세요.

Manifest merger failed의 원인은 무엇인가요?

<application>android:name 값 충돌 또는 중복 권한이 원인입니다. 병합된 매니페스트에서 두 번째 Application 클래스를 검색하고 android:name을 하나만 유지하세요.

배터리 최적화가 알림을 차단하는 이유는 무엇인가요?

일부 OEM은 백그라운드 작업을 제한합니다. 기기가 절전 모드에 들어간 후 알림이 중단된다면 사용자에게 앱의 배터리 최적화를 비활성화하도록 요청하세요.

더 많은 로그 출력을 얻으려면 어떻게 하나요?

OneSignal.Debug.logLevel = LogLevel.VERBOSE(Kotlin) 또는 OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE)(Java)를 설정하고, 문제를 재현한 후 logcat을 캡처하세요. 디버그 로그 가져오기를 참조하세요.
도움이 필요하신가요?지원 팀과 채팅하거나 support@onesignal.com으로 이메일을 보내주세요.다음을 포함해 주세요:
  • 발생한 문제의 세부 정보 및 재현 단계(가능한 경우)
  • OneSignal 앱 ID
  • External ID 또는 Subscription ID(해당하는 경우)
  • OneSignal 대시보드에서 테스트한 메시지의 URL(해당하는 경우)
  • 관련 로그 또는 오류 메시지
기꺼이 도와드리겠습니다!