App Notifications

App 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 app notifications to send these messages to people who have authorized your app.

This document will introduce you to notifications and how to use the API. Specifically it covers:

• User experience
• Quality controls
• Best practices
• Tracking and testing performance of notifications
• Implementation details

User experience

Apps can send notifications to people who have authorized the app. No special or extended permission is required.

When a notification is delivered, it lights the notifications jewel on Facebook and appears in the drop down. Notifications appear with the app icon to the left, interspersed with other notifications based on chronological sorting.

Notifications themselves are short — up to 180 characters — strings of custom text. You can also reference the UIDs of any other people authorized on your application. UIDs will be expanded to show people's actual names, but they won't be clickable.

When people click the notification, they'll be taken to a URL you specify with the notification.

Quality controls

Notifications work well because people pay attention to them. Since this API gives you a lot of freedom to design notifications as you wish, Facebook has built in several quality controls to maintain quality while many different apps use the service.

Opt out

Although you do not need any special permission to send notifications, people have the ability to opt-out at any time. When someone receives a notification or person-to-person request from an app for the first time, they see a first-receipt prompt along with the notification, like this:

When they position the cursor over the X to the right, they have the option of turning off notifications from your app, like this:

Once people click the X they have to complete addition steps before the can turn off notifications from the app completely, as shown here:

In addition to turning off notifications, people can also report spam. Apps that receive too many complaints may be disabled.

Minimum click-to-impression ratio for high-volume apps

The click-to-impression (CTI) ratio is one of the most important measure of the effectiveness of your notifications. Notifications that have a high CTI are interesting and engaging to people. Notifications with a low CTI tend to be viewed as 'spammy'. Over time, people will tend to ignore or disable low CTI notifications, hurting performance of your app's performance and others', too.

To ensure the notifications channel remains interesting to people on Facebook, apps that send more than 50,000 notifications in a week are required to maintain at least a 17% weekly click-to-impression (CTI) ratio. Data shows that people engage for longer when apps maintain this ratio or higher. Apps that do not maintain this rate on a weekly basis may be temporarily disabled.

Most applications can maintain this rate quite easily if they follow the simple best practices. described below.

Typically your app is at greatest risk of falling below this threshold when you want to test new notifications. We have provided several options to help you avoid trouble while testing new ideas. See How to Test New Notifications below for complete information about this.

See How the click-to-impression ratio is calculated section below to see how we calculate this number.

Best practices

Since quality is so important, Facebook lets people 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 us 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 spammy 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 so you stay below the 50,000-per-week threshold. This way you can experiment with your notifications until you learn what works best for people.

3. Monitor your rate. You can find your current click-per-impression rate by checking out the notifications page in Insights.

4. 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.

5. Follow best practices. Our Notification Design Guidelines describes best practices gleaned from the most successful apps on Facebook.

Tracking and testing performance Of notifications

You can find out how your notifications are performing under Traffic in Insights, shown just below. By default this shows data for both User Notifications (which are generated by Requests) and App Notifications. Select App Notifications from the Traffic menu.

This section contains data such as click to impression ratio, the number of accepted and rejected notifications and mark as spam rate. We highly encourage you to use this data while refining your techniques for sending notifications.

You can access your app's insights in the Insights Dashboard.

To get more detailed measurement of notifications, you can separate your notifications into groups for Insights to track them separately. Just pass a ref parameter with a custom key name when posting your notification. All notifications with the same ref will be grouped together in Insights, and can be selected via the Story Types menu.

How to test new notifications

Because the Notifications API gives you freedom to communicate with people using your app, you are also responsible to maintain the quality of these notifications. Typically this is most challenging when you want to try a new notification and don't know how it will perform.

Whenever you introduce a new notification, follow these steps to assure quality:

1. If you haven't sent notifications yet. Start with a low volume and only roll out to everyone using your app when you're happy with the result. Low-volume notifications have looser quality controls. When you first start testing notifications, send them to a small enough set of people to remain below 50,000 sends-per-week. Only ramp up if CTI for the new notification exceeds 17% and spam rates aren't high.

2. If you send notifications already. If you're already sending a high volume of notifications, test new notifications to a small percent of people using your app. Usually 1-5% is sufficient to measure effectiveness. Use the ref parameter to measure the performance of these notifications separate from the rest of your integration. By testing with a small base, you can keep your overall performance high without worrying about your new type.

How the click-to-impression ratio is calculated

The click-to-impression ratio is a measure of how engaging people find your notifications. If you follow our design guidelines, CTI should remain high, which you can check in Insights. If you need to understand your CTI ratio in detail, this sections describes how we calculate it.

For quality control purposes, we calculate it on a weekly basis. CTI is calculated in the following way:

CTI = total clicks over the last seven days /  
  total impressions over the last seven days

An impression is counted the first time someone sees a new notification from your app. A single notification never counts for more than one impression per person. We look at all notifications over all uses of your application to calculate the total CTI.

Implementation details

Here are technical details of adding notifications capability to your apps.

Using the API

Apps can generate notifications by issuing a HTTP POST request to the /user_id/notifications Graph API, with a app access_token.

 POST /{recipient_userid}/notifications?access_token= … &template= … &href= …

Parameters

href	The relative path/GET params of the target (for example, "index.html?gift_id=123", or "?gift_id=123"). Then we will construct proper target URL based on your app settings. The logic is that, on web, if Canvas setting exists, we always show “Canvas URL + href”. If not, we show nothing. In the future (not in this version), we will also use existing URL re-writing logic to support mobile canvas and native mobile apps. We also append some special tracking params (fb_source, notif_id, notif_t) to the target URL for developers to track at their side. One example of target URL displayed in the jewel is: https://apps.facebook.com/bzhang_og/?fb_source=notification&notif_id=notif_514699839_145756436&ref=notif&notif_t=app_notification
template	The customized text of the notification. See the templating section below for more details.
ref	Separate your notifications into groups so they can be tracked independently in Insights. See the measuring performance section of the Notifications concept document for more information.

Return values:

If notification is successful, returns true:

{
  "success": true
}

If failed, throws an error with corresponding exception message.

If the user you're trying to send to has not authenticated your app, you will get an error 200:

{
   "error": {
      "message": "(#200) Cannot send notifications to a user who has not installed the app",
      "type": "OAuthException",
      "code": 200
   } }

If a person you're trying to tag has not authenticated your app, you will get an error 200:

{
   "error": {
      "message": "(#200) Cannot tag users who have not installed the app",
      "type": "OAuthException",
      "code": 200
   } }

If your template text contains more than 180 characters, we throw an error 100:

{
   "error": {
      "message": "(#100) template parameter cannot be longer than 180 characters.",
      "type": "OAuthException",
      "code": 100
   }
}

Note that if people turn off notifications from your app, posting will still succeed but the notification just will not appear in the UI.

Templating

Notification messages are free form text. We enforce a maximum number of 180 characters in this field. Otherwise, an exception is thrown.

Format 1: Plain text

This notification can be generated with the following graph API call:

POST /{recipient_userid}/notifications?
     access_token= … & 
     href= … & 
     template=You have people waiting to play with you, play now!

Format 2: Lightweight template to refer to user_ids

You use @[USER_ID] to embrace user_ids. Then our system will replace it with the person's full name and highlight it at rendering time.

The notification above can be generated by formatting the template with the user IDs as shown in the code below.

POST /{recipient_userid}/notifications?
     access_token= … & 
     href= … & 
     template=@[596824621] started a game with you, play now!

Similarly, the notification above also uses the @[USER_ID] syntax but has more than one actor (person) in the template.

POST /{recipient_userid}/notifications?
     access_token= … & 
     href= … & 
     template=@[596824621] and @[555279551] started a game with you!

We will verify each user_id to make sure it is valid Facebook user and has already authenticated your app. Otherwise, we will throw an exception.