Google은 흑인 공동체를 위한 인종적 평등을 추구하기 위해 노력하고 있습니다. 자세히 알아보기

Android에서 Firebase 클라우드 메시징 클라이언트 앱 설정

Firebase 클라우드 메시징 Android 클라이언트 앱을 만들려면 FirebaseMessaging API와 Gradle이 있는 Android 스튜디오 1.4 이상을 사용하세요. 이 페이지의 안내에서는 Android 프로젝트에 Firebase를 추가하는 단계를 완료했다고 가정합니다.

FCM 클라이언트에 Android 4.1 이상을 실행하며 Google Play 스토어 앱도 설치되어 있는 기기 또는 Google API로 Android 4.1을 실행하는 에뮬레이터가 필요합니다. Google Play 스토어를 통해서만 Android 앱을 배포하도록 제한되지는 않습니다.

SDK 설정

이 섹션에서 설명하는 작업은 앱에서 다른 Firebase 기능을 사용 설정한 경우 이미 완료되었을 수 있습니다.

시작하기 전에

  • Android 스튜디오를 설치하거나 최신 버전으로 업데이트합니다.

  • 프로젝트가 다음 요구사항을 충족하는지 확인합니다.

    • API 수준 16(Jelly Bean) 이상 타겟팅
    • Gradle 4.1 이상 사용
    • 다음 버전 요구사항을 충족하는 Jetpack(AndroidX) 사용
      • com.android.tools.build:gradle v3.2.1 이상
      • compileSdkVersion 28 이상
  • 실제 기기를 설정하거나 에뮬레이터를 사용하여 앱을 실행합니다.
    에뮬레이터는 Google Play에서 에뮬레이터 이미지를 사용해야 합니다.

  • Google 계정을 사용하여 Firebase에 로그인합니다.

Android 프로젝트가 준비되지 않았다면 빠른 시작 샘플 중 하나를 다운로드하여 Firebase 제품을 사용해 볼 수 있습니다.

Firebase 프로젝트 만들기

Firebase를 Android 앱에 추가하려면 먼저 Android 앱에 연결할 Firebase 프로젝트를 만드세요. Firebase 프로젝트에 대한 자세한 내용은 Firebase 프로젝트 이해를 참조하세요.

Firebase에 앱 등록

Android 앱에서 Firebase를 사용하려면 Firebase 프로젝트에 앱을 등록해야 합니다. 앱 등록이란 보통 프로젝트에 앱을 '추가'하는 것을 의미합니다.

  1. Firebase Console로 이동합니다.

  2. 프로젝트 개요 페이지 중앙에 있는 Android 아이콘() 또는 앱 추가를 클릭하여 설정 워크플로를 시작합니다.

  3. Android 패키지 이름 필드에 앱의 패키지 이름을 입력합니다.

  4. (선택사항) 다른 앱 정보(앱 닉네임디버그 서명 인증서 SHA-1)를 입력합니다.

  5. 앱 등록을 클릭합니다.

Firebase 구성 파일 추가

  1. 앱에 Firebase Android 구성 파일을 추가합니다.

    1. google-services.json 다운로드를 클릭하여 Firebase Android 구성 파일(google-services.json)을 가져옵니다.

    2. 구성 파일을 앱의 모듈(앱 수준) 디렉터리로 이동합니다.

  2. 앱에서 Firebase 제품을 사용할 수 있도록 google-services 플러그인을 Gradle 파일에 추가합니다.

    1. 루트 수준(프로젝트 수준) Gradle 파일(build.gradle)에서 Google 서비스 Gradle 플러그인을 포함하는 규칙을 추가합니다. Google의 Maven 저장소도 있는지 확인합니다.

      buildscript {
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
        }
      
        dependencies {
          // ...
      
          // Add the following line:
          classpath 'com.google.gms:google-services:4.3.4'  // Google Services plugin
        }
      }
      
      allprojects {
        // ...
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
          // ...
        }
      }
      
    2. 모듈(앱 수준) Gradle 파일(일반적으로 app/build.gradle)에서 Google 서비스 Gradle 플러그인을 적용합니다.

      apply plugin: 'com.android.application'
      // Add the following line:
      apply plugin: 'com.google.gms.google-services'  // Google Services plugin
      
      android {
        // ...
      }
      

앱에 Firebase SDK 추가

  1. Firebase Android BoM을 사용하여 모듈(앱 수준) Gradle 파일(일반적으로 app/build.gradle)에서 Firebase 클라우드 메시징 Android 라이브러리의 종속 항목을 선언합니다.

    Firebase 클라우드 메시징 사용 환경을 최적화하려면 프로젝트에 Google 애널리틱스를 사용 설정하는 것이 좋습니다. 또한 애널리틱스를 설정하는 과정에서 앱에 Google 애널리틱스용 Firebase SDK를 추가해야 합니다.

    자바

    dependencies {
        // Import the BoM for the Firebase platform
        implementation platform('com.google.firebase:firebase-bom:26.0.0')
    
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When using the BoM, you don't specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging'
        implementation 'com.google.firebase:firebase-analytics'
    }
    

    Firebase Android BoM을 사용하면 앱에서 항상 호환되는 Firebase Android 라이브러리 버전을 사용합니다.

    (대안) BoM을 사용하지 않고 Firebase 라이브러리 종속 항목을 선언합니다.

    Firebase BoM을 사용하지 않도록 선택한 경우에는 종속 항목 줄에 각 Firebase 라이브러리 버전을 지정해야 합니다.

    앱에서 여러 Firebase 라이브러리를 사용하는 경우 모든 버전이 호환되도록 BoM을 사용하여 라이브러리 버전을 관리하는 것이 좋습니다.

    dependencies {
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When NOT using the BoM, you must specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging:21.0.0'
        implementation 'com.google.firebase:firebase-analytics:18.0.0'
    }
    

    Kotlin+KTX

    dependencies {
        // Import the BoM for the Firebase platform
        implementation platform('com.google.firebase:firebase-bom:26.0.0')
    
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When using the BoM, you don't specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging-ktx'
        implementation 'com.google.firebase:firebase-analytics-ktx'
    }
    

    Firebase Android BoM을 사용하면 앱에서 항상 호환되는 Firebase Android 라이브러리 버전을 사용합니다.

    (대안) BoM을 사용하지 않고 Firebase 라이브러리 종속 항목을 선언합니다.

    Firebase BoM을 사용하지 않도록 선택한 경우에는 종속 항목 줄에 각 Firebase 라이브러리 버전을 지정해야 합니다.

    앱에서 여러 Firebase 라이브러리를 사용하는 경우 모든 버전이 호환되도록 BoM을 사용하여 라이브러리 버전을 관리하는 것이 좋습니다.

    dependencies {
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When NOT using the BoM, you must specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging-ktx:21.0.0'
        implementation 'com.google.firebase:firebase-analytics-ktx:18.0.0'
    }
    

  2. 앱을 동기화하여 모든 종속 항목에 필요한 버전이 있는지 확인합니다.

앱 매니페스트 수정

앱의 매니페스트에 다음을 추가합니다.

  • FirebaseMessagingService를 확장하는 서비스를 추가합니다. 백그라운드에서 앱의 알림을 수신하는 것 외에 다른 방식으로 메시지를 처리하려는 경우에 필요합니다. 포그라운드 앱의 알림 수신, 데이터 페이로드 수신, 업스트림 메시지 전송 등을 수행하려면 이 서비스를 확장해야 합니다.
  • <service
        android:name=".java.MyFirebaseMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
  • (선택사항) 애플리케이션 구성요소에 기본 알림 아이콘 및 색상을 설정하는 메타데이터 요소를 추가합니다. Android는 받은 메시지에 아이콘 또는 색상이 명시적으로 설정되지 않은 경우 이 값을 사용합니다.
  • <!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
         See README(https://goo.gl/l4GJaQ) for more. -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_icon"
        android:resource="@drawable/ic_stat_ic_notification" />
    <!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
         notification message. See README(https://goo.gl/6BKBk7) for more. -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_color"
        android:resource="@color/colorAccent" />
  • (선택사항) Android 8.0(API 수준 26) 이상부터는 알림 채널이 지원 및 권장됩니다. FCM은 기본적인 설정으로 기본 알림 채널을 제공합니다. 기본 채널을 직접 만들어 사용하려면 아래와 같이 default_notification_channel_id를 알림 채널 객체의 ID로 설정합니다. 받은 메시지에 명시적으로 설정된 알림 채널이 없으면 FCM에서는 항상 이 값을 사용합니다. 자세한 내용은 알림 채널 관리를 참조하세요.
  • <meta-data
        android:name="com.google.firebase.messaging.default_notification_channel_id"
        android:value="@string/default_notification_channel_id" />

기기 등록 토큰 액세스

FCM SDK는 앱을 처음 시작할 때 클라이언트 앱 인스턴스용 등록 토큰을 생성합니다. 단일 기기를 타겟팅하거나 기기 그룹을 만들려면 FirebaseMessagingService를 확장하고 onNewToken을 재정의하여 이 토큰에 액세스해야 합니다.

이 섹션에서는 토큰을 검색하고 토큰의 변경을 모니터링하는 방법을 설명합니다. 토큰은 최초 시작 후에 순환될 수 있으므로 마지막으로 업데이트된 등록 토큰을 가져오는 것이 좋습니다.

다음과 같은 경우에 등록 토큰이 변경될 수 있습니다.

  • 새 기기에서 앱 복원
  • 사용자가 앱 삭제/재설치
  • 사용자가 앱 데이터 소거

현재 등록 토큰 가져오기

현재 토큰을 가져오려면 FirebaseMessaging.getInstance().getToken()을 호출합니다.

자바

FirebaseMessaging.getInstance().getToken()
    .addOnCompleteListener(new OnCompleteListener<String>() {
        @Override
        public void onComplete(@NonNull Task<String> task) {
          if (!task.isSuccessful()) {
            Log.w(TAG, "Fetching FCM registration token failed", task.getException());
            return;
          }

          // Get new FCM registration token
          String token = task.getResult();

          // Log and toast
          String msg = getString(R.string.msg_token_fmt, token);
          Log.d(TAG, msg);
          Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
        }
    });

Kotlin+KTX

FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task ->
    if (!task.isSuccessful) {
        Log.w(TAG, "Fetching FCM registration token failed", task.exception)
        return@OnCompleteListener
    }

    // Get new FCM registration token
    val token = task.result

    // Log and toast
    val msg = getString(R.string.msg_token_fmt, token)
    Log.d(TAG, msg)
    Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
})

토큰 생성 모니터링

새 토큰이 생성될 때마다 onNewToken 콜백이 호출됩니다.

자바

/**
 * Called if FCM registration token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the
 * FCM registration token is initially generated so this is where you would retrieve
 * the token.
 */
@Override
public void onNewToken(String token) {
    Log.d(TAG, "Refreshed token: " + token);

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token);
}

Kotlin+KTX

/**
 * Called if the FCM registration token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the
 * FCM registration token is initially generated so this is where you would retrieve the token.
 */
override fun onNewToken(token: String) {
    Log.d(TAG, "Refreshed token: $token")

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token)
}

토큰이 확보되었으면 앱 서버로 전송하고 원하는 방법으로 저장할 수 있습니다.

Google Play 서비스 확인

Play 서비스 SDK를 사용하는 앱은 Google Play 서비스 기능에 액세스하기 전에 항상 기기에 호환되는 Google Play 서비스 APK가 있는지 확인해야 합니다. 기본 활동의 onCreate() 메서드 및 onResume() 메서드 등 두 위치에서 확인 작업을 하는 것이 좋습니다. onCreate()로 확인하면 확인에 성공하지 못한 앱을 사용할 수 없게 됩니다. onResume()으로 확인하면 사용자가 '뒤로' 버튼과 같은 다른 수단을 통해 실행 중인 앱으로 돌아오는 경우에 확인 작업이 계속 수행될 수 있습니다.

기기에 호환되는 Google Play 서비스 버전이 없으면 앱에서 GoogleApiAvailability.makeGooglePlayServicesAvailable()을 호출하여 사용자가 Play 스토어에서 Google Play 서비스를 다운로드하도록 허용할 수 있습니다.

자동 초기화 방지

FCM 등록 토큰이 생성되면 라이브러리는 식별자와 구성 데이터를 Firebase에 업로드합니다. 토큰이 자동 생성되는 것을 방지하려면 AndroidManifest.xml에 다음 메타데이터 값을 추가하여 애널리틱스 수집 및 FCM 자동 초기화를 사용 중지해야 합니다(둘 다 사용 중지해야 함).

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

FCM 자동 초기화를 다시 사용 설정하려면 런타임 호출을 만듭니다.

자바

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

Kotlin+KTX

FirebaseMessaging.getInstance().isAutoInitEnabled = true

애널리틱스 수집을 다시 사용 설정하려면 FirebaseAnalytics 클래스의 setAnalyticsCollectionEnabled() 메서드를 호출합니다. 예를 들면 다음과 같습니다.

setAnalyticsCollectionEnabled(true);

이 값을 설정하고 나면 앱을 다시 시작해도 유지됩니다.

다음 단계

클라이언트 앱이 설정되었으면 알림 작성기를 사용하여 다운스트림 메시지를 보낼 수 있습니다. 이 기능은 빠른 시작 샘플에 나와 있으며 샘플을 다운로드하여 실행하거나 검토할 수 있습니다.

앱에 다른 고급 동작을 추가하려면 인텐트 필터를 선언하고 받은 메시지에 응답하는 작업을 구현하면 됩니다. 자세한 내용은 앱 서버에서 메시지를 전송하는 방법 가이드를 참조하세요.

이러한 기능을 활용하려면 서버 구현과 서버 프로토콜(HTTP 또는 XMPP) 또는 Admin SDK 구현이 필요합니다.