Adding GameCircle Social Features

Overview

This page helps game developers incorporate GameCircle Friends data into their games. The GameCircle Friends feature is available to players using Amazon Fire devices.

Players on Amazon Fire devices (tablet, phone, or TV) can use GameCircle’s device-specific features to create a player profile and set up a friends list to connect with other players with GameCircle profiles. The topics on this page show you how to access players’ friends data and use it to provide an enhanced game experience for players using Fire devices. Once you have the data, you can display it in your own games or use it to leverage custom social interaction features. Social interactions are great for increasing player engagement with your game.

GameCircle Friends data can be accessed and used by your game regardless of whether it’s running on an Amazon device or not. This lets you support players who use multiple devices including a Fire device, giving them a seamless social experience regardless of which device they’re playing your game on.

Use the GameCircle social APIs to:

These social APIs are available in the following client libraries: Java, C# (for Unity), and C++ (JNI), and support Amazon Fire and Android devices. You can also get scores and percentile ranks for friends using the ActionScript APIs for Adobe AIR.

Display Friend-Specific Leaderboards

Display friend-specific scores and percentile rankings on any of your game’s leaderboards for the current player and their friends. Use a customized leaderboard display and filter the leaderboard data for friends only.

If you’re already using a customized in-game leaderboard display, you simply need to filter the results to get data for the current player’s GameCircle friends only. If you’ve been displaying the GameCircle overlay and are now transitioning to a custom leaderboard display, here’s a quick overview on how GameCircle structures leaderboard displays using scores and percentile rankings.

  • Score is the highest score submitted by each game player to a particular leaderboard.
  • Percentile rank indicates how a game player’s top score measures up against all other players on a leaderboard. A 1% rank means the player’s high score is higher than 99% of all other players on the leaderboard. a 50% rank means the score is in the middle of the pack.

GameCircle leaderboard displays feature percentile rankings along with scores because they make it quick and easy for a player to compare their performance against all other players on the leaderboard–and track their own progress as they move up the ranks. To keep the leaderboard view manageable, GameCircle displays a score for each of six key points in the rankings (1%, 10%, 25%, 50%, 75%, and 100%), along with the current player’s score and rank, and scores representing 1% over and under the current player. Each rank (other than the current player) is represented by a player randomly selected from those who’ve earned that score. Showing scores for each rank tells the player what score they need to get into the top 10% or 1%.

To get friend-filtered leaderboard scores

  • Call LeaderboardsClient.getScores() and set the LeaderboardFilter parameter to FRIENDS_ALL_TIME.

This operation returns an ordered list of the top 100 scores for a specified leaderboard. The filter parameter is used to get a subset of these top scores, filtered either for a certain time span (all-time, current week, or current day), or for friends only. With the FRIENDS_ALL_TIME filter, the getScores() result set becomes an ordered list of high scores for up to 100 of the current player’s friends. Friend-filtered results reflect all-time top scores.

Data is returned as a collection of Score objects. A Score object includes the score value, rank (ordinal not percentile), and a Player object identifying the player who earned the high score. Additional metadata returned includes the number of Score objects returned.

Code sample 1 (Java)

// Get scores for current player's friends only.
LeaderboardsClient lbClient = agsClient.getLeaderboardsClient();
lbClient.getScores (someLeaderboardId, LeaderboardFilter.FRIENDS_ALL_TIME, null).setCallback(new AGResponseCallback<GetScoresResponse>() {
	@Override
	public void onComplete(GetScoresResponse result) {
		if (result.isError()) {
			// Handle getScores error
		}
		else {
			List<Score> scores = result.getScores();
			// Do work with scores, ranks and players
			for(int i=0; i<result.getNumScores(); i++){
				int rank = scores.get(i).getRank();
				long score = scores.get(i).getScoreValue();
				Player player = scores.get(i).getPlayer();
				// Handle friend player data
			}
		}
	}
});

To get percentile ranks for friends

  • Call LeaderboardsClient.getPercentileRanks().

This operation returns the same data used in the GameCircle leaderboard displays, and now includes percentile rankings and scores for all of the current player’s friends. When used with a GLOBAL time filter, percentiles are calculated based on the range of high scores during the filter’s time frame (all-time, current week, current day). The FRIENDS_ALL_TIME filter is not used with this API, as friends are always returned.

Data is returned as a collection of LeaderboardPercentileItem objects. Each object contains a percentile, a raw score value, and a Player object identifying a player who earned the score. The collection includes data for these percentile ranks:

  • Six specific percentile ranks: 1% (the top score for the game) , 10%, 25%, 50%, 75%, and 100%
  • the current player’s rank
  • One percentage point above the current player
  • One percentage point below the current player
  • Ranks for all of the current player’s friends

Code sample 2

//Get percentile rankings including the current player's friends ranks
LeaderboardsClient lbClient = agsClient.getLeaderboardsClient();
lbClient.getPercentileRanks (someLeaderboardId, LeaderboardFilter.GLOBAL_ALL_TIME, null).setCallback(new AGResponseCallback<GetLeaderboardPercentilesResponse>() {
	@Override
	public void onComplete(GetLeaderboardPercentilesResponse result) {
		if (result.isError()) {
			// Handle getPercentileRanks error
		}
		else {
			List<LeaderboardPercentileItem> percentiles = result.getPercentileList();
			// Do work with percentiles, scores, and players
			for(int i=0; i<percentiles.size(); i++){
				int pRank = percentiles.get(i).getPercentile();
				long score = percentiles.get(i).getPlayerScore();
				Player player = percentiles.get(i).getPlayer();
				// Handle friend player data
			}
		}
	}
});

Troubleshooting

  • If you get an empty response, check for an error code of “UNRECOVERABLE”. The problem could be any of the following:

    • you haven’t yet initialized AmazonGamesClient
    • leaderboardId is null or not recognized
  • If you call getPercentileRanks() with the FRIENDS_ALL_TIME filter, you’ll get an “UNRECOVERABLE” error code.

Get a Player’s GameCircle Friends

Get a list of all GameCircle friends of a current player who also play your game. The information returned from GameCircle includes a player ID, nickname, and profile image URL for each friend.

  • Player ID uniquely identifies a player in GameCircle. Most game developers submit and retrieve game progress for a current player and don’t need to access the player’s GameCircle ID, which is stored locally on the player’s device(s). When incorporating GameCircle’s social APIs, however, you’ll need to identify individual players by their player ID. Some games already track GameCircle player IDs independently, such as those that use a game-specific social network or provide expanded player profiles; for these games, the player IDs returned by the GameCircle social APIs will match up with those used to identify current players.
  • Alias represents the player’s chosen nickname for their profile. It also uniquely identifies a player in GameCircle. In the GameCircle UI, players are initially given a randomly generated nickname, but they can replace it with their own. Players use nicknames to locate other players and add them to their GameCircle friends list.
  • Avatar URL points to a GameCircle-provided image. Players select an avatar as their profile image, and multiple players can choose the same avatar. The image is a 1024x1024 .jpg file.

To get GameCircle friends

Request a list of the current player’s friends:

  1. Call PlayerClient.getFriendIds(). This operation returns a list of playerId values.
    The API returns only those GameCircle friends for the current player who also play your game.
  2. Once you’ve acquired a list of playerId values, call PlayerClient.getBatchFriends() with the list of player IDs to get additional profile info for each friend. This operation returns a Player object for each playerId in the list.
  3. For each Player object, extract the player’s ID, nickname and image URL strings using getPlayerId(), getAlias(), and getAvatarUrl().

Once you have Player objects for the current player’s GameCircle friends, you can display their friends using recognizable nicknames rather than player IDs.

Code sample 3

//Get playerIDs for all of the current player's friends
//This sample uses a unique user value to track requests & responses
plClient.getFriendIds(someUniqueValue).setCallback(new AGResponseCallback<RequestFriendIdsResponse>() {
	@Override
	public void onComplete(RequestFriendIdsResponse result) {
		if (result.isError()) {
			// Handle getFriendIds error
		}
		else {
			List<String> playerIds = result.getFriends();

			// get Player objects for the list of player IDs
			plClient.getBatchFriends(playerIds, someUniqueValue).setCallback(new AGResponseCallback<RequestFriendsResponse>() {
				@Override
				public void onComplete(RequestFriendsResponse result) {
					if (result.isError()) {
						// Handle getBatchFriends error
					}
					else {
						if (result.getUserData() == someUniqueValue) {
							List<Player> players = result.getFriends();
							// get friends profile data
							for(int i=0; i<;players.size(); i++){
								String pAlias = players.get(i).getAlias();
								String pAvatar = players.get(i).getAvatarUrl();
								String pPlayerId = players.get(i).getPlayerId();
							}
						}
					}
				}
			});
		}
	}
});

Troubleshooting

  • If the current player is not authenticated (in guest mode) or their profile is hidden, both getFriendIds() and getBatchFriends() will fail with an error code UNRECOVERABLE.
  • The operation getBatchFriends() validates that the players listed do have a friend relationship with the current player. If a player does not have an active relationship with the current player–or if the player’s profile is hidden–no data for that player is returned.

Look Up a Friend’s Game Progress

With a list of friends for the current player, you can get game progress for any individual player. Available game progress data includes (1) a player’s top score on a game leaderboard, (2) a player’s and percentile ranking on a game leaderboard, and (3) progress toward game achievements. With this data, you can create UIs to show player stats and compare stats between players, incorporate player stats into gameplay, or develop entirely new ways to leverage friends’ game progress.

To get a friend’s game progress

To get game data for a friend, you need to have the friend’s player ID. This ID is returned in a Player object along with the player’s nickname and profile image (as a URL). Player objects are returned with any of these operations. PlayerClient.getBatchFriends(), LeaderboardsClient.getScores(), and LeaderboardsClient.getPercentileRanks().

  1. To get a friend’s leaderboard top score, call LeaderboardsClient.getScoreForPlayer(), specifying the leaderboard ID and the friend’s player ID. You can also add a time-span filter for the leaderboard to get an all-time, weekly, or daily top score. Don’t use the filter FRIENDS_ALL_TIME; with this operation, it’ll have the same results as GLOBAL_ALL_TIME. This operation returns two values, the friend’s score and rank.
  2. To get a friend’s leaderboard percentile ranking, call LeaderboardsClient.getPercentileRanksForPlayer(), specifying the leaderboard ID and the friend’s playerId. You can also add a time-span filter for the leaderboard to get an all-time, weekly, or daily top score. Don’t use the filter FRIENDS_ALL_TIME; it’ll return the same result as GLOBAL_ALL_TIME. This operation returns the same data as getPercentileRanks(), but with only a single LeaderboardPercentileItem object containing the friend’s percentile and score.
  3. To get a friend’s achievement progress, you can either get progress on a single achievement or on all achievements.

    • To get progress on a single achievement:
      1. Call AchievementsClient.getAchievementForPlayer(), specifying the achievement’s ID and the friend’s playerId. This operation returns an Achievement object, which includes the friend’s progress as well as descriptive info about the achievement. Note: you can get a collection of all game achievements, including achievement IDs by calling AchievementsClient.getAchievements().
      2. Get the friend’s progress from the Achievement object. Use getProgress() to get the percent completed. Use isUnlocked() to determine whether the friend has earned the achievement. Use getDateUnlocked to learn when the friend earned the achievement.
    • To get progress on all achievements:
      1. Call AchievementsClient.getAchievementsForPlayer(), specifying the friend’s playerId. This operation returns the friend’s a collection of Achievement objects, both as a list and as a map. Each Achievement object includes the friend’s progress as well as descriptive info about the achievement.
      2. Get the friend’s progress from each of the Achievement objects as with the single achievement.

Code sample 5

//Get game progress for a friend of the current player.
LeaderboardsClient lbClient = agsClient.getLeaderboardsClient();
AchievementsClient acClient = agsClient.getAchievementsClient();

//Get friend's high score for a leaderboard
lbClient.getScoreForPlayer (someLeaderboardId, somePlayerId, LeaderboardFilter.GLOBAL_ALL_TIME, null).setCallback(new AGResponseCallback<GetPlayerScoreResponse>() {
	@Override
	public void onComplete(GetPlayerScoreResponse result) {
		if (result.isError()) {
			// Handle getScoreForPlayer error
		}
		else {
			long playerScore = result.getScoreValue();
			// display player's score
		}
	}
});

//Get friend's percentile ranking for a leaderboard
lbClient.getPercentileRanksForPlayer (someLeaderboardId, somePlayerId, LeaderboardFilter.GLOBAL_ALL_TIME, null).setCallback(new AGResponseCallback<GetLeaderboardPercentilesResponse>() {
	@Override
	public void onComplete(GetLeaderboardPercentilesResponse result) {
		if (result.isError()) {
			// Handle getPercentileRanksForPlayer error
		}
		else {
			List <LeaderboardPercentileItem> playerPercentile = result.getPercentileList();
			// display player's percentile rank
		}
	}
});

//Get friend's achievement progress
acClient.getAchievementsForPlayer(some_player_id, null).setCallback(new AGResponseCallback<getAchievementsResponse>() {
	@Override
	public void onComplete( getAchievementsResponse  result) {
		if (result.isError()) {
			// Handle getAchievementsClient error
		}
		else {
			List <Achievement> playerAchievements = result.getAchievementsList();
			//do something to check if the achievement is visible and earned or not
			// display player's achievements
		}
	}
});

Help Players Add GameCircle Friends

Make it easy for players of your game to connect with each other. One of the best ways to increase player engagement with your game is to promote strong social networking–and give players interesting ways to interact with friends. For players using Fire devices, you can link directly to the Friends tab of your game’s GameCircle details page as a way to encourage players to add friends to their network. The Friends tab features the new Suggested Friends feature, which highlights players who have recently played your game. On this tab, players can also see current friends who are playing your game and compare game stats with them. This tab is currently supported on Fire tablets only, with support on Fire TV and phone devices coming soon.

To open the GameCircle Friends tab for your game:

Add the link as a button that is visible only on supported Fire devices and hidden on all non-supported devices.

  1. Add a GameCircle Friends button to your activity’s layout. Set the button’s enabled visibility to GONE or INVISIBLE.
  2. Create an intent to launch the game details activity.
    • Set the button’s action to “com.amazon.ags.app.SHOW_GAME_DETAILS”.
  3. Check to verify that the intent is safe. Use PackageManager.queryIntentActivities to check that the new Friends button intent is resolveable.
  4. Conditional to the intent being safe, enable and display the button. NOTE: This step should only occur if the intent is safe–it may crash your game on a non-supported device.
    In the onClick action of the button:
  • Set the following extra data:
    • putExtra("launched_from_game", true)`
    • putExtra("package_name", getApplicationContext().getPackageName())`
    • putExtra("tab_name", "FRIENDS");`
  • Set the button visibility to VISIBLE.

Code sample 6

// Display a button that launches the Friends tab on Fire devices where the Friends
// tab is supported and hidden on all other

// Get the relevant button from the activity layout
friendsTabIntentButton = (Button) findViewById(R.id.gcFriendTabIntentButton);

// Create the intent for launching the GameCircle game details page
final Intent friendsTabIntent = new Intent();
friendsTabIntent.addFlags(Intent.FLAG_ACTIVITY_PREVIOUS_IS_TOP);
friendsTabIntent.setAction("com.amazon.ags.app.SHOW_GAME_DETAILS");

// Check if the intent is resolvable (skipping this might crash app!)
PackageManager packageManager = getPackageManager();
List <resolveinfo>activities = packageManager.queryIntentActivities(friendsTabIntent, 0);
boolean isIntentSafe = activities.size() > 0;

if(isIntentSafe) {
    // If intent is safe, enable the button and display it
    if(friendsTabIntentButton != null) {
        friendsTabIntentButton.setOnClickListener(new OnClickListener() {
            @Override
            public void onClick(final View v) {
                // Set bundle extras
                friendsTabIntent.putExtra("launched_from_game", true);
                friendsTabIntent.putExtra("package_name", getApplicationContext().getPackageName());
                friendsTabIntent.putExtra("tab_name", "FRIENDS");
                startActivity(friendsTabIntent);
            }
        });
        friendsTabIntentButton.setVisibility(View.VISIBLE);
    }
} else {
    // Hide the button
    friendsTabIntentButton.setVisibility(View.GONE);
}

## API Quick Reference {#quickref}

Task Android Java Android JNI Unity (C#)
Get progress on all achievements for a specified player

getAchievementsForPlayer(
String playerId,
Object ... userData)

static void getAchievementsForPlayer(
const char* playerId,
IGetAchievementsCb* const callback,
int developerTag = 0);

RequestAchievementsForPlayer(
string playerId,
int userData = 0 )

GetAchievementsResponse
List<Achievement> getAchievementsList()
Map<String, Achievement> getAchievementsMap()
int getNumVisibleAchievements()
IGetAchievementsCb

const AchievementsData* responseStruct

AchievementsData
int numAchievements
const AchievementData* achievements
AGSRequestAchievementsForPlayerResponse
List<AGSAchievement> achievements
public string playerId


Get progress on a specified achievement for a specified friend

getAchievementForPlayer(
String achievementId,
String playerId,
Object ... userData)

static void getAchievementForPlayer(
const char* achievementId,
const char* playerId,
IGetAchievementCb* const callback,
int developerTag = 0)

 
GetAchievementResponse
Achievement getAchievement()
IGetAchievementCb
const AchievementData* responseStruct

 

Get top score for a specified player and leaderboard

getScoreForPlayer(
String leaderboardId,
String playerId,
LeaderboardFilter filter,
Object ... userData)

getScoreForPlayer(
char const* const leaderboardId,
char const* const playerId,
AmazonGames::LeaderboardFilter filter,
ILeaderboardGetPlayerScoreCb* const callback,
int developerTag = 0)

RequestScoreForPlayer(
string leaderboardId,
string playerId,
LeaderboardScope scope,
int userData = 0 )

GetPlayerScoreResponse
long getScoreValue()
int getRank()
ILeaderboardGetPlayerScoreCb

PlayerScoreInfo* response

PlayerScoreInfo
const char* leaderboardId
long long scoreValue
int rank
AGSRequestScoreForPlayerResponse
string leaderboardId

LeaderboardScope scope

int rank

long score
public string playerId
Get percentile rank for a specified player and leaderboard

getPercentileRanksForPlayer(
String leaderboardId,
String playerId,
LeaderboardFilter filter,
Object ... userData)

static void getPercentileRanksForPlayer(
char const* const leaderboardId,
char const* const playerId,
AmazonGames::LeaderboardFilter filter,
ILeaderboardGetPercentilesCb* const callback,
int developerTag = 0)

RequestPercentileRanksForPlayer(
string leaderboardId,
string playerId,
LeaderboardScope scope,
int userData = 0 )

GetLeaderboardPercentilesResponse
int getUserIndex()
Leaderboard getLeaderboard()

List<LeaderboardPercentileItem> getPercentileList()

LeaderboardPercentileItem
Player getPlayer()
long getPlayerScore()
int getPercentile()
ILeaderboardGetPercentilesCb

const LeaderboardPercentiles* response

LeaderboardPercentiles
LeaderboardInfo leaderboardInfo
int userIndex
int numPercentiles

const PercentileItem* percentiles

PercentileItem
const char* playerAlias
long long scoreValue
int percentile
AGSRequestPercentilesForPlayerResponse
string leaderboardId
AGSLeaderboard leaderboard

List<AGSLeaderboardPercentile> percentiles

AGSLeaderboardPercentile
int percentile
long score
AGSPlayer player
int userIndex
LeaderboardScope scope
string playerId
Get a list of the current player's friends

getFriendIds(
Object... userData)

getFriendIds(
IGetFriendIdsCb* const callback,
int developerTag = 0)

RequestFriendIds(
int userData = 0 )

RequestFriendIdsResponse
List<String> getFriends()
IGetFriendIdsCb

const FriendIdList* responseStruct

FriendIdList
int numFriendIds
const char** friendIds
AGSRequestFriendIdsResponse
List<string> friendIds
Get profiles for a list of the current player's friends

getBatchFriends(
List<String> playerIds,
Object... userData)

getBatchFriends(
FriendIdList* friendIds,
IGetBatchFriendsCb* const callback,
int developerTag = 0)

RequestBatchFriends (
List<string> friendIds,
int userData = 0 )

RequestFriendsResponse
List<Player> getFriends()
IGetBatchFriendsCb

const FriendList* responseStruct

FriendList
int numFriends
AmazonGames::PlayerInfo* friends
AGSRequestBatchFriendsResponse
List<AGSPlayer> friends
Get scores for a specified leaderboard (filter on friends with FRIENDS_ALL_TIME).

getScores(
String leaderboardId,
LeaderboardFilter filter,
Object ... userData)

getScores(
char const* const leaderboardId,
AmazonGames::LeaderboardFilter filter,
ILeaderboardGetScoresCb* const callback,
int developerTag = 0)

RequestScores(
string leaderboardId,
LeaderboardScope scope,
int userData = 0 )

GetScoresResponse

List<Score> getScores()

Score
Player getPlayer()
long getScoreValue()
String getScoreString()
int getRank()
String getLeaderboard()
int getNumScores()
Leaderboard getLeaderboard()
ILeaderboardGetScoresCb

const LeaderboardScores* scoresResponse

LeaderboardScores
LeaderboardInfo leaderboardInfo
int numScores

const LeaderboardScore* scores

LeaderboardScores
LeaderboardInfo leaderboardInfo
int numScores

const LeaderboardScore* scores

LeaderboardScore
const char* playerAlias
long long scoreValue
const char* scoreString
int rank
const char* leaderboardString
AGSRequestScoresResponse
string leaderboardId
AGSLeaderboard leaderboard
LeaderboardScope scope

List<AGSScore> scores

AGSScore
AGSPlayer player
int rank
string scoreString
long scoreValue
Get percentile rankings for a specified leaderboard (filter on friends with FRIENDS_ALL_TIME).

getPercentileRanks(
String leaderboardId,
LeaderboardFilter filter,
Object ... userData)

static void getPercentileRanks(
char const* const leaderboardId,
AmazonGames::LeaderboardFilter filter,
ILeaderboardGetPercentilesCb* const callback,
int developerTag = 0)

RequestPercentileRanks(
string leaderboardId,
LeaderboardScope scope,
int userData = 0 )

GetLeaderboardPercentilesResponse
int getUserIndex()
Leaderboard getLeaderboard()

List<LeaderboardPercentileItem> getPercentileList()

LeaderboardPercentileItem
Player getPlayer()
long getPlayerScore()
int getPercentile()
ILeaderboardGetPercentilesCb

const LeaderboardPercentiles* response

LeaderboardPercentiles
LeaderboardInfo leaderboardInfo
int userIndex
int numPercentiles

const PercentileItem* percentiles

PercentileItem
const char* playerAlias
long long scoreValue
int percentile
AGSRequestPercentilesResponse
string leaderboardId
AGSLeaderboard leaderboard

List<AGSLeaderboardPercentile> percentiles

AGSLeaderboardPercentile
int percentile
long score
AGSPlayer player
int userIndex
LeaderboardScope scope
Data Objects      

Achievement

Achievement
String getId()
String getTitle()
String getDescription()
String getImageURL()
int getPointValue()
boolean isHidden()
boolean isUnlocked()
float getProgress()
int getPosition()
Date getDateUnlocked()
AchievementData
const char* id
const char* title
const char* description
const char* imageURL
int pointValue
bool isHidden
bool isUnlocked
float progress
int position
AGSAchievement
string id
string title
string description
 
int pointValue
bool isHidden
bool isUnlocked
float progress
public int position
DateTime dateUnlocked
Leaderboard
Leaderboard

String getId()

String getName()

String getDisplayText()

ScoreFormat getScoreFormat()

ScoreFormat
NUMERIC
DURATION
UNKNOWN
String getImageURL()
LeaderboardInfo
const char* leaderboardId
const char* leaderboardName
const char* displayText

int scoreFormat

No enumeration of score formats
const char* imageURL
AGSLeaderboard
string id
string name
string displayText

string scoreFormat

No enumeration of score formats
string imageUrl
Player
Player
String getAlias()
String getPlayerId()
String getAvatarUrl()
PlayerInfo
const char* alias
const char* playerId
const char* avatarUrl
AGSPlayer
readonly string alias
readonly string playerId
readonly string avatarUrl