Set up a Firebase Cloud Messaging Client App with Unity

To write your cross-platform Firebase Cloud Messaging client app with Unity, use the Firebase Cloud Messaging API. The Unity SDK works for both Android and iOS, with some additional setup required for each platform.

Before you begin

Before you can use the Firebase Cloud Messaging, you will need to create a Firebase project, and add the Firebase Unity SDK packages to your Unity project.

Setup:

Prerequisites

Android

iOS

  • Unity 5.0 or later
  • Xcode 8.0 or later
  • A physical iOS device
  • APNs certificate with Push Notifications enabled

If you don't have a Unity project already, you can download one of our quickstart samples and experiment with a specific Firebase feature. If you're using a quickstart, remember to get the bundle identifier from the project settings; you need it for the next step.

Set up your app in the Firebase console

To add Firebase to your app, you need a Firebase project and a Firebase configuration file for your app.

Create a Firebase project in the Firebase console if you don't already have one. If you already have an existing Google project associated with your mobile app, click Import Google Project. Otherwise, click Create New Project.

Android

  1. Click Add Firebase to your Android app and follow the setup steps. If you're importing an existing Google project, this may happen automatically and you can just download the config file.
  2. When prompted, enter your app's package name. It's important to enter the package name your app is using; this can only be set when you add an app to your Firebase project.
  3. Download a google-services.json file when instructed. You can redownload this file again at any time.
  4. Copy this file to anywhere inside your project's assets folder.

IOs

  1. Click Add Firebase to your iOS app and follow the setup steps. If you're importing an existing Google project, this may happen automatically and you can just download the config file.
  2. When prompted, enter your app's bundle ID. It's important to enter the bundle ID your app is using; this can only be set when you add an app to your Firebase project.
  3. Download a GoogleService-Info.plist file when instructed. You can redownload this file again at any time.
  4. Add the GoogleService-Info.plist file to the project.

  5. Drag the GoogleService-Info.plist downloaded from the Firebase console into any folder in the Unity project.

Add the Firebase Unity SDK to your app

  1. Download the Firebase Unity SDK.
  2. Select the Assets > Import Package > Custom Package menu item.
  3. Import the FirebaseMessaging.unitypackage package from the Firebase Unity SDK, downloaded previously.
  4. When the Import Unity Package window appears, click the Import button.

Build your app

Android

  1. Select the File > Build Settings menu option.
  2. Select Android in the Platform list.
  3. Click Switch Platform to select Android as the target platform.
  4. Wait for the spinner (compiling) icon in the bottom right corner of the Unity status bar to stop.
  5. Click Build and Run.

iOS

  1. Select the File > Build Settings menu option.
  2. Select iOS in the Platform list.
  3. Click Switch Platform to select iOS as the target platform.
  4. Wait for the spinner (compiling) icon in the bottom right corner of the Unity status bar to stop.
  5. Click Build and Run.

  6. After Xcode opens, add the UserNotifications.framework.

    1. Click on the project in Xcode and select the General tab from the Editor area.
    2. Scroll down to Linked Frameworks and Libraries and click the + button to add a framework.
    3. In the window that appears, scroll to UserNotifications.framework and click on that entry, then click on Add.

Initialize Firebase Cloud Messaging

The Firebase Cloud Message library will be initialized when adding handlers for either the TokenReceived or MessageReceived events.

Upon initialization, a registration token is requested for the client app instance. The app will receive the token with the OnTokenReceived event, which should be cached for later use. You'll need this token if you want to target this specific device for messages.

In addition, you will need to register for the OnMessageReceived event if you want to be able to receive incoming messages.

The entire setup looks like this:

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

Next steps

After setting up the client app, you are ready to send downstream and topic messages with Firebase. To learn more, see the quickstart sample which demonstrates this functionality.

To add other, more advanced behavior to your app, see the guides for sending messages from an app server:

Keep in mind that you'll need a server implementation to make use of these features.

Note for Android

Apps that do not use the default UnityPlayerActivity or that supply their own Assets/Plugins/AndroidManifest.xml may need extra configuration.

The Firebase Cloud Messaging Unity Plugin on Android comes bundled with two additional files:

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar contains an activity called MessagingUnityPlayerActivity that replaces the standard UnityPlayerActivity.
  • Assets/Plugins/Android/AndroidManifest.xml instructs the app to use MessagingUnityPlayerActivity as the entry point to the app.

These files are provided because the default UnityPlayerActivity does not handle onStop, onRestart activity lifecycle transitions or implement the onNewIntent which is necessary for Firebase Cloud Messaging to correctly handle incoming messages.

If your app does not use the default UnityPlayerActivity you will need to remove the supplied AndroidManifest.xml and ensure that your custom activity properly handles all transitions of the Android Activity Lifecycle. If your custom activity extends UnityPlayerActivity you can instead extend com.google.firebase.MessagingUnityPlayerActivity which implements all necessary methods.

Here is an example implementation of the unhandled methods:

/**
 * 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
 * receieved 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);
  startService(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);
}

Send feedback about...

Need help? Visit our support page.