Facebook Instant Games: Push Notifications

FBInstantNotifications is a library and backend service provided by 2DKit for implementing push notifications (bots) for Facebook Instant Games. Developers can implement time delayed push notifications using client-side JS only, with no need to manage a server, database, or Facebook Messenger APIs.

Example

// Schedule a push notification to be sent after one hour
FBInstantNotifications.scheduleAfterDelay("harvest", 60, {
    text: "Hey {{name}}, your farm crops are ready to harvest!"
});

Installation

Either include our CDN-hosted library in your index.html:

<script src="https://d2r5kp6rl4cz9b.cloudfront.net/FBInstantNotifications.js"></script>

Or with NPM using npm install fbinstant-notifications and importing:

var FBInstantNotifications = require("fbinstant-notifications");

Bot Setup

Run through these steps to create a page for your bot, subscribe the webhook, and connect it to your Instant Game.

1. Add the Messenger product to your Facebook app:

2. Under the Access Token section, click to create a new page:

3. The name of the page must contain the name of the app, and must be in the App Page category:

4. Get the access token by selecting the new page from the dropdown. You may have to refresh your browser for it to appear. If you receive the following error, click Edit Permissions and allow your app messaging permissions:

5. Once you have the access token, copy it to the clipboard:

6. In the Webhooks section, create a new subscription:
   • For the Callback URL, enter https://notifications.2dkit.com/webhook?page_access_token=YOUR_PAGE_ACCESS_TOKEN (replace your token from the previous step). When troubleshooting, you can visit your webhook URL in your browser to receive more error information.
   • For the Verify Token, enter "2DKit".
   • For the Subscription Fields, check "messages" and "messaging_game_plays" only.

7. Subscribe the webhook to the page. You may have to refresh your browser for it to appear:

8. In the Instant Games product, in the App Page section, set the app page to the new page:

All set! Now you can use the JS library to schedule push notifications.

Support

Contact us at [email protected] with questions, feature requests, and bug reports.

For more information about 2DKit and our other Instant Games products, visit http://2dkit.com.

API Documentation

FBInstantNotifications.scheduleAfterDelay(type, delayInMinutes, notification)

Schedules a push notification to be sent on a time delay.

Parameters:

• type: string, the developer-defined type of this notification.
• delayInMinutes: number, how many minutes into the future should the notification be sent.
• notification: object, which may have the following properties:
  • text: string, Required! The main text of the notification. Instances of "{{name}}" are replaced with the player's first name.
  • subtitleText: string, the subtitle text of the notification. Instances of "{{name}}" are replaced with the player's first name.
  • buttonText: string, the call-to-action text on the notification game play button.
  • image: string, the notification image URL.
  • imageAspectRatio: string, the aspect ratio of the image. Either "horizontal" (1.91:1) or square (1:1). Defaults to "horizontal".
  • entryPointData: object, the object sent to the game when launched via the notification's play button. Can be retrieved by using FBInstant.getEntryPointData().
  • contextId: string, the context ID the game will enter when launched via the notification's play button.
  • overwrite: boolean, whether this notification should cancel and overwrite any previously scheduled notification with the same type. Defaults to true.

FBInstantNotifications.scheduleAtDate(type, date, notification)

Like FBInstantNotifications.scheduleAfterDelay(), but at an exact date.

Parameters:

• date: Date, the time when the notification should be sent.

FBInstantNotifications.cancel(type)

Cancels a notification that was scheduled at any previous point.

Parameters:

• type: string, the type of notification that should be canceled.

FBInstantNotifications.subscribeBot()

A convenience method to call FBInstant.subscribeBotAsync(), if not already subscribed. This method is automatically called when the schedule methods are called.