GooglePlayGames.BasicApi.IPlayGamesClient

Defines an abstract interface for a Play Games Client.

Summary

Concrete implementations might be, for example, the client for Android or for iOS. One fundamental concept that implementors of this class must adhere to is stable authentication state. This means that once Authenticate() returns true through its callback, the user is considered to be forever after authenticated while the app is running. The implementation must make sure that this is the case for example, it must try to silently re-authenticate the user if authentication is lost or wait for the authentication process to get fixed if it is temporarily in a bad state (such as when the Activity in Android has just been brought to the foreground and the connection to the Games services hasn't yet been established). To the user of this interface, once the user is authenticated, they're forever authenticated. Unless, of course, there is an unusual permanent failure such as the underlying service dying, in which it's acceptable that API method calls will fail.

All methods can be called from the game thread. The user of this interface DOES NOT NEED to call them from the UI thread of the game. Transferring to the UI thread when necessary is a responsibility of the implementors of this interface.

CALLBACKS: all callbacks must be invoked in Unity's main thread. Implementors of this interface must guarantee that (suggestion: use PlayGamesHelperObject.RunOnGameThread(System.Action)).

Inheritance

Direct Known Subclasses:GooglePlayGames.BasicApi.DummyClient

Public functions

AskForLoadFriendsResolution(Action< UIStatus > callback)
void
Shows the appropriate platform-specific friends sharing UI.
Authenticate(Action< SignInStatus > callback)
void
Returns the result of the automatic sign-in attempt.
GetEventsClient()
Gets the events client.
GetFriends()
IUserProfile[]
GetFriendsListVisibility(bool forceReload, Action< FriendsListVisibilityStatus > callback)
void
Returns if the user has allowed permission for the game to access the friends list.
GetLastLoadFriendsStatus()
Returns the latest LoadFriendsStatus obtained from loading friends.
GetPlayerStats(Action< CommonStatusCodes, PlayerStats > callback)
void
Gets the player stats.
GetSavedGameClient()
Gets the saved game client.
GetUserDisplayName()
string
Returns a human readable name for the user, if they are logged in.
GetUserId()
string
Returns the authenticated user's ID.
GetUserImageUrl()
string
Returns the user's avatar url, if they are logged in and have an avatar.
IncrementAchievement(string achievementId, int steps, Action< bool > successOrFailureCalllback)
void
Increments the achievement with the passed identifier.
IsAuthenticated()
bool
Returns whether or not user is authenticated.
LeaderboardMaxResults()
int
Returns the max number of scores returned per call.
LoadAchievements(Action< Achievement[]> callback)
void
Loads the achievements for the current signed in user and invokes the callback.
LoadFriends(Action< bool > callback)
void
Loads friends of the authenticated user.
LoadFriends(int pageSize, bool forceReload, Action< LoadFriendsStatus > callback)
void
Loads the first page of the user's friends
LoadMoreFriends(int pageSize, Action< LoadFriendsStatus > callback)
void
Loads the friends list page
LoadMoreScores(ScorePageToken token, int rowCount, Action< LeaderboardScoreData > callback)
void
Loads the more scores for the leaderboard.
LoadScores(string leaderboardId, LeaderboardStart start, int rowCount, LeaderboardCollection collection, LeaderboardTimeSpan timeSpan, Action< LeaderboardScoreData > callback)
void
Loads the score data for the given leaderboard.
LoadUsers(string[] userIds, Action< IUserProfile[]> callback)
void
Loads the users specified.
ManuallyAuthenticate(Action< SignInStatus > callback)
void
Manually requests that your game performs sign in with Play Games Services.
RequestRecallAccessToken(Action< RecallAccess > callback)
void
Requests Recall Access to Player Games Services for the currently signed in account
RequestServerSideAccess(bool forceRefreshToken, Action< string > callback)
void
Requests server-side access to Player Games Services for the currently signed in player.
RequestServerSideAccess(bool forceRefreshToken, List< AuthScope > scopes, Action< AuthResponse > callback)
void
Requests server-side access to Play Games Services for the currently signed in player.
RevealAchievement(string achievementId, Action< bool > successOrFailureCalllback)
void
Reveals the achievement with the passed identifier.
SetStepsAtLeast(string achId, int steps, Action< bool > callback)
void
Set an achievement to have at least the given number of steps completed.
ShowAchievementsUI(Action< UIStatus > callback)
void
Shows the appropriate platform-specific achievements UI.
ShowCompareProfileWithAlternativeNameHintsUI(string otherUserId, string otherPlayerInGameName, string currentPlayerInGameName, Action< UIStatus > callback)
void
Shows the Play Games Player Profile UI for a specific user identifier.
ShowLeaderboardUI(string leaderboardId, LeaderboardTimeSpan span, Action< UIStatus > callback)
void
Shows the leaderboard UI for a specific leaderboard.
SubmitScore(string leaderboardId, long score, Action< bool > successOrFailureCalllback)
void
Submits the passed score to the passed leaderboard.
SubmitScore(string leaderboardId, long score, string metadata, Action< bool > successOrFailureCalllback)
void
Submits the score for the currently signed-in player.
UnlockAchievement(string achievementId, Action< bool > successOrFailureCalllback)
void
Unlocks the achievement with the passed identifier.

Public functions

AskForLoadFriendsResolution

void AskForLoadFriendsResolution(
  Action< UIStatus > callback
)

Shows the appropriate platform-specific friends sharing UI.

Details
Parameters
callback
The callback to invoke when complete. If null, no callback is called.

Authenticate

void Authenticate(
  Action< SignInStatus > callback
)

Returns the result of the automatic sign-in attempt.

This returns the result

Details
Parameters
callback
Callback

GetEventsClient

Events.IEventsClient GetEventsClient()

Gets the events client.

Details
Returns
The events client.

GetFriends

IUserProfile[] GetFriends()

GetFriendsListVisibility

void GetFriendsListVisibility(
  bool forceReload,
  Action< FriendsListVisibilityStatus > callback
)

Returns if the user has allowed permission for the game to access the friends list.

Details
Parameters
forceReload
If true, this call will clear any locally cached data and attempt to fetch the latest data from the server. Normally, this should be set to false to gain advantages of data caching.
callback
Callback invoked upon completion.

GetLastLoadFriendsStatus

LoadFriendsStatus GetLastLoadFriendsStatus()

Returns the latest LoadFriendsStatus obtained from loading friends.

GetPlayerStats

void GetPlayerStats(
  Action< CommonStatusCodes, PlayerStats > callback
)

Gets the player stats.

Details
Parameters
callback
Callback for response.

GetSavedGameClient

SavedGame.ISavedGameClient GetSavedGameClient()

Gets the saved game client.

Details
Returns
The saved game client.

GetUserDisplayName

string GetUserDisplayName()

Returns a human readable name for the user, if they are logged in.

Details
Returns
The user's human-readable name. null if they are not logged in

GetUserId

string GetUserId()

Returns the authenticated user's ID.

Note that this value may change if a user signs out and signs in with a different account.

Details
Returns
The user's ID, null if the user is not logged in.

GetUserImageUrl

string GetUserImageUrl()

Returns the user's avatar url, if they are logged in and have an avatar.

Details
Returns
The URL to load the avatar image. null if they are not logged in

IncrementAchievement

void IncrementAchievement(
  string achievementId,
  int steps,
  Action< bool > successOrFailureCalllback
)

Increments the achievement with the passed identifier.

If the operation succeeds, the callback will be invoked on the game thread with true. If the operation fails, the callback will be invoked with false. This operation will immediately fail if the user is not authenticated (i.e. the callback will immediately be invoked with false).

Details
Parameters
achievementId
The ID of the achievement to increment.
steps
The number of steps to increment by.
successOrFailureCalllback
Callback used to indicate whether the operation succeeded or failed.

IsAuthenticated

bool IsAuthenticated()

Returns whether or not user is authenticated.

Details
Returns
true if the user is authenticated; otherwise, false.

LeaderboardMaxResults

int LeaderboardMaxResults()

Returns the max number of scores returned per call.

Details
Returns
The max results.

LoadAchievements

void LoadAchievements(
  Action< Achievement[]> callback
)

Loads the achievements for the current signed in user and invokes the callback.

LoadFriends

void LoadFriends(
  Action< bool > callback
)

Loads friends of the authenticated user.

This loads the entire list of friends.

Details
Parameters
callback
Callback invoked when complete. bool argument indicates success.

LoadFriends

void LoadFriends(
  int pageSize,
  bool forceReload,
  Action< LoadFriendsStatus > callback
)

Loads the first page of the user's friends

Details
Parameters
pageSize
The number of entries to request for this initial page. Note that if cached data already exists, the returned buffer may contain more than this size, but it is guaranteed to contain at least this many if the collection contains enough records.
forceReload
If true, this call will clear any locally cached data and attempt to fetch the latest data from the server. This would commonly be used for something like a user-initiated refresh. Normally, this should be set to false to gain advantages of data caching.
callback
Callback invoked upon completion.

LoadMoreFriends

void LoadMoreFriends(
  int pageSize,
  Action< LoadFriendsStatus > callback
)

Loads the friends list page

Details
Parameters
pageSize
The number of entries to request for this page. Note that if cached data already exists, the returned buffer may contain more than this size, but it is guaranteed to contain at least this many if the collection contains enough records.
callback

LoadMoreScores

void LoadMoreScores(
  ScorePageToken token,
  int rowCount,
  Action< LeaderboardScoreData > callback
)

Loads the more scores for the leaderboard.

The token is accessed by calling LoadScores() with a positive row count.

Details
Parameters
token
Token for tracking the score loading.
rowCount
max number of scores to return. This can be limited by the SDK.
callback
Callback.

LoadScores

void LoadScores(
  string leaderboardId,
  LeaderboardStart start,
  int rowCount,
  LeaderboardCollection collection,
  LeaderboardTimeSpan timeSpan,
  Action< LeaderboardScoreData > callback
)

Loads the score data for the given leaderboard.

Details
Parameters
leaderboardId
Leaderboard identifier.
start
Start indicating the top scores or player centric
rowCount
max number of scores to return. non-positive indicates no rows should be returned. This causes only the summary info to be loaded. This can be limited by the SDK.
collection
leaderboard collection: public or social
timeSpan
leaderboard timespan
callback
callback with the scores, and a page token. The token can be used to load next/prev pages.

LoadUsers

void LoadUsers(
  string[] userIds,
  Action< IUserProfile[]> callback
)

Loads the users specified.

This is mainly used by the leaderboard APIs to get the information of a high scorer.

Details
Parameters
userIds
User identifiers.
callback
Callback.

ManuallyAuthenticate

void ManuallyAuthenticate(
  Action< SignInStatus > callback
)

Manually requests that your game performs sign in with Play Games Services.

Note that a sign-in attempt will be made automatically when your game's application started. For this reason most games will not need to manually request to perform sign-in unless the automatic sign-in attempt failed and your game requires access to Play Games Services.

Details
Parameters
callback

RequestRecallAccessToken

void RequestRecallAccessToken(
  Action< RecallAccess > callback
)

Requests Recall Access to Player Games Services for the currently signed in account

When requested a session id is returned that can be used by your game-server to use Recall Access APIs like LinkPerson , UnlinkPersona and get Details about Recall Tokens and corresponding personas. See https://developer.android.com/games/pgs/recall?hl=en.

Details
Parameters
callback

RequestServerSideAccess

void RequestServerSideAccess(
  bool forceRefreshToken,
  Action< string > callback
)

Requests server-side access to Player Games Services for the currently signed in player.

When requested an authorization code is returned that can be used by your game-server to exchange for an access token and conditionally a refresh token (when forceRefreshToken is true). The access token may then be used by your game-server to access the Play Games Services web APIs. This is commonly used to complete a sign-in flow by verifying the Play Games Services player id.

If forceRefreshToken is true, when exchanging the authorization code a refresh token will be returned in addition to the access token. The refresh token allows the game-server to request additional access tokens, allowing your game-server to continue accesses Play Games Services while the user is not actively playing your app.

Details
Parameters
forceRefreshToken
If true when the returned authorization code is exchanged a refresh token will be included in addition to an access token.
callback

RequestServerSideAccess

void RequestServerSideAccess(
  bool forceRefreshToken,
  List< AuthScope > scopes,
  Action< AuthResponse > callback
)

Requests server-side access to Play Games Services for the currently signed in player.

An authorization code is returned when requested. Your server can then exchange this code for an access token (and conditionally a refresh token when forceRefreshToken is true). The access token allows your server to access the Play Games Services web APIs, which is often used to complete sign-in by verifying the Play Games Services player ID.

When forceRefreshToken is true during authorization code exchange, a refresh token is provided along with the access token. This refresh token enables your server to obtain new access tokens and continue accessing Play Games Services even when the user isn't actively playing. Note that refresh tokens are only generated for players who have auto sign-in setting enabled.

Scopes represent the AuthScope values requested such as AuthScope.EMAIL, AuthScope.PROFILE, AuthScope.OPEN_ID. For new permissions, users will see a consent screen upon the first request. Granting consent (or if permissions were already granted) results in the AuthResponse listing the effectively granted AuthScope. Declining permission results in an empty list of granted AuthScope in the AuthResponse . Regardless of granted permissions, a successful request will always return the authorization code. param name="scopes">A list of AuthScope values representing the OAuth 2.0 permissions being requested, such as AuthScope.EMAIL, AuthScope.PROFILE and AuthScope.OPEN_ID.

Details
Parameters
forceRefreshToken
If true when the returned authorization code is exchanged a refresh token will be included in addition to an access token.

A Task that completes with an AuthResponse containing the OAuth 2.0 authorization code as a string and a list of the AuthScopes that were effectively granted by the user (see description for details on consent). This authorization code can be exchanged by your server for an access token (and conditionally a refresh token) that can be used to access the Play Games Services web APIs and other Google Identity APIs.

Details
Parameters
callback

RevealAchievement

void RevealAchievement(
  string achievementId,
  Action< bool > successOrFailureCalllback
)

Reveals the achievement with the passed identifier.

If the operation succeeds, the callback will be invoked on the game thread with true. If the operation fails, the callback will be invoked with false. This operation will immediately fail if the user is not authenticated (i.e. the callback will immediately be invoked with false). If the achievement is already in a revealed state, this call will succeed immediately.

Details
Parameters
achievementId
The ID of the achievement to reveal.
successOrFailureCalllback
Callback used to indicate whether the operation succeeded or failed.

SetStepsAtLeast

void SetStepsAtLeast(
  string achId,
  int steps,
  Action< bool > callback
)

Set an achievement to have at least the given number of steps completed.

Calling this method while the achievement already has more steps than the provided value is a no-op. Once the achievement reaches the maximum number of steps, the achievement is automatically unlocked, and any further mutation operations are ignored.

Details
Parameters
achId
Ach identifier.
steps
Steps.
callback
Callback.

ShowAchievementsUI

void ShowAchievementsUI(
  Action< UIStatus > callback
)

Shows the appropriate platform-specific achievements UI.

Details
Parameters
callback
The callback to invoke when complete. If null, no callback is called.

ShowCompareProfileWithAlternativeNameHintsUI

void ShowCompareProfileWithAlternativeNameHintsUI(
  string otherUserId,
  string otherPlayerInGameName,
  string currentPlayerInGameName,
  Action< UIStatus > callback
)

Shows the Play Games Player Profile UI for a specific user identifier.

Details
Parameters
otherUserId
User Identifier.
otherPlayerInGameName
The game's own display name of the player referred to by userId.
currentPlayerInGameName
The game's own display name of the current player.
callback
Callback invoked upon completion.

ShowLeaderboardUI

void ShowLeaderboardUI(
  string leaderboardId,
  LeaderboardTimeSpan span,
  Action< UIStatus > callback
)

Shows the leaderboard UI for a specific leaderboard.

If the passed ID is null, all leaderboards are displayed.

Details
Parameters
leaderboardId
The leaderboard to display. null to display all.
span
Timespan to display for the leaderboard
callback
If non-null, the callback to invoke when the leaderboard is dismissed.

SubmitScore

void SubmitScore(
  string leaderboardId,
  long score,
  Action< bool > successOrFailureCalllback
)

Submits the passed score to the passed leaderboard.

This operation will immediately fail if the user is not authenticated (i.e. the callback will immediately be invoked with false).

Details
Parameters
leaderboardId
Leaderboard identifier.
score
Score.
successOrFailureCalllback
Callback used to indicate whether the operation succeeded or failed.

SubmitScore

void SubmitScore(
  string leaderboardId,
  long score,
  string metadata,
  Action< bool > successOrFailureCalllback
)

Submits the score for the currently signed-in player.

Details
Parameters
score
Score.
leaderboardId
leaderboard id.
metadata
metadata about the score.
successOrFailureCalllback
Callback upon completion.

UnlockAchievement

void UnlockAchievement(
  string achievementId,
  Action< bool > successOrFailureCalllback
)

Unlocks the achievement with the passed identifier.

If the operation succeeds, the callback will be invoked on the game thread with true. If the operation fails, the callback will be invoked with false. This operation will immediately fail if the user is not authenticated (i.e. the callback will immediately be invoked with false). If the achievement is already unlocked, this call will succeed immediately.

Details
Parameters
achievementId
The ID of the achievement to unlock.
successOrFailureCalllback
Callback used to indicate whether the operation succeeded or failed.