App-to-User Notifications

Overview

App-to-User Notifications are short free-form messages you can send to people using your app to reengage them. They are one of the most effective ways to communicate important events, invites from friends or actions people need to take. You use these notifications to send messages to people who have authorized your app.

The notification delivery channels includes Messenger Game Bot, Facebook push/jewel notification or through a user's feed within the gaming tab.

Notification Channel Example

Messenger Bot

Notification Jewel

Gaming Tab Feed

Requirements

To enable App-to-User notifications, your app will require the following.

  1. Enabled and set up for Facebook Login for Gaming
  2. Create and associate a page with your app for messenger bots

Server Side Notifications

Notifications can be initiated from your servers through the Gaming Domain Graph API graph.fb.gg. To send a notification, make a POST to /app_id/gaming_app_to_user_update with an app access_token.

POST graph.fb.gg/{app_id}/gaming_app_to_user_update
ParameterDescription

access_token

The App Access Token associated with your app. For security, this token should only be acquired and used on your game servers. For more information, refer to our developer documentation.

user_id

App scoped User ID. This is acquired on a successful Facebook Login for Gaming.

title

Title of the notification. Minimum of 1 and maximum of 30 characters.

body

Content body of the notification. Minimum of 10 and maximum of 180 characters.

media

URL to statically hosted image(JPG/PNG). WxH of 300x200px with a maximum size of 10MB.

payload

Optional custom payload that can be read when a user enters your app through the notification. JSON format with a maximum length of 1000 characters.

Local Notifications

You can trigger a local notification using our Gaming Services Android SDK.

AppToUserNotificationSender.scheduleAppToUserNotification (
  "Lives Filled!",	// title
  "Your lives are filled! Continue your journey!",	// body
  "https://www.image.url/image.png",	// media Uri, File, Bitmap
  1 * SEC_IN_A_DAY,	// time interval
  payload,	// json encoded payload
  new GraphRequest.Callback() {	// callback
    @Override
    public void onCompleted(GraphResponse response) {
      if (response.getError() != null) {
        // handle error
      }
  	  else {
        // success
      }
    }
  }
)
// throws FileNotFoundException if media asset is missing
ParameterDescription

access_token

The App Access Token associated with your app. For security, this token should only be acquired and used on your game servers. For more information, refer to our developer documentation.

title

Title of the notification. Minimum of 1 and maximum of 30 characters.

body

Content body of the notification. Minimum of 10 and maximum of 180 characters.

media

MediaType. WxH of 300x200px with a maximum size of 10MB.

payload

Optional custom payload that can be read when a user enters your app through the notification. JSON format with a maximum length of 1000 characters.

timeInterval

Interval in seconds from now before the notification is delivered. Maximum interval of 10 days.

callback

Function that is called after the notification is scheduled.

Note: Please read here for best practices regarding notifications on Facebook.

Rate Limiting

The window to send a notification is 10 days from when a user last opened your app. The maximum number of notifications you can send to each user is 5. This limit is reset on app launch.

Best Practices

Since quality is so important, recipients on Facebook can easily turn off notifications they don't like or report them as spam. We use these signals to promote notifications people like and reduce distribution for notifications people don't like. This helps to keep notifications useful for everyone.

People don’t differentiate notifications from the rest of their experience on Facebook, so each message has a lot of power. One unwanted message can make someone start ignoring notifications or turn them off entirely.

To help you create clear and compelling notifications, we’ve put these best practices together.

  1. No inactive people. Your app should not send notifications to people who have not used it in the last 28 days. Data shows that engagement among this group is significantly lower. They are also the most likely to report your notifications as spam. Apps that receive a high degree of spam reports may be disabled.
  2. Start small. Even if you have a large app, start by testing your notifications on a few people. This way you can experiment with your notifications until you learn what works best for people.
  3. Only send one or two notifications to people each day. After two notifications in one day, many people stop responding or mark apps as spam.
  4. Don't fatigue your audience. It is generally not good practice to send too many notifications to the same person within a short period of time.

Unity SDK


InitCloudGame()

public static void ScheduleAppToUserNotification (string title, string body, Uri media, int timestamp, string payload, FacebookDelegate<IScheduleAppToUserNotificationResult> callback);

The parameter timeInterval has incorrectly been called timestamp in this version. Please use as a time interval.

Callback

The callback takes IScheduleAppToUserNotificationResult result as a parameter.

If successful,

result.Error == null

Example

// (c) Facebook, Inc. and its affiliates. Confidential and proprietary.
using Facebook.Unity;
...

public class Notifications : MonoBehaviour
{
    private void ScheduleNotification()
    {
        string title = "Lives Filled!";
        string body = "Your lives are filled! Continue your journey!";
        Uri media = new Uri(https://www.image.url/image.png);
        int timeInterval = 1 * SEC_IN_A_DAY;
        string payload = "{'payload_key': 'payload_value'}";
        FBGamingServices.ScheduleAppToUserNotification(title, body, media, timeInterval, payload, delegate (IScheduleAppToUserNotificationResult notificationResult)
        {
            if (notificationResult == null && notificationResult.ResultDictionary != null)
            {
                // Successfully scheduled an app-to user-notification
            }
            else
            {
                // Unsuccessfully scheduled an app-to-user notification
            }
        });
    }
}