The NotificationsManager object provides the API for setting up and controlling Turbulenz Notifications (short text messages) from your game.
Game Notifications can be sent in two ways: instantly to anybody on Turbulenz.com or time-delayed back to the sender. This allows for example sending reminders about game-events.
Game Notifications, just like other Turbulenz Notifications, can appear in the ‘Notifications Panel’ on turbulenz.com (site notifications), and emails sent to the user. Additionally games can register a callback-function to react to game-notifications arriving while the player is playing.
Each registered Turbulenz user has settings to control whether they receive notifications or not. These can be found on the ‘Notification Settings’ panel on turbulenz.com called ‘Game Actions’. Site notifications and email can be separately controlled. A user has to be a ‘follower’ of a game to receive notifications from it.
Required scripts
The NotificationsManager object requires:
/*{{ javascript("jslib/services/turbulenzservices.js") }}*/
/*{{ javascript("jslib/services/notificationsmanager.js") }}*/
/*{{ javascript("jslib/services/sessiontoken.js") }}*/
Some examples of notifications are
The NotificationsManager allows sending short messages to users to keep them informed about game events that occur when they are not currently playing your game. (If the user is currently playing your game then notifications are suppressed, but the game itself can register a callback function with the NotificationsManager to define how it wants to react to a notification)
Testing
To test with multiple users see this guide on multiple logins.
Sending a delayed notification (for 5 minutes from now) to the current user:
var promise = gameNotificationsManager.sendDelayedNotification({
key: 'gameprogress', // a type specified in gamenotifications.yaml
msg: {text: 'Your crop is ready to harvest'}, // a message object
delay: 300, // the delay until the message is sent in seconds
});
Sending an instant notification to a partner:
var promise = gameNotificationsManager.sendInstantNotification({
key: 'turn', // a type specified in gamenotifications.yaml
msg: {text: 'Your turn Peter!'}, // a message object
recipient: 'peter', // the recipient
});
Tic-tac-toe
The SDK contains a tic-tac-toe app which shows how to use instant notifications combined with data share objects from the DataShareManager. Read the instructions for logging in multiple accounts in order to play.
Creating a notification is an asynchronous process. The returned ‘promise’-object is your link to it. It exposes the functions ‘success’ and ‘error’ which allow you to define callback-functions for both eventualities (note that both ‘success’ and ‘error’ return the promise object itself, allowing you to do function-chaining like this):
promise
.success(function (id) {
... // save the notification-id in case you want to cancel the notification later
})
.error(function (e) {
... // analyse e.status or e.error
// the send***Notification functions throw an error if they are called with an invalid params
// object, so this should only ever happen if the server could not be reached for some.
});
You can also cancel a notification directly on the promise-object, instead of having to store the id:
promise.cancel();
Summary
Creates a NotificationManager object. This object provides the interface for all the game notification features.
Syntax
var gameNotificationsManager = TurbulenzServices.createNotificationsManager(requestHandler, gameSession, successCallbackFn, errorCallbackFn);
A JavaScript function. If creation fails due to an api-call failing, a single argument is passed to the function, a JavaScript object with the following properties:
Returns a NotificationsManager object or if the Turbulenz Services are unavailable returns null.
Summary
Sends an instant notification to a user.
Syntax
var params = {
key: key,
msg: message,
recipient: string,
noNotification: bool (optional)
};
var promise = gameNotificationsManager.sendInstantNotification(params);
Summary
Sends a delayed notification to the current user.
Syntax
var params = {
key: key,
msg: message,
delay: integer,
noNotification: bool (optional)
};
var promise = gameNotificationsManager.sendDelayedNotification(params);
Summary
Cancels a single notification, given the notification_id. This allows cancelling of a pending notification.
Syntax
gameNotificationsManager.cancelNotificationByID(notification_id);
Summary
Cancels all of the current users pending notifications that have the specified key.
Syntax
gameNotificationsManager.cancelNotificationsByKey(key);
Summary
Cancels all of the current users pending notifications.
Syntax
gameNotificationsManager.cancelAllNotifications();
Summary
Adds a listener callback function for notifications with the specified key to the current user. This allows the game to react to a notification arriving while the player is playing.
Syntax
function listenFn(notification) {}
gameNotificationsManager.addNotificationListener(key, listenFn);
A JavaScript function. This function receives the notification data as a single object parameter, which has the following properties:
Summary
Removes a listener callback function for notifications with the specified key.
Syntax
gameNotificationsManager.removeNotificationListener(key, listenFn);
Summary
Gets the current user’s notification settings for receiving notifications per email or on Turbulenz.com (1 for enabled, 0 for disabled).
For now, the Local Server and Hub will return dummy-data that corresponds to the default settings for each user on the gamesite:
email_setting: 1
site_setting: 1
However, on the Local Server this data stems from a file called ‘notificationsettings.yaml’ which is automatically created in your localdata/notifications folder.
This allows testing any error-messages, e.g. by corrupting the file. It will automatically get restored after the first error.
Syntax
function successFn(data) {}
gameNotificationsManager.requestUserNotificationSettings(successFn, errorFn);
A JavaScript function. A single argument is passed to the function, a JavaScript object with the following properties:
A JavaScript function. A single argument is passed to the function, a JavaScript object with the following properties:
Summary
Gets the current games’s notification keys.
Syntax
function successFn(data) {}
gameNotificationsManager.requestGameNotificationKeys(successFn, errorFn);
A JavaScript function. A single argument is passed to the function, a JavaScript object with the following properties:
keys A JavaScript object. Contains properties with the key name for each key defined in gamenotifications.yaml
A JavaScript function. A single argument is passed to the function, a JavaScript object with the following properties:
This game file specifies the notifications that the game can use, for example:
- key: moo
title: Moo Notification
- key: baa
title: Baa Notification