The TurbulenzServices object provides a set of functions for creating objects that require communication with Turbulenz Services in-order to be populated. If the game is running in an environment without access to the Turbulenz Services then these objects will be created with their default settings.
Turbulenz Services are only available when running in local, hub or game site. All requests made by the Turbulenz Services are asynchronous.
Required scripts
The TurbulenzServices object requires:
/*{{ javascript("jslib/utilities.js") }}*/
/*{{ javascript("jslib/services/turbulenzbridge.js") }}*/
/*{{ javascript("jslib/services/turbulenzservices.js") }}*/
You should look at the documentation for the each service to find its required scripts.
Each method uses a ServiceRequester object.
Some of our services HTTP requests are protected against tampering. If this is the case then the method will have one of the following notices:
Note
This is an encrypted API call
Note
This is a signed API call
This means that any HTTP requests made by the API are encrypted or signed to avoid simple alteration by malicious users.
If these notes are not included in the documentation for the API then the results of the API call can be easily manipulated by an attacker. Please keep this in mind when using the API.
Example
For example, when adding a “Most bullets fired” leaderboard a developer might try:
However, the API call in step 1 is unprotected so an attacker can easily alter this value by changing the HTTP response. This allows an attacker to set any score they like on the leaderboards. Instead the developer should use a protected API to get the leaderboard scores. In this case the developer should have used the protected API calls on the UserDataManager to store the “Most bullets fired” score:
It is now not easy for an attacker to modify any of the HTTP requests without invalidating the signatures.
Summary
Create a GameSession object.
Syntax
function sessionCreatedFn(gameSession) {}
var gameSession = TurbulenzServices.createGameSession(requestHandler, sessionCreatedFn, errorCallbackFn);
errorCallbackFn (Optional)
The GameSession returned contains no information about the game session until sessionCreatedFn is called. Once sessionCreatedFn is called the GameSession returned must be destroyed before the game is closed.
Summary
Create a MappingTable object. The MappingTable object retrieves the mapping table for the game. See the creating a mapping table for more information on mapping tables.
Syntax
function tableReceivedFn(mappingTable) {}
var mappingTable = TurbulenzServices.createMappingTable(requestHandler,
gameSession,
tableReceivedFn,
defaultMappingSettings,
errorCallbackFn);
// example usage:
var tableReceived = function tableReceivedFn(mappingTable)
{
// load assets here
textureManager.setPathRemapping(mappingTable.urlMapping, mappingTable.assetPrefix);
shaderManager.setPathRemapping(mappingTable.urlMapping, mappingTable.assetPrefix);
souindManager.setPathRemapping(mappingTable.urlMapping, mappingTable.assetPrefix);
sceneLoader.setPathRemapping(mappingTable.urlMapping, mappingTable.assetPrefix);
};
var mappingTable;
function gameSessionCreatedFn(gameSession)
{
mappingTable = TurbulenzServices.createMappingTable(requestHandler
gameSession,
tableReceived);
}
var gameSession = TurbulenzServices.createGameSession(requestHandler, gameSessionCreatedFn);
A JavaScript object. Contains the mapping table settings to use when the GameSession is null, the Turbulenz Services are unavailable or the MappingTable has not yet been received. Defaults to
{
mappingTablePrefix: "staticmax/",
assetPrefix: "missing/",
mappingTableURL: "mapping_table.json",
urnMapping: {}
}
Here mappingTablePrefix is the relative path to the MappingTable’s physical files, assetPrefix is the path to prepend to assets missing from the MappingTable, mappingTableURL is the relative path to the MappingTable file and urnMapping is the table to use in the case that the MappingTable file could not be found.
errorCallbackFn (Optional)
Returns a MappingTable object with defaultMappingSettings values. The MappingTable object methods cannot be called until the tableReceivedFn is called.
Summary
Creates a MultiPlayerSessionManager object.
Syntax
var multiPlayerSessionManager = TurbulenzServices.createMultiplayerSessionManager(requestHandler,
gameSession);
Returns a MultiPlayerSessionManager object. The MultiPlayerSessionManager object is ready to use upon creation. You must dispose of this object by calling MultiPlayerSessionManager.destroy, either when you finish using the object or in TurbulenzEngine.onunload. This will destroy any MultiPlayerSession objects which have not yet been destroyed.
Summary
Create a LeaderboardManager object. The LeaderboardManager object retrieves leaderboards meta data and provides an API for querying the leaderboards.
Syntax
function leaderboardsReceivedFn(leaderboardManager) {}
var leaderboardManager = TurbulenzServices.createLeaderboardManager(requestHandler,
gameSession,
leaderboardsReceivedFn,
errorCallbackFn);
// example usage:
var leaderboardsReady = false;
var leaderboardsReceived = function leaderboardsReceivedFn(leaderboardManager)
{
leaderboardsReady = true;
};
var leaderboardManager;
function gameSessionCreatedFn(gameSession)
{
leaderboardManager = TurbulenzServices.createLeaderboardManager(requestHandler,
gameSession,
leaderboardsReceived,
errorCallbackFn);
}
var gameSession = TurbulenzServices.createGameSession(requestHandler, gameSessionCreatedFn);
errorCallbackFn (Optional)
Returns a LeaderboardManager object. The LeaderboardManager object methods cannot be called until the leaderboardsReceivedFn is called.
Summary
Create a BadgeManager object. The BadgeManager object provides an API for querying and awarding badges.
Syntax
var badgeManager = TurbulenzServices.createBadgeManager(requestHandler, gameSession);
// example usage:
var badgeManager;
function gameSessionCreatedFn(gameSession)
{
badgeManager = TurbulenzServices.createBadgeManager(requestHandler, gameSession);
}
var gameSession = TurbulenzServices.createGameSession(requestHandler, gameSessionCreatedFn);
Returns a BadgeManager object. The BadgeManager object is ready upon creation.
Summary
Create a StoreManager object. The StoreManager object retrieves store items meta data, user owned items and provides an API for managing the game store basket.
Syntax
function storeMetaReceivedFn(storeManager) {}
var storeManager = TurbulenzServices.createStoreManager(requestHandler,
gameSession,
storeMetaReceivedFn,
errorCallbackFn);
// example usage:
var storeManagerReady = false;
var storeManagerReceived = function storeManagerReceivedFn(storeManager)
{
storeManagerReady = true;
};
var storeManager;
function gameSessionCreatedFn(gameSession)
{
storeManager = TurbulenzServices.createStoreManager(requestHandler,
gameSession,
storeManagerReceived,
errorCallbackFn);
}
var gameSession = TurbulenzServices.createGameSession(requestHandler, gameSessionCreatedFn);
errorCallbackFn (Optional)
Returns a StoreManager object. The StoreManager object methods cannot be called until the storeManagerReceivedFn is called.
Summary
Create a UserProfile object. The UserProfile object contains user profile information.
Syntax
function profileReceivedFn(userProfile)
{
// Use profile information here
}
var userProfile = TurbulenzServices.createUserProfile(requestHandler,
profileReceivedFn,
errorCallbackFn);
errorCallbackFn (Optional)
Returns a UserProfile object. The UserProfile object cannot be used until profileReceivedFn is called.
Summary
Present the user with options for upgrading their account from anonymous to a full user. If supported a dialog or login screen will be presented listing the options available to upgrade to a full turbulenz account.
Syntax
var accountUpgraded = function accountUpgradedFn()
{
// Re-request the UserProfile and check the 'anonymous'
// property to determine the user's new status.
}
TurbulenzServices.upgradeAnonymousUser(accountUpgraded);
Summary
Send a custom event to be tracked for the game.
The event contributes to the metrics for the game with the event value being saved as an aggregate for each unique key.
These metrics can be seen on the Hub once a game has been published, and the events themselves can be downloaded using the exportevents tool.
Syntax
TurbulenzServices.sendCustomMetricEvent(eventKey, eventValue, requestHandler, gameSession);
errorCallbackFn (Optional)
Note
Custom events are only recorded for the game on the game site and not on Turbulenz Local Server or the Hub. These events contribute to the custom metrics only when eventValue is a number and not an array.
Note
Turbulenz already provides a variety of metrics it tracks for your game by default. For more information see the Hub User Guide.
Summary
Send a batch of custom events to be tracked for the game. Sending a custom metrics in a batch rather than individually with TurbulenzServices.sendCustomMetricEvent allows an application to reduce the number of requests made to the servers. This can reduce both cpu cost and bandwidth cost from an application.
Each event in the batch will preserve a timestamp based on the time it is added to the batch meaning metrics from batches lose no information versus individual metrics.
Sending individual metrics may still be preferred in cases where you have high importance low frequency metrics (started level, level complete) versus tracking high frequency metrics (such as collected pickup, killed enemy). When higher frequency metrics are batched it’s possible that some could be lost in situations where a user closes the browser in the middle of a game session, as a result more important events may still want to be tracked immediately when they happen.
The ideal number of events in a batch can vary depending on the size of the event data (e.g. large event arrays vs single values). Batches of 10 to 20 metrics will normally be reasonable but consider looking at Working with HTTP requests for some comments on sizes of HTTP requests.
The events contribute to the metrics for the game with the event values being saved as aggregates for each unique key.
These metrics can be seen on the Hub once a game has been published, and the events themselves can be downloaded using the exportevents tool.
Syntax
TurbulenzServices.sendCustomMetricEventBatch(eventBatch, requestHandler, gameSession);
errorCallbackFn (Optional)
Note
Custom events are only recorded for the game on the game site and not on Turbulenz Local Server or the Hub. Events from the batch contribute to the custom metrics only when eventValue is a number and not an array.
Note
Turbulenz already provides a variety of metrics it tracks for your game by default. For more information see the Hub User Guide.
Summary
Get a ServiceRequester object for a given service.
Syntax
var serviceRequester = TurbulenzServices.getService('gameSessions');
You can find a list of currently supported service names here.
Summary
A JavaScript function. The default error callback for the TurbulenzServices. Returns an error message and its HTTP status.
Syntax
TurbulenzServices.defaultErrorCallback = function errorCallbackFn(errorMsg, httpStatus) {};
// example usage:
TurbulenzServices.defaultErrorCallback = function defaultErrorCallbackFn(msg)
{
var tmpConsole = window.console || console;
if (tmpConsole)
{
tmpConsole.log(msg);
}
};
Summary
A JavaScript function. This function is called when a service is re-enabled.
Syntax
TurbulenzServices.onServiceAvailable = function onServiceAvailableFn(serviceRequester) {
Utilties.log(serviceRequester.serviceName + ' is available');
};