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()`	`Events.IEventsClient` 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()`	`LoadFriendsStatus` Returns the latest LoadFriendsStatus obtained from loading friends.
`GetPlayerStats(Action< CommonStatusCodes, PlayerStats > callback)`	`void` Gets the player stats.
`GetSavedGameClient()`	`SavedGame.ISavedGameClient` 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.

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.

Details

Parameters

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