Friends

The Friends APIs enable players to find their friends in your game to enhance social engagement. You can use these APIs to help players find their friends in your game, compare scores with their friends on leaderboards, and to help a player identify another player with an in-game profile popup. This popup shows a nickname that the current player has given to their friend.

Import friends

Basics

These APIs allow you to perform the following actions:

  • Load friends: You can check if the player has allowed the game to access Friends list information. If access is granted, you can get a list of Player objects corresponding to the friends of the signed-in player.
  • Launch a view of another player’s Play Games profile: You can open up this view to show the name given to the other player by the signed-in player. This view also offers friendship management controls and won't take the player out of your game.
  • Provide user controls: The user has controls to manage how their Play Games profile is visible to friends and how their friends list is visible to games. For friends list access, the user can choose to automatically grant access for all games or they can choose to individually approve access for each game. Consequently, when loading the friends list, the result may be a callback to display a request for access.

Import friends list

For games that already have a social system and a knowledge of Play Games gamer IDs, you can import the list of Play Games friends to augment the existing friends list in your game. If you store any relationships from Play Games, you must regularly check the friends list to ensure that the relationships, and consent to use them, are still valid.

When using the friends list from a backend server, load it securely using the REST API rather than passing the result of the Android API. Make sure to use the player ID returned by players.get(me) in the REST API for the currently signed-in player, as this will be consistent with the ID seen by other players.

If the augmented friends list is not stored (but just used at the time of viewing), then no additional work is needed.

View another player's profile

You can allow your signed-in player to view another player's Play Games profile. This allows the signed-in player to see the name they have given the other player and whether or not they are already friends, giving them added context about the relationship. If the players are not yet friends, the signed-in player will see friendship management controls on the profile view. When friendships are created from within the game, the default names for the two players are their in-game names (if you provide one). The name of the game where the friendship was initiated is also shown.

View another player's profile

Social leaderboards

The Friends APIs can also be used for leaderboards. Use this feature to show the ranking of the current player among their Play Games friends. Note that this only applies to users who have chosen to share this information with your application, and if the users are friends in Play Games. To support this feature, the game exposes a control to the user. This control uses the collection argument to select the social view of the leaderboard. To learn more, see the section on public and social leaderboards.

Friends in a leaderboard

If you implement the social leaderboards collection, the call to load the leaderboard scores may return a consent-required resolution exception similar to that from loadFriends(). If you implement the default Play Games-provided UI (for example, getLeaderboardIntent()), then this is handled for you automatically.

Next steps

Before you start to use the Friends APIs, do the following: