Unity로 Firebase 클라우드 메시징 클라이언트 앱 설정

Unity로 교차 플랫폼 Firebase Cloud Messaging 클라이언트 앱을 개발하려면 Firebase Cloud Messaging API를 사용합니다. Unity SDK는 Android 및 Apple과 연동이 가능하며 각 플랫폼에 대해 몇 가지 설정이 추가로 필요합니다.

시작하기 전에

기본 요건

  • Unity 2021 LTS 이상을 설치합니다. Unity 2020 지원은 지원 중단된 것으로 간주하며 다음 주요 출시 후에 더 이상 적극적으로 지원되지 않습니다. 이전 버전도 호환될 수 있지만 적극적으로 지원되지는 않습니다.

  • (Apple 플랫폼만 해당) 다음을 설치합니다.

    • Xcode 13.3.1 이상
    • CocoaPods 1.12.0 이상

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

    • iOS — iOS 13 이상 타겟팅
    • tvOS - tvOS 13 이상 타겟팅
    • Android — API 수준 21(Lollipop) 이상 타겟팅

  • 기기를 설정하거나 에뮬레이터를 사용하여 Unity 프로젝트를 실행합니다.

    • iOS 또는 tvOS — 실제 기기를 설정하여 앱을 실행하고 다음 작업을 완료합니다.

      • Apple 개발자 계정의 Apple 푸시 알림 인증 키를 가져옵니다.
      • XCode의 App(앱) > Capabilities(기능)에서 푸시 알림을 사용 설정합니다.

    • Android — 에뮬레이터에서 Google Play가 포함된 에뮬레이터 이미지를 사용해야 합니다.

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

1단계: Firebase 프로젝트 만들기

Unity 프로젝트에 Firebase를 추가하려면 우선 Unity 프로젝트에 연결할 Firebase 프로젝트를 만들어야 합니다. Firebase 프로젝트에 대한 자세한 내용은 Firebase 프로젝트 이해를 참조하세요.

2단계: Firebase에 앱 등록

Firebase 프로젝트에 연결할 앱 또는 게임을 1개 이상 등록할 수 있습니다.

  1. Firebase 콘솔로 이동

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

    Firebase 프로젝트에 앱을 이미 추가한 경우 앱 추가를 클릭하여 플랫폼 옵션을 표시합니다.

  3. 등록하려는 Unity 프로젝트의 빌드 타겟을 선택하거나 이제 동시에 두 타겟을 등록하도록 선택할 수도 있습니다.

  4. Unity 프로젝트의 플랫폼별 ID를 입력합니다.

    • iOS의 경우 — iOS 번들 ID 필드에 Unity 프로젝트의 iOS ID를 입력합니다.

    • Android의 경우 — Android 패키지 이름 필드에 Unity 프로젝트의 Android ID를 입력합니다.
      패키지 이름과 애플리케이션 ID는 같은 개념입니다.

  5. (선택사항) Unity 프로젝트의 플랫폼별 닉네임을 입력합니다.
    이러한 닉네임은 편의상 지정하는 내부용 식별자로 Firebase 콘솔에서 본인만 볼 수 있습니다.

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

3단계: Firebase 구성 파일 추가

  1. Firebase 콘솔 설정 워크플로에서 플랫폼별 Firebase 구성 파일을 가져옵니다.

    • iOS의 경우 — GoogleService-Info.plist 다운로드를 클릭합니다.

    • Android의 경우 — google-services.json 다운로드를 클릭합니다.

  2. Unity 프로젝트의 프로젝트 창을 연 다음 구성 파일을 Assets 폴더로 이동합니다.

  3. Firebase 콘솔로 돌아가서 설정 워크플로에서 다음을 클릭합니다.

4단계: Firebase Unity SDK 추가

  1. Firebase 콘솔에서 Firebase Unity SDK 다운로드를 클릭한 후 원하는 위치에 SDK의 압축을 풉니다.

    • 언제든 Firebase Unity SDK를 다시 다운로드할 수 있습니다.

    • Firebase Unity SDK는 플랫폼별로 제공되지 않습니다.

  2. Unity 프로젝트를 열고 Assets(애셋) > Import Package(패키지 가져오기) > Custom Package(커스텀 패키지)로 이동합니다.

  3. 압축을 푼 SDK에서 앱에 사용할 지원되는 Firebase 제품을 선택합니다.

    Firebase Cloud Messaging 사용 환경을 최적화하려면 프로젝트에서 Google Analytics를 사용 설정하는 것이 좋습니다. 또한 Analytics를 설정하는 과정에서 앱에 Analytics용 Firebase 패키지를 추가해야 합니다.

    Analytics 사용 설정됨

    • Google Analytics용 Firebase 패키지를 추가합니다. FirebaseAnalytics.unitypackage
    • Firebase Cloud Messaging용 패키지를 추가합니다. FirebaseMessaging.unitypackage

    Analytics 사용 설정되지 않음

    Firebase Cloud Messaging용 패키지를 추가합니다. FirebaseMessaging.unitypackage

  4. Unity 패키지 가져오기 창에서 가져오기를 클릭합니다.

  5. Firebase 콘솔로 돌아가서 설정 워크플로에서 다음을 클릭합니다.

5단계: Google Play 서비스 버전 요구사항 확인

Android용 Firebase Unity SDK를 사용하려면 먼저 최신 상태의 Google Play services가 필요합니다.

애플리케이션 시작 시 다음 using 문과 초기화 코드를 추가합니다. Firebase Unity SDK에서 다른 메서드를 호출하기 전에 Google Play services를 확인하고 필요에 따라 SDK에 필요한 버전으로 업데이트할 수 있습니다.

using Firebase.Extensions;

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWithOnMainThread(task => {
  var dependencyStatus = task.Result;
  if (dependencyStatus == Firebase.DependencyStatus.Available) {
    // Create and hold a reference to your FirebaseApp,
    // where app is a Firebase.FirebaseApp property of your application class.
       app = Firebase.FirebaseApp.DefaultInstance;

    // Set a flag here to indicate whether Firebase is ready to use by your app.
  } else {
    UnityEngine.Debug.LogError(System.String.Format(
      "Could not resolve all Firebase dependencies: {0}", dependencyStatus));
    // Firebase Unity SDK is not safe to use here.
  }
});

Firebase를 사용하기 위한 Unity 프로젝트 등록 및 구성 작업을 마쳤습니다.

Apple 지원을 위해 APNs 인증 키 업로드

Firebase에 APNs 인증 키를 업로드합니다. 아직 APNs 인증 키가 없다면 Apple Developer Member Center에서 만드세요.

  1. Firebase Console 프로젝트 내에서 톱니바퀴 아이콘을 선택하고 프로젝트 설정을 선택한 다음 클라우드 메시징 탭을 선택합니다.

  2. iOS 앱 구성의 APNs 인증 키에서 업로드 버튼을 클릭합니다.

  3. 키를 저장한 위치로 이동하여 키를 선택하고 열기를 클릭합니다. 해당하는 키 ID(Apple Developer Member Center에서 확인 가능)를 추가하고 업로드를 클릭합니다.

Apple 플랫폼에서 푸시 알림 사용 설정

1단계: 사용자 알림 프레임워크 추가

  1. Xcode 프로젝트를 클릭한 후 Editor area(편집 영역)에서 General(일반) 탭을 클릭합니다.

  2. Linked Frameworks and Libraries(연결된 프레임워크 및 라이브러리)까지 아래로 스크롤한 다음 + 버튼을 클릭하여 프레임워크를 추가합니다.

  3. 나타나는 창에서 UserNotifications.framework까지 스크롤하여 해당 항목을 클릭한 다음 Add(추가)를 클릭합니다.

2단계: 푸시 알림 사용 설정

  1. Xcode 프로젝트를 클릭한 후 Editor area(편집 영역)에서 Capabilities(기능) 탭을 클릭합니다.

  2. Push Notifications(푸시 알림)를 On(켜기)으로 전환합니다.

  3. Background Modes(백그라운드 모드)까지 아래로 스크롤하고 On(켜기)으로 전환합니다.

  4. Background Modes(백그라운드 모드)아래의 Remote notifications(원격 알림) 체크박스를 선택합니다.

Firebase Cloud Messaging 초기화

TokenReceived 또는 MessageReceived 이벤트에 대한 핸들러를 추가하면 Firebase 클라우드 메시징 라이브러리가 초기화됩니다.

초기화 시 클라이언트 앱 인스턴스에 대한 등록 토큰이 요청됩니다. 앱은 OnTokenReceived 이벤트로 토큰을 수신하며, 이 토큰을 이후에 사용하도록 캐시해야 합니다. 메시지를 해당 기기로 타겟팅하려면 이 토큰이 필요합니다.

더불어, OnMessageReceived 이벤트에도 등록해야 메시지를 수신할 수 있습니다.

전체 설정은 다음과 같습니다.

public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
}

public void OnTokenReceived(object sender, Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

public void OnMessageReceived(object sender, Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

Android 진입점 활동 구성

Android에서 Firebase Cloud Messaging은 기본 UnityPlayerActivity를 대체하는 커스텀 진입점 활동과 함께 제공됩니다. 커스텀 진입점을 사용하지 않는 경우에는 자동으로 대체 작업이 진행되며 별도로 조치를 취할 필요가 없습니다. 기본 진입점 활동을 사용하지 않거나 자체 Assets/Plugins/AndroidManifest.xml을 제공하는 앱은 추가 구성이 필요합니다.

Android용 Firebase Cloud Messaging Unity 플러그인에는 2가지 파일이 추가로 포함되어 있습니다.

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar에는 표준 UnityPlayerActivity를 대체하는 MessagingUnityPlayerActivity라는 활동이 포함되어 있습니다.
  • Assets/Plugins/Android/AndroidManifest.xml은 MessagingUnityPlayerActivity를 앱의 진입점으로 사용하도록 앱에 지시합니다.

이러한 파일이 제공되는 이유는 기본 UnityPlayerActivity는 onStop, onRestart 활동 수명 주기 전환을 처리하지 않으며 Firebase Cloud Messaging에서 수신 메시지를 올바르게 처리하는 데 필요한 onNewIntent를 구현하지 않기 때문입니다.

커스텀 진입점 활동 구성

앱에서 기본 UnityPlayerActivity를 사용하지 않는 경우 제공된 AndroidManifest.xml을 삭제하고 커스텀 활동에서 Android 활동 수명 주기의 모든 전환을 적절히 처리해야 합니다. 처리 방법의 예시는 아래에 나와 있습니다. 커스텀 활동에서 UnityPlayerActivity를 확장하는 경우 필요한 메서드를 모두 구현하는 com.google.firebase.MessagingUnityPlayerActivity를 대신 확장할 수 있습니다.

커스텀 활동을 사용하고 있고 com.google.firebase.MessagingUnityPlayerActivity를 확장하지 않은 경우에는 활동에 다음 스니펫을 포함해야 합니다.

/**
 * Workaround for when a message is sent containing both a Data and Notification payload.
 *
 * When the app is in the background, if a message with both a data and notification payload is
 * received the data payload is stored on the Intent passed to onNewIntent. By default, that
 * intent does not get set as the Intent that started the app, so when the app comes back online
 * it doesn't see a new FCM message to respond to. As a workaround, we override onNewIntent so
 * that it sends the intent to the MessageForwardingService which forwards the message to the
 * FirebaseMessagingService which in turn sends the message to the application.
 */
@Override
protected void onNewIntent(Intent intent) {
  Intent message = new Intent(this, MessageForwardingService.class);
  message.setAction(MessageForwardingService.ACTION_REMOTE_INTENT);
  message.putExtras(intent);
  message.setData(intent.getData());
  // For older versions of Firebase C++ SDK (< 7.1.0), use `startService`.
  // startService(message);
  MessageForwardingService.enqueueWork(this, message);
}

/**
 * Dispose of the mUnityPlayer when restarting the app.
 *
 * This ensures that when the app starts up again it does not start with stale data.
 */
@Override
protected void onCreate(Bundle savedInstanceState) {
  if (mUnityPlayer != null) {
    mUnityPlayer.quit();
    mUnityPlayer = null;
  }
  super.onCreate(savedInstanceState);
}

Firebase C++ SDK의 새 버전(7.1.0 이상)은 JobIntentService를 사용하므로 AndroidManifest.xml 파일에서 추가 수정이 필요합니다.

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" >
</service>

Android 메시지 전송 참고사항

앱이 전혀 실행되지 않을 때 사용자가 알림을 탭하면 기본적으로 메시지가 FCM의 기본 제공 콜백을 통해 라우팅되지 않습니다. 이러한 경우에는 메시지 페이로드가 애플리케이션을 시작하는 데 사용되는 Intent를 통해 수신됩니다.

앱이 백그라운드 상태일 때 수신된 메시지에는 작업 표시줄 알림을 채우는 데 사용되는 알림 필드의 콘텐츠가 포함되지만 이 알림 콘텐츠는 FCM에 전달되지 않습니다. 즉 FirebaseMessage.Notification은 null입니다.

요약하면 다음과 같습니다.

앱 상태 알림 데이터 둘 다
포그라운드 Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
배경 작업 표시줄 Firebase.Messaging.FirebaseMessaging.MessageReceived 알림: 작업 표시줄
데이터: 인텐트 부가 정보

자동 초기화 방지

FCM은 기기 타겟팅을 위한 등록 토큰을 생성합니다. 토큰이 생성되면 라이브러리는 식별자와 구성 데이터를 Firebase에 업로드합니다. 토큰을 사용하기 전에 명시적으로 수신 동의하려면 Android나 애널리틱스에서 FCM을 사용 중지하여 구성 시 생성을 방지할 수 있습니다. 이를 위해 Apple에서는 GoogleService-Info.plist가 아닌 Info.plist에, Android에서는 AndroidManifest.xml에 메타데이터 값을 추가합니다.

Android

<?xml version="1.0" encoding="utf-8"?>
<application>
  <meta-data android:name="firebase_messaging_auto_init_enabled"
             android:value="false" />
  <meta-data android:name="firebase_analytics_collection_enabled"
             android:value="false" />
</application>

Swift

FirebaseMessagingAutoInitEnabled = NO

FCM을 다시 사용 설정하려면 런타임 호출을 만들면 됩니다.

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

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

FCM을 사용하면 앱에 딥 링크가 포함된 메시지를 보낼 수 있습니다. 딥 링크가 포함된 메시지를 수신하려면 앱의 딥 링크를 처리하는 활동에 새 인텐트 필터를 추가해야 합니다. 인텐트 필터가 도메인의 딥 링크를 인식합니다. 메시지에 딥 링크가 포함되어 있지 않다면 이 구성이 필요하지 않습니다. AndroidManifest.xml에 다음을 추가합니다.

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="http"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="https"/>
</intent-filter>

인텐트 필터를 보다 유연하게 만들기 위해 와일드 카드를 지정할 수도 있습니다. 예를 들면 다음과 같습니다.

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="*.example.com" android:scheme="http"/>
  <data android:host="*.example.com" android:scheme="https"/>
</intent-filter>

지정한 스키마 및 호스트로 연결되는 링크가 포함된 알림을 사용자가 탭하면 앱에서 이 인텐트 필터로 링크를 처리하는 활동을 시작합니다.

다음 단계

클라이언트 앱이 설정되면 Firebase로 다운스트림 메시지와 주제 메시지를 보낼 수 있습니다. 자세한 내용은 이 기능을 시연하는 빠른 시작 샘플을 참조하세요.

앱에 다른 고급 동작을 추가하려면 앱 서버에서 메시지를 전송하는 방법 가이드를 참조하세요.

이러한 기능을 사용하려면 서버 구현이 필요하다는 점에 유의하세요.