Welcome to the Facebook Instant Games SDK Tutorials. This series of tutorials covers many aspects of using the Facebook Instant Games SDK.

In this tutorial we will look at the important process of getting the players details and other important information to enable you to personalise the players gaming experience.
The Facebook Instants SDK provides you quite a bit of information about the device that the player is playing the game on as well as about the player themselves.

Device specific information

Players locale

One of the most important pieces if information you can get is the players locale, you can get this by calling:

[sourcecode language=”js”]
FBInstant.getLocale();
[/sourcecode]

This returns a string of the users language locale in the format “en_US”. You can use this to provide text and art work in different languages.

Players device platform

You can grab the players device platform by calling:

[sourcecode language=”js”]
FBInstant.getPlatform();
[/sourcecode]

This returns a string containing either WEB, IOS or ANDROID.

Player Specific Information

Player ID

Each player that plays your game has an ID associated with them, note that this ID is scoped to your game and is not consistent across different games. This is to prevent you tracking the same users across multiple games. You can collect this ID by calling:

[sourcecode language=”js”]
FBInstant.player.getID();
[/sourcecode]

A string representing the players ID will be returned. You can use this ID in your back-end to identify users of your game and assign data to them. This ID is also useful for users that sign up to receive notifications from your bot as well as filtering out the player from a list of all users.

Player Name

Using the players name when addressing them in the game or in context messages / bot notifications adds a level of personalisation that can help players connect with your game. You can collect the players name by calling:

[sourcecode language=”js”]
FBInstant.player.getName();
[/sourcecode]

Players Photo

Using the players profile photo is a great way to add personalisation into the game. To retreve the players photo URL you call:

[sourcecode language=”js”]
FBInstant.player.getPhoto();
[/sourcecode]

However this only retrieves the players photo url and not the photo itself. To retrieve the actual photo you will need to download it:

[sourcecode language=”js”]
var image = new Image();
image.crossOrigin = "anonymous"; // Allow cross origin access
image.onload = function()
{
// Image loaded
}
image.onerror = function()
{
// Image did not load
}
image.src = FBInstant.player.getPhoto();
[/sourcecode]

Once loaded you now have a HTML5 Image object that you can render to wherever you like. I tend to use the players profile pic to show the players avatar in leaderboards, in messages and in-game.