백그라운드 앱에 테스트 메시지 보내기

FCM을 시작하기 위해 앱이 백그라운드 상태일 때 알림 작성기에서 개발 기기로 테스트 알림 메시지를 전송하는 가장 단순한 사용 사례부터 살펴보겠습니다. 이 페이지에는 설정부터 검증까지 이 작업을 수행하기 위한 모든 단계가 제시되어 있으므로, FCM용 Android 클라이언트 앱 설정을 마친 경우 일부 단계는 이미 완료된 상태일 수 있습니다.

SDK 설정

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

시작하기 전에

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

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

  • API 수준 19(KitKat) 이상 타겟팅
  • Android 4.4 이상 사용
  • 다음 버전 요구사항을 충족하는 Jetpack(AndroidX) 사용
    • com.android.tools.build:gradle v3.2.1 이상
    • compileSdkVersion 28 이상

• 실제 기기를 설정하거나 에뮬레이터를 사용하여 앱을 실행합니다.
  Google Play 서비스에 대한 종속 항목이 있는 Firebase SDK를 사용하려면 기기 또는 에뮬레이터에 Google Play 서비스가 설치되어 있어야 합니다.

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

Android 프로젝트가 준비되지 않았지만 Firebase 제품을 사용해 보고자 하는 경우 빠른 시작 샘플 중 하나를 다운로드하세요.

Firebase 프로젝트 만들기

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

Firebase에 앱 등록

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

1. Firebase Console로 이동합니다.

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

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

   패키지 이름은 무엇이며 어디에서 찾을 수 있나요?

   • 패키지 이름은 기기와 Google Play 스토어에서 앱을 고유하게 식별하는 역할을 합니다.

   • 패키지 이름을 애플리케이션 ID라고도 합니다.

   • 모듈(앱 수준) Gradle 파일(일반적으로 app/build.gradle)에서 앱의 패키지 이름(패키지 이름 예시: com.yourcompany.yourproject)을 찾습니다.

   • 패키지 이름 값은 대소문자를 구분하며 Firebase 프로젝트에 등록한 후에는 해당 Firebase Android 앱의 패키지 이름을 변경할 수 없습니다.

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

   Firebase에서 앱 닉네임과 디버그 서명 인증서 SHA-1은 어떻게 사용되나요?

   • 앱 닉네임: 닉네임은 편의상 지정하는 내부용 식별자로 Firebase Console에서 본인만 볼 수 있습니다.

   • 디버그 서명 인증서 SHA-1: SHA-1 해시는 Firebase 인증(Google 로그인 또는 전화번호 로그인을 사용하는 경우) 및 Firebase 동적 링크에 필요합니다.

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

Firebase 구성 파일 추가

1. Firebase Android 구성 파일(google-services.json)을 다운로드한 후 앱에 추가합니다.

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

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

   이 구성 파일에 대해 알아야 할 사항은 무엇인가요?

   • Firebase 구성 파일에는 고유하지만 보안 비밀은 아닌 프로젝트 식별자가 있습니다. 이 구성 파일에 대한 자세한 내용은 Firebase 프로젝트 이해를 참조하세요.

   • 언제든지 다시 Firebase 구성 파일을 다운로드할 수 있습니다.

   • 구성 파일 이름에 (2)와 같은 문자가 추가되지 않았는지 확인합니다.

2. google-services.json 구성 파일의 값이 Firebase SDK에 액세스할 수 있게 하려면 Google 서비스 Gradle 플러그인(google-services)이 필요합니다.

   1. 루트 수준(프로젝트 수준) Gradle 파일(<project>/build.gradle)에서 Google 서비스 플러그인을 buildscript 종속 항목으로 추가합니다.

      buildscript {
      
          repositories {
            // Make sure that you have the following two repositories
            google()  // Google's Maven repository
            mavenCentral()  // Maven Central repository
          }
      
          dependencies {
            ...
      
            // Add the dependency for the Google services Gradle plugin
            classpath 'com.google.gms:google-services:4.3.14'
          }
      }
      
      allprojects {
        ...
      
        repositories {
          // Make sure that you have the following two repositories
          google()  // Google's Maven repository
          mavenCentral()  // Maven Central repository
        }
      }
      

   2. 모듈(앱 수준) Gradle 파일(일반적으로 <project>/<app-module>/build.gradle)에서 Google 서비스 플러그인을 추가합니다.

      plugins {
          id 'com.android.application'
      
          // Add the Google services Gradle plugin
          id 'com.google.gms.google-services'
          ...
      }
      

앱에 Firebase SDK 추가

1. 모듈(앱 수준) Gradle 파일(일반적으로 <project>/<app-module>/build.gradle)에서 Firebase 클라우드 메시징 Android 라이브러리의 종속 항목을 추가합니다. 라이브러리 버전 관리를 제어하는 데 Firebase Android BoM을 사용하는 것이 좋습니다.

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

   Java

   dependencies {
       // Import the BoM for the Firebase platform
       implementation platform('com.google.firebase:firebase-bom:30.4.1')
   
       // Add 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 {
       // Add 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:23.0.8'
       implementation 'com.google.firebase:firebase-analytics:21.1.1'
   }
   

   Kotlin+KTX

   dependencies {
       // Import the BoM for the Firebase platform
       implementation platform('com.google.firebase:firebase-bom:30.4.1')
   
       // Add 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 {
       // Add 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:23.0.8'
       implementation 'com.google.firebase:firebase-analytics-ktx:21.1.1'
   }
   

2. Android 프로젝트를 Gradle 파일과 동기화합니다.

   커스텀 지원 호출 및 디슈가링 사용 설정과 관련된 빌드 실패가 발생하는 경우 해결 방법은 다음과 같습니다.

   Android Gradle 플러그인(AGP) v4.2 이하를 사용하는 Gradle 빌드에서는 자바 8 지원을 사용 설정해야 합니다. 그렇지 않으면 Firebase SDK를 추가할 때 이러한 Android 프로젝트에 빌드 실패가 발생합니다.

   빌드 실패를 해결하려면 다음 두 가지 옵션 중 하나를 수행하면 됩니다.

   • 오류 메시지에 나열된 compileOptions를 앱 수준 build.gradle 파일에 추가합니다.
   • Android 프로젝트의 minSdkVersion을 26 이상으로 높입니다.

   이 빌드 실패에 대한 자세한 내용은 이 FAQ를 참조하세요.

등록 토큰 액세스

특정 기기로 메시지를 보내려면 기기의 등록 토큰을 알아야 합니다. 알림 콘솔의 필드에 토큰을 입력해야 이 가이드를 마칠 수 있으므로 토큰을 검색한 후 복사하거나 안전하게 저장해 두세요.

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();
        }
    });

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 콜백이 호출됩니다.

/**
 * There are two scenarios when onNewToken is called:
 * 1) When a new token is generated on initial app startup
 * 2) Whenever an existing token is changed
 * Under #2, there are three scenarios when the existing token is changed:
 * A) App is restored to a new device
 * B) User uninstalls/reinstalls the app
 * C) User clears app data
 */
@Override
public void onNewToken(@NonNull 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);
}
MyFirebaseMessagingService.java

/**
 * 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)
}
MyFirebaseMessagingService.kt

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

테스트 알림 메시지 전송

1. 대상 기기에 앱을 설치하고 실행합니다.

2. 앱을 기기에서 백그라운드 상태로 만듭니다.

3. 알림 작성기를 열고 새 알림을 선택합니다.

4. 메시지 본문을 입력합니다.

5. 테스트 메시지 보내기를 선택합니다.

6. FCM 등록 토큰 추가 필드에 이 가이드의 앞 섹션에서 가져온 등록 토큰을 입력합니다.

7. 테스트를 클릭합니다.

테스트를 클릭하면 타겟팅된 클라이언트 기기(백그라운드 상태의 앱 포함)의 작업 표시줄에 알림이 표시됩니다.

앱으로 전송된 메시지의 통계를 파악하려면, Apple 및 Android 기기에서 열린 전송 메시지 수와 Android 앱의 '노출수'(사용자에게 표시된 알림) 데이터가 기록된 FCM 보고 대시보드를 확인합니다.

다음 단계

포그라운드 앱에 메시지 전송

백그라운드 앱에 알림 메시지를 보내는 데 성공했으면 Android 앱에서 메시지 수신을 참조하여 포그라운드 앱에 전송하는 방법을 알아보세요.

알림 메시지 이외의 고급 기능

앱에 단순한 알림 메시지 이외에 더 많은 고급 기능을 추가하려면 다음을 참조하세요.

• Android 앱에서 메시지 수신
• 여러 기기에 메시지 전송