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

Follow the instructions at:
https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md

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. Firebase 서버 키 또는 서비스 계정 정보를 입력하세요.
  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.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 추가

  1. Android Studio에서 build.gradle.kts (Module: app) 또는 build.gradle (Module: app) 파일을 여세요
  2. dependencies 섹션에 OneSignal을 추가하세요:
implementation("com.onesignal:OneSignal:[5.6.1, 5.6.99]")
  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 (또는 원하는 이름)
Application 클래스에 다음 OneSignal 코드를 추가하세요. YOUR_APP_ID를 Dashboard > Settings > Keys & IDs에서 확인한 실제 OneSignal App ID로 교체하세요.
// FILE: ApplicationClass.kt
// PURPOSE: Initialize OneSignal when your app launches
// REQUIREMENT: Must be registered in AndroidManifest.xml

package com.your.package.name // Replace with your actual package name

import android.app.Application
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

import com.onesignal.OneSignal
import com.onesignal.debug.LogLevel

class ApplicationClass : Application() {
    override fun onCreate() {
        super.onCreate()

        // Enable verbose logging to debug issues (remove in production)
        OneSignal.Debug.logLevel = LogLevel.VERBOSE

        // Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
        OneSignal.initWithContext(this, "YOUR_APP_ID")

        // Prompt user for push notification permission
        // In production, consider using an in-app message instead for better opt-in rates
        CoroutineScope(Dispatchers.IO).launch {
            OneSignal.Notifications.requestPermission(false)
        }
    }
}
Activity(예: MainActivity)에서 초기화하는 것은 딥 링크나 알림으로부터의 앱 콜드 스타트 시 호출되지 않을 수 있으므로 권장하지 않습니다. 안정성을 위해 항상 Application 클래스에서 OneSignal을 초기화하세요.
Application 클래스 등록:
  1. 앱의 AndroidManifest.xml을 여세요
  2. <application> 태그에 android:name=".ApplicationClass"를 추가하세요 (클래스 이름을 다르게 설정한 경우 .ApplicationClass를 실제 클래스 이름으로 교체하세요).
AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application
        android:name=".ApplicationClass"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        ...
      </application>

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

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

앱의 브랜딩에 맞게 알림 아이콘을 커스터마이즈하세요. 이 단계는 선택 사항이지만 전문적인 외관을 위해 권장됩니다.

4단계. 통합 테스트

구독 생성 확인:
  1. Google Play Services가 있는 기기 또는 에뮬레이터에서 앱을 실행하세요
  2. Dashboard > Audience > Subscriptions를 확인하세요 — 상태가 “Never Subscribed”로 표시됩니다
  3. 권한 요청 프롬프트가 나타나면 수락하세요
  4. 대시보드를 새로고침하세요 — 상태가 “Subscribed”로 변경됩니다
iOS 및 Android 푸시 권한 요청 프롬프트 예시.
'Never Subscribed' 상태의 구독을 보여주는 대시보드.
푸시 권한을 허용한 후 대시보드를 새로고침하면 구독 상태가 'Subscribed'로 업데이트됩니다.
모바일 구독을 성공적으로 생성했습니다. 모바일 구독은 사용자가 기기에서 앱을 처음 열거나 같은 기기에서 앱을 삭제하고 다시 설치할 때 생성됩니다.

테스트 구독 및 세그먼트 생성

  1. 구독 옆의 **⋮**을 클릭 > Add to Test Subscriptions > 이름을 지정하세요
  2. Audience > Segments > New Segment로 이동하세요
  3. 이름: Test Users, 필터 Test Users 추가 > Create Segment
테스트 구독 추가.
Test Users 필터로 'Test Users' 세그먼트 생성.
테스트 사용자 세그먼트를 성공적으로 생성했습니다.이제 이 개별 기기와 테스트 사용자 그룹에 메시지 전송을 테스트할 수 있습니다.

API를 통한 테스트 푸시 전송

  1. **Settings > Keys & IDs**로 이동하세요.
  2. 아래 코드에서 YOUR_APP_API_KEYYOUR_APP_ID를 실제 키로 교체하세요. 이 코드는 앞서 생성한 Test Users 세그먼트를 사용합니다.
curl -X POST 'https://api.onesignal.com/notifications' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Key YOUR_APP_API_KEY' \
  -d '{
    "app_id": "YOUR_APP_ID",
    "target_channel": "push",
    "name": "Testing basic setup",
    "headings": { "en": "👋" },
    "contents": {"en": "Hello world!"},
    "included_segments": ["Test Users"],
    "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  }'
푸시 알림의 이미지는 축소된 알림 보기에서 작게 표시됩니다. 알림을 펼치면 전체 이미지를 볼 수 있습니다.
확인된 전송을 보여주는 전송 통계 (무료 플랜에서는 사용 불가).
테스트 기기가 다음 항목이 포함된 알림을 수신했는지 확인하세요:
  • 커스텀 아이콘 (구성한 경우)
  • 펼쳤을 때의 큰 이미지
  • Dashboard > Delivery > Sent Messages에 “Confirmed” 상태 표시 (무료 플랜에서는 사용 불가).
  • 알림이 수신되지 않나요? 모바일 푸시가 표시되지 않음을 참조하세요.
  • 커스텀 아이콘이 표시되지 않나요? 아이콘 이름이 onesignal_small_icon_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' 세그먼트 타겟팅.
인앱 Welcome 메시지 커스터마이즈 예시.
인앱 메시지 스케줄링 옵션.
기기에 표시된 Welcome 인앱 메시지.
테스트 기기가 인앱 메시지를 수신했는지 확인하세요. 자세한 내용은 인앱 메시지 설정 가이드를 참조하세요.
메시지가 보이지 않나요?
  • 새 세션 시작
    • 앱을 최소 30초 이상 종료하거나 백그라운드로 전환한 후 다시 여세요. 이렇게 하면 새 세션이 시작됩니다.
    • 자세한 내용은 인앱 메시지가 표시되는 방식을 참조하세요.
  • Test Users 세그먼트에 여전히 포함되어 있나요?
    • 앱을 재설치하거나 기기를 변경한 경우, 테스트 구독에 기기를 다시 추가하고 Test Users 세그먼트에 포함되어 있는지 확인하세요.
  • 문제가 있나요?
    • 위의 단계를 재현하면서 디버그 로그 가져오기를 따르세요. 이렇게 하면 support@onesignal.com으로 공유할 수 있는 추가 로그가 생성되며, 저희가 문제를 조사하는 데 도움을 드리겠습니다.
OneSignal SDK를 성공적으로 설정하고 다음과 같은 중요한 개념을 배웠습니다:이 가이드를 계속 진행하여 앱에서 사용자를 식별하고 추가 기능을 설정하세요.

일반적인 오류 및 해결 방법

오류 / 증상원인해결 방법
Cannot resolve symbol 'OneSignal'SDK 의존성이 추가되지 않았거나 Gradle이 동기화되지 않음build.gradle에 의존성을 추가하고 프로젝트를 동기화하세요
Application class not foundApplication 클래스가 매니페스트에 등록되지 않음<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
// Call when user logs in or is identified, safe to call multiple times
// Typically used in a login completion handler, or on app launch if already authenticated
fun onUserAuthenticated(userId: String) {
    OneSignal.login(userId)
}

// If you want to remove the External ID from the Subscription, setting it to an anonymous user
fun onUserLoggedOut() {
    OneSignal.logout()
}
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
// Add a tag when the user's name is set
OneSignal.User.addTag("username", "john_doe")

// Create a custom event when user abandoned a cart
val properties = mapOf(
    "product_id" to "123456",
    "product_name" to "Product Name",
    "product_price" to 100,
    "product_quantity" to 1
)
OneSignal.User.trackEvent("abandoned_cart", properties)
태그와 커스텀 이벤트를 사용하는 방법에 대한 자세한 내용은 태그커스텀 이벤트 가이드를 참조하세요.

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

푸시 알림 외에도 이메일과 SMS 채널을 통해 사용자에게 도달할 수 있습니다. 이메일 주소 및/또는 전화번호가 이미 OneSignal 앱에 존재하는 경우, SDK는 이를 기존 사용자에게 추가하며 중복을 생성하지 않습니다. 자세한 내용과 Java 코드 예시는 모바일 SDK 레퍼런스를 참조하세요.
Kotlin
// Add email subscription
// Call when user provides their email (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addEmail("user@example.com")

// Add SMS subscription
// Use E.164 format: + country code + number
// Call when user provides their phone number (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addSms("+15551234567")
External ID로 통합된 푸시, 이메일, SMS 구독이 있는 사용자 프로필.
멀티채널 커뮤니케이션 모범 사례
  • 이메일 또는 SMS 구독을 추가하기 전에 명시적 동의를 받으세요.
  • 각 커뮤니케이션 채널의 이점을 사용자에게 설명하세요.
  • 사용자가 선호하는 채널을 선택할 수 있도록 채널 환경 설정을 제공하세요.

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

OneSignal이 사용자 데이터를 수집하는 시점을 제어하려면 SDK의 동의 제어 메서드를 사용하세요. 자세한 내용과 Java 코드 예시는 모바일 SDK 레퍼런스를 참조하세요.
Kotlin
// In ApplicationClass onCreate(), BEFORE OneSignal.initWithContext()
// Use this if your app requires GDPR or other privacy consent before data collection
OneSignal.consentRequired = true

// Later, after user grants consent (e.g., taps "I Agree" on your consent screen)
OneSignal.consentGiven = true
개인정보 보호 및 보안 문서에서 자세히 알아보세요:

푸시 권한 요청

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

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

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

푸시 알림 이벤트

Kotlin
// Add click listener to handle when users tap notifications
val clickListener = object : INotificationClickListener {
  override fun onClick(event: INotificationClickEvent) {
    Log.d("OneSignal", "Notification clicked: ${event.notification.title}")
  }
}
OneSignal.Notifications.addClickListener(clickListener)

사용자 상태 변경

아래 예시는 푸시 구독 옵저버를 사용하는 방법을 보여줍니다. 사용자 상태 옵저버 및 알림 권한 옵저버와 같은 다른 사용자 상태 이벤트는 모바일 SDK 레퍼런스에서 확인할 수 있습니다.
Kotlin
// Add subscription observer to track push subscription changes
class MyObserver : IPushSubscriptionObserver {
  init {
    OneSignal.User.pushSubscription.addObserver(this)
  }

  override fun onPushSubscriptionChange(state: PushSubscriptionChangedState) {
    if (state.current.optedIn) {
      println("User is now opted-in with push token: ${state.current.token}")
    }
  }
}

인앱 메시지 이벤트

추가 인앱 메시지 메서드는 모바일 SDK 레퍼런스에서 확인할 수 있습니다.
Kotlin
// Add click listener for in-app message interactions
val clickListener = object : IInAppMessageClickListener {
  override fun onClick(event: IInAppMessageClickEvent) {
    print(event.result.actionId)
  }
}
OneSignal.InAppMessages.addClickListener(clickListener)

고급 설정 및 기능

Android 전용 기능

공통 기능

전체 SDK 메서드 문서는 모바일 SDK 레퍼런스를 참조하세요.
도움이 필요하신가요?지원 팀과 채팅하거나 support@onesignal.com으로 이메일을 보내주세요.다음을 포함해 주세요:
  • 발생한 문제의 세부 정보 및 재현 단계(가능한 경우)
  • OneSignal 앱 ID
  • External ID 또는 Subscription ID(해당하는 경우)
  • OneSignal 대시보드에서 테스트한 메시지의 URL(해당하는 경우)
  • 관련 로그 또는 오류 메시지
기꺼이 도와드리겠습니다!