App Center Push

App Center Push enables you to send push notifications to users of your app from the App Center portal. App Center portal and the Push SDK is integrated with Firebase Cloud Messaging.

Only devices with the Google Play Store application or emulators using Google APIs images can receive notifications.

Note

A notification appears in the system notification center only if the application is in the background at the moment the Push is received.

Prerequisites

1. Set up Firebase Cloud Messaging

  1. Create a project on the Firebase Console.
  2. Click the Android logo on the page to create an application matching your package name.
  3. Go to Project Settings and download the google-services.json file.
  4. Copy this file to your Android project app module.

2. Obtain your Android API Key

  1. In the Firebase Console, go to Project Settings.
  2. Navigate to the Cloud Messaging tab.
  3. Copy the Server Key. This will be the Android API Key that you will need to set in the App Center Push portal.

Add App Center Push to your app

If you haven't set up the SDK in your application yet, see the instructions in the Unity Get started section of the docs.

Enable App Center Push

Note

To use the APIs presented below, you must add the following using statement to your .cs file:

using Microsoft.AppCenter.Unity.Push;

You also have to make sure that Use Push is checked in the settings of your App Center game object.

Intercept push notifications

You can set up a listener to be notified whenever a push notification is received in foreground, or a background push notification has been clicked by the user.

Note

A notification is not generated when your application receives a push in the foreground.

Note

If the push is received in background, the event is NOT triggered at receive time. The event is triggered when you click on the notification.

Note

The background notification click callback does NOT expose title and message. Title and message are only available in foreground pushes.

To register the listener, see the following example:

Push.PushNotificationReceived += (sender, e) =>
{
    string customData = "";
    if (e.CustomData != null)
        foreach (var data in e.CustomData)
            customData += data.Key + " = " + data.Value + Environment.NewLine;

    // Message and title cannot be read from a background notification object.
    // Message being a mandatory field, you can use that to check foreground vs background.
    if (string.IsNullOrEmpty(e.Message))
    {
        // Use the custom data dictionary when a background push is clicked.
        Debug.Log("Background push notification received:" + Environment.NewLine +
                  "Custom data: " + customData);
    }
    else
    {
        // Display an alert for foreground push.
        Debug.Log("Foreground push notification received:" + Environment.NewLine +
                  "Notification title: " + e.Title + Environment.NewLine +
                  "Message: " + e.Message + Environment.NewLine +
                  "Custom data: " + customData);
    }
};

Custom data in your notifications

You can send optional custom data as part of the push payload. The data will be sent in the key-value format. This custom data can be intercepted in the app through Push SDK callback.

There are few reserved keywords that can be set via custom data. You can customize your notifications by setting custom color, icon or sound.

Note

Android 5.0 and later uses a silhouette (only alpha channel) of your icon for notifications. See Android 5.0 Behavior Changes for details.

Reserved keywords in Android platform

  • color: The notification's icon color, expressed in #rrggbb format. Will be applied only on devices with Android 5.0 and later.
  • icon: The notification's icon. You should specify name of the icon resource. Supports drawable and mipmap types. If this value isn't specified application icon will be used.
  • sound: Add this key when you want the to play a sound when the device receives the notification. Supports default or the filename of a sound resource bundled in the app. Sound files must reside in /res/raw/. This is effective only for devices running or targeting an Android version lower than 8. Sound is set by default on Android 8 and user can change notification settings for the group of notifications coming from AppCenter.

Configure notification's default values

You can specify custom defaults for the icon and color that are applied if not already set in the push payload.

Export your Unity project and add the following lines to application tag inside the project's AndroidManifest.xml file:

<!-- Set default notification icon and color. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_notification" />
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/notification" />

App Center displays the application icon if a custom default icon and an icon aren't set in the push payload.

Existing Firebase Analytics users

App Center Push SDK automatically disables Firebase Analytics. If you're a Firebase customer and want to keep reporting analytics data to Firebase, you must check the Enable Firebase Analytics checkbox in the settings of your App Center game object.

Enable or disable App Center Push at runtime

You can enable and disable App Center Push at runtime. If you disable it, the SDK stops updating the Google registration identifier used to push, but the existing one will continue working. Disabling App Center Push in the SDK will NOT stop your application from receiving push notifications.

Push.SetEnabledAsync(false);

To enable App Center Push again, use the same API but pass true as a parameter.

Push.SetEnabledAsync(true);

The state is persisted in the device's storage across application launches.

This API is asynchronous, you can read more about in our App Center Asynchronous APIs guide.

Check if App Center Push is enabled

You can also check if App Center Push is enabled or not.

bool isEnabled = await Push.IsEnabledAsync();

This API is asynchronous, you can read more about in our App Center Asynchronous APIs guide.