Key Concepts

• A Push Notifications is a message that is received by a player's device even when they are not logged in to the game. You've probably see many Push Notifications on your devices every day.
• Firebase Cloud Messaging (FCM) is a part of Google's Firebase platform, and can be used to send Push Notifications. Metaplay uses FCM for its Push Notifications.
• A Device Token (a.k.a. Token, Registration Token, Notification Token, etc.) is a token that identifies a receiving end (i.e. a mobile device) for a push notification. When a game server sends a push notification, it specifies the Token of the destination device. The game server receives a device's Token from the device itself, sent by the game client, which gets it from Firebase.
• A Notification Campaign (or Campaign) is an operation that sends a specific push notification to all (or to a subset of all) players. Notification Campaigns are created from the Metaplay LiveOps Dashboard. A Notification Campaign can be defined to start immediately, or scheduled for a specific date and time.
• A Programmatic Notification is a push notification that is sent to a specific player based on some programmatic condition on the game server. Programmatic Notifications are defined by writing the appropriate code in PlayerActor or other parts of the game server.

Overview

Push Notifications are a great way of reaching out to your player base. Their main advantage over in-game communication is that they will be received by a player's device even if they are not logged in to the game, allowing you to reach both active and inactive players. However, players can and will disable notifications from specific apps if they find them to be too obtrusive or annoying, so you cannot guarantee that message will be seen. Another disadvantage of Push Notifications is that they can only contain text - you can't attach in-game rewards.

The Push Notifications feature is built-in to the Metaplay SDK, but you'll need to do a couple of things to enable it in your game.

TIP

If you want to send rich, in-game notifications to a large group of players, take a look at Managing Broadcasts. Unlike Push Notifications, Broadcasts only target players who are logged in. On the plus side, they do allow you to attach rewards - just like regular in-game mails.

Configuring Push Notifications for Your Game

To use Push Notifications with Metaplay, you'll need to set up a Firebase project for your game and configure the game server and client to use it.

Setting Up a Firebase Project

Please set up a Firebase project and a service account as described in https://firebase.google.com/docs/admin/setup#set-up-project-and-service-account.

You'll likely want to have separate projects for at least development and production.

Configuring the Game Server

After configuring the service account for Firebase, generate a credential JSON file for it in the Firebase console as described in https://firebase.google.com/docs/admin/setup#initialize-sdk.

Next, make this credential JSON file available to the game server by putting it in the Backend/Server/Secrets/ folder. You'll also need to enable Push Notifications and specify the credential file in the appropriate Options.*.yaml file in Backend/Server/Config/ as follows:

PushNotification:
  Enabled:                 true
  FirebaseCredentialsPath: ./Secrets/<credentials json file name>

Replace <credentials json file name> with the name of your credentials file in the Secrets/ folder, for example dev-mygame-firebase-credentials.json.

📦 Storing Secrets Securely

To avoid storing secrets within the code repository, you can put them in AWS Secrets Manager instead. For example, setting FirebaseCredentialsPath to aws-sm://us-east-1#firebase_credentials would denote credentials in Secrets Manager on us-east-1 with name firebase_credentials.

Configuring the Game Client

Please set up the Firebase Unity SDK for your game client as described in https://firebase.google.com/docs/cloud-messaging/unity/client.

Platform Dependency

Installing the plugin will also install the External Dependency Manager for Unity (EDM4U). For more information, see Using the External Dependency Manager for Unity on Android.

After integrating the Firebase Unity SDK, you'll receive a popup indicating that Metaplay has detected Firebase Messaging and has enabled the Metaplay SDK integration.

When the game client receives a Token from the Firebase SDK, it needs to be registered to the game backend. The MetaplayClient in the Metaplay SDK does this automatically when presence of Firebase Messaging is detected.

If your game doesn’t use the SDK-provided MetaplayClient, you can register the Token by adding a handler for the Firebase.Messaging.FirebaseMessaging.TokenReceived event to receive the Token from Firebase, and invoking the PlayerAddFirebaseMessagingToken action to send it to the game backend. You'll need to make sure that the client doesn't attempt to execute the action before the session has been initialized, as the Token might be received from the Firebase SDK at an arbitrary time after registering the TokenReceived handler.

Sending Push Notifications

There are two ways to send notifications to your players: through Notification Campaigns or programmatically from inside your game client.

Notification Campaigns

A Notification Campaign sends a specific push notification message to all players at a specified time. The execution of a Campaign is not instantaneous; depending on the number of players, a Campaign may take a while to complete, and the players won't all receive the notification at the same time.

Notification Campaigns are managed through the LiveOps Dashboard. See Managing Push Notifications for details on how to do this.

Programmatic Notifications

Push Notifications with a given title and body can be sent from PlayerActor by calling the SendPushNotification(string title, string body) method.