The GameProfileManager object is an API for setting a public game profile and retrieving other users’ game profiles. Each user has a public game profile string (typically a JSON string) that can be retrieved by any other user playing the same game. This public profile can be used to hold a small amount of game specific information, for example: level, XP, favorite weapon, ... . The manager allows retrieving multiple users’ game profiles in one request using the gameProfileManager.getList API.
The game profile string is persistent and can be read by any other user after the current user’s game has closed.
GameProfileManager shouldn’t be confused with userdata (for save games and game preferences) , badges (for achievements) or leaderboards (for high scores).
Required scripts
The GameProfileManager object requires:
/*{{ javascript("jslib/utilities.js") }}*/
/*{{ javascript("jslib/services/turbulenzservices.js") }}*/
/*{{ javascript("jslib/services/gameprofilemanager.js") }}*/
The GameProfileManager is for retrieving a small profile string (typically a JSON string). The profile string must be smaller than 1KB in order to limit the size of responses from the gameProfileManager.getList API since up to 64 users can be requested simultaneously.
Any strings stored will need to be localized by game logic as users of any language can read the user’s game profile.
Setting the current user’s game profile value:
function callbackFn()
{
Utilities.log('Game profile set');
}
var userStats = {
'level': 14,
'xp': 134800
};
gameProfileManager.set(JSON.stringify(userStats), callbackFn);
Getting another user’s game profile value:
function callbackFn(username, gameProfile)
{
if (gameProfile.value)
{
var otherUsersStats = JSON.parse(gameProfile.value);
Utilities.log(username + ':');
Utilities.log('level: ' + otherUsersStats.level);
Utilities.log('XP: ' + otherUsersStats.xp);
}
}
gameProfileManager.get('dave', callbackFn);
Getting a group of user’s game profile values:
function callbackFn(gameProfiles)
{
var username;
for (username in gameProfiles)
{
if (gameProfiles.hasOwnProperty(username))
{
var gameProfile = gameProfiles[username];
if (gameProfile.value)
{
var otherUsersStats = JSON.parse(gameProfile.value);
Utilities.log(username + ':');
Utilities.log('level: ' + otherUsersStats.level);
Utilities.log('XP: ' + otherUsersStats.xp);
}
}
}
}
gameProfileManager.getList(['dave', 'bob', 'ben'], callbackFn);
A more advanced example showing how to add additional information to the leaderboards:
var currentLeaderboardsResult;
var gameProfiles = {};
var displayLeaderboard = function displayLeaderboardFn()
{
if (currentLeaderboardsResult)
{
var leaderboardString = leaderboardManager.meta[currentLeaderboardsResult.key].title + '\n';
var view = currentLeaderboardsResult.getView();
var ranking = view.ranking;
var numScores = ranking.length;
var i;
for (i = 0; i < numScores; i += 1)
{
var row = ranking[i];
var username = row.user.username;
leaderboardString += row.rank + ',';
leaderboardString += username + ',';
leaderboardString += row.score + ',';
if (gameProfiles.hasOwnProperty(username))
{
var gameProfile = JSON.parse(gameProfiles[username].value);
leaderboardString += gameProfile.level + ',';
leaderboardString += gameProfile.xp;
}
leaderboardString += '\n';
}
Utilities.log(leaderboardString);
}
};
var gameProfileManager = GameProfileManager.create(requestHandler, gameSession);
var onSlidingWindowUpdate = function onSlidingWindowUpdateFn()
{
if (currentLeaderboardsResult)
{
// request profiles for the entire sliding window (all of the results from the current response)
// as this is more efficient (only 1 game profile request per leaderboard request)
var slidingWindow = currentLeaderboardsResult.getSlidingWindow();
var ranking = slidingWindow.ranking;
var numScores = ranking.length;
var users = [];
var i;
for (i = 0; i < numScores; i += 1)
{
var username = ranking[i].user.username;
if (!gameProfiles.hasOwnProperty(username))
{
users.push(username);
}
}
var onGameProfileList = function onGameProfileListFn(newGameProfiles)
{
var u;
for (u in newGameProfiles)
{
if (newGameProfiles.hasOwnProperty(u))
{
gameProfiles[u] = newGameProfiles[u];
}
}
displayLeaderboard();
};
if (users.length > 0)
{
gameProfileManager.getList(users, onGameProfileList);
}
}
};
function onLeaderboardResult(key, leaderboardResult)
{
currentLeaderboardsResult = leaderboardResult;
onSlidingWindowUpdate();
leaderboardResult.onSlidingWindowUpdate = onSlidingWindowUpdate;
}
var onScrollUpClicked = function onScrollUpClickedFn()
{
currentLeaderboardsResult.scrollUp(displayLeaderboard);
};
var onScrollDownClicked = function onScrollDownClickedFn()
{
currentLeaderboardsResult.scrollDown(displayLeaderboard);
};
var spec = {
type: 'near',
size: 5
};
leaderboardManager.get('score', spec, onLeaderboardResult);
Summary
Creates a GameProfileManager object.
Syntax
var gameProfileManager = GameProfileManager.create(requestHandler, gameSession, defaultErrorCallbackFn);
Returns a GameProfileManager object or if the Turbulenz Services are unavailable returns null.
Summary
Get a user’s game profile by username.
Syntax
function callbackFn(username, gameProfile) {}
gameProfileManager.get(username, callbackFn, errorCallbackFn);
// example usage:
gameProfileManager.get('dave', callbackFn);
A JavaScript function. Called on receipt of the request from the Turbulenz Services. With the following arguments:
null if the username does not exist. Otherwise, a JavaScript object with the following format:
errorCallbackFn (Optional)
Summary
Get a list of users’ game profiles by usernames.
Syntax
function callbackFn(gameProfiles) {}
var ok = gameProfileManager.getList(usernames, callbackFn, errorCallbackFn);
// example usage:
function callbackFn(gameProfiles) {
var username;
for (username in gameProfiles)
{
if (gameProfiles.hasOwnProperty(username))
{
Utilities.log(username + ': ' + gameProfiles[username].value);
}
}
}
gameProfileManager.getList(['dave', 'ben', 'bob'], callbackFn);
A JavaScript function. Called on receipt of the request from the Turbulenz Services. With the following arguments:
A JavaScript dictionary with usernames for keys and values as objects with the following format:
errorCallbackFn (Optional)
The gameProfiles array retrieved might not be in the same order as the usernames requested. Users will not be returned in the gameProfiles array if:
If usernames length is greater than GameProfileManager.maxGetListUsernames this function will return false and neither callbackFn or errorCallbackFn will be called. Otherwise, this returns true.
Summary
Set the current user’s game profile string.
Note
This is an encrypted API call
Syntax
function callbackFn() {}
var ok = gameProfileManager.set(value, callbackFn, errorCallbackFn);
errorCallbackFn (Optional)
If value is too large to set this function returns false and neither callbackFn or errorCallbackFn will be called. Otherwise, this returns true.
This sets the current user’s game profile string to value. If the current user’s game profile string is already set then this overwrites the profile string.
Summary
Remove the current user’s game profile.
Note
This is an encrypted API call
Syntax
function callbackFn(key) {}
gameProfileManager.remove(callbackFn, errorCallbackFn);
errorCallbackFn (Optional)
Summary
The max size of a value string for gameProfileManager.set.
Syntax
var maxValueSize = gameProfileManager.maxValueSize;
This is set to 1024.
Note
This property is read only.
Summary
The max length of the usernames array for gameProfileManager.getList.
Syntax
var maxGetListUsernames = gameProfileManager.maxGetListUsernames;
This is set to 64.
Note
This property is read only.
Summary
The ServiceRequester object for the gameProfile service.
Syntax
var serviceRequester = gameProfileManager.service;
Summary
A JavaScript function. Returns an error message and its HTTP status.
Syntax
function errorCallbackFn(errorMsg, httpStatus, calledByFn, calledByParams) {}