415 lines
20 KiB
C#
Executable File
415 lines
20 KiB
C#
Executable File
// <copyright file="IPlayGamesClient.cs" company="Google Inc.">
|
|
// Copyright (C) 2014 Google Inc. All Rights Reserved.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
// </copyright>
|
|
|
|
#if UNITY_ANDROID
|
|
|
|
namespace GooglePlayGames.BasicApi
|
|
{
|
|
using System;
|
|
using UnityEngine.SocialPlatforms;
|
|
|
|
/// <summary>
|
|
/// Defines an abstract interface for a Play Games Client.
|
|
/// </summary>
|
|
/// <remarks>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.
|
|
///
|
|
/// <para>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.</para>
|
|
///
|
|
/// <para>CALLBACKS: all callbacks must be invoked in Unity's main thread.
|
|
/// Implementors of this interface must guarantee that (suggestion: use
|
|
/// <see cref="PlayGamesHelperObject.RunOnGameThread(System.Action)"/>).</para>
|
|
/// </remarks>
|
|
public interface IPlayGamesClient
|
|
{
|
|
/// <summary>
|
|
/// Starts the authentication process.
|
|
/// </summary>
|
|
/// <remarks>If silent == true, no UIs will be shown
|
|
/// (if UIs are needed, it will fail rather than show them). If silent == false,
|
|
/// this may show UIs, consent dialogs, etc.
|
|
/// At the end of the process, callback will be invoked to notify of the result.
|
|
/// Once the callback returns true, the user is considered to be authenticated
|
|
/// forever after.
|
|
/// </remarks>
|
|
/// <param name="silent">If set to <c>true</c> silent.</param>
|
|
/// <param name="callback">Callback</param>
|
|
void Authenticate(bool silent, Action<SignInStatus> callback);
|
|
|
|
/// <summary>
|
|
/// Returns whether or not user is authenticated.
|
|
/// </summary>
|
|
/// <returns><c>true</c> if the user is authenticated; otherwise, <c>false</c>.</returns>
|
|
bool IsAuthenticated();
|
|
|
|
/// <summary>
|
|
/// Signs the user out.
|
|
/// </summary>
|
|
void SignOut();
|
|
|
|
/// <summary>
|
|
/// Returns the authenticated user's ID. Note that this value may change if a user signs
|
|
/// on and signs in with a different account.
|
|
/// </summary>
|
|
/// <returns>The user's ID, <code>null</code> if the user is not logged in.</returns>
|
|
string GetUserId();
|
|
|
|
/// <summary>
|
|
/// Loads friends of the authenticated user. This loads the entire list of friends.
|
|
/// </summary>
|
|
/// <param name="callback">Callback invoked when complete. bool argument
|
|
/// indicates success.</param>
|
|
void LoadFriends(Action<bool> callback);
|
|
|
|
/// <summary>
|
|
/// Returns a human readable name for the user, if they are logged in.
|
|
/// </summary>
|
|
/// <returns>The user's human-readable name. <code>null</code> if they are not logged
|
|
/// in</returns>
|
|
string GetUserDisplayName();
|
|
|
|
/// <summary>
|
|
/// Returns an id token, which can be verified server side, if they are logged in.
|
|
/// </summary>
|
|
string GetIdToken();
|
|
|
|
/// <summary>
|
|
/// The server auth code for this client.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Note: This function is currently only implemented for Android.
|
|
/// </remarks>
|
|
string GetServerAuthCode();
|
|
|
|
/// <summary>
|
|
/// Gets another server auth code.
|
|
/// </summary>
|
|
/// <remarks>This method should be called after authenticating, and exchanging
|
|
/// the initial server auth code for a token. This is implemented by signing in
|
|
/// silently, which if successful returns almost immediately and with a new
|
|
/// server auth code.
|
|
/// </remarks>
|
|
/// <param name="reAuthenticateIfNeeded">Calls Authenticate if needed when
|
|
/// retrieving another auth code. </param>
|
|
/// <param name="callback">Callback returning the auth code, or null if there
|
|
/// was a problem. NOTE: This callback can be called immediately.</param>
|
|
void GetAnotherServerAuthCode(bool reAuthenticateIfNeeded,
|
|
Action<string> callback);
|
|
|
|
/// <summary>
|
|
/// Gets the user's email.
|
|
/// </summary>
|
|
/// <remarks>The email address returned is selected by the user from the accounts present
|
|
/// on the device. There is no guarantee this uniquely identifies the player.
|
|
/// For unique identification use the id property of the local player.
|
|
/// The user can also choose to not select any email address, meaning it is not
|
|
/// available.
|
|
/// </remarks>
|
|
/// <returns>The user email or null if not authenticated or the permission is
|
|
/// not available.</returns>
|
|
string GetUserEmail();
|
|
|
|
/// <summary>
|
|
/// Returns the user's avatar url, if they are logged in and have an avatar.
|
|
/// </summary>
|
|
/// <returns>The URL to load the avatar image. <code>null</code> if they are not logged
|
|
/// in</returns>
|
|
string GetUserImageUrl();
|
|
|
|
/// <summary>Gets the player stats.</summary>
|
|
/// <param name="callback">Callback for response.</param>
|
|
void GetPlayerStats(Action<CommonStatusCodes, PlayerStats> callback);
|
|
|
|
/// <summary>
|
|
/// Loads the users specified. This is mainly used by the leaderboard
|
|
/// APIs to get the information of a high scorer.
|
|
/// </summary>
|
|
/// <param name="userIds">User identifiers.</param>
|
|
/// <param name="callback">Callback.</param>
|
|
void LoadUsers(string[] userIds, Action<IUserProfile[]> callback);
|
|
|
|
/// <summary>
|
|
/// Loads the achievements for the current signed in user and invokes
|
|
/// the callback.
|
|
/// </summary>
|
|
void LoadAchievements(Action<Achievement[]> callback);
|
|
|
|
/// <summary>
|
|
/// Unlocks the achievement with the passed identifier.
|
|
/// </summary>
|
|
/// <remarks>If the operation succeeds, the callback
|
|
/// will be invoked on the game thread with <code>true</code>. If the operation fails, the
|
|
/// callback will be invoked with <code>false</code>. This operation will immediately fail if
|
|
/// the user is not authenticated (i.e. the callback will immediately be invoked with
|
|
/// <code>false</code>). If the achievement is already unlocked, this call will
|
|
/// succeed immediately.
|
|
/// </remarks>
|
|
/// <param name="achievementId">The ID of the achievement to unlock.</param>
|
|
/// <param name="successOrFailureCalllback">Callback used to indicate whether the operation
|
|
/// succeeded or failed.</param>
|
|
void UnlockAchievement(string achievementId, Action<bool> successOrFailureCalllback);
|
|
|
|
/// <summary>
|
|
/// Reveals the achievement with the passed identifier.
|
|
/// </summary>
|
|
/// <remarks>If the operation succeeds, the callback
|
|
/// will be invoked on the game thread with <code>true</code>. If the operation fails, the
|
|
/// callback will be invoked with <code>false</code>. This operation will immediately fail if
|
|
/// the user is not authenticated (i.e. the callback will immediately be invoked with
|
|
/// <code>false</code>). If the achievement is already in a revealed state, this call will
|
|
/// succeed immediately.
|
|
/// </remarks>
|
|
/// <param name="achievementId">The ID of the achievement to reveal.</param>
|
|
/// <param name="successOrFailureCalllback">Callback used to indicate whether the operation
|
|
/// succeeded or failed.</param>
|
|
void RevealAchievement(string achievementId, Action<bool> successOrFailureCalllback);
|
|
|
|
/// <summary>
|
|
/// Increments the achievement with the passed identifier.
|
|
/// </summary>
|
|
/// <remarks>If the operation succeeds, the
|
|
/// callback will be invoked on the game thread with <code>true</code>. If the operation fails,
|
|
/// the callback will be invoked with <code>false</code>. This operation will immediately fail
|
|
/// if the user is not authenticated (i.e. the callback will immediately be invoked with
|
|
/// <code>false</code>).
|
|
/// </remarks>
|
|
/// <param name="achievementId">The ID of the achievement to increment.</param>
|
|
/// <param name="steps">The number of steps to increment by.</param>
|
|
/// <param name="successOrFailureCalllback">Callback used to indicate whether the operation
|
|
/// succeeded or failed.</param>
|
|
void IncrementAchievement(string achievementId, int steps,
|
|
Action<bool> successOrFailureCalllback);
|
|
|
|
/// <summary>
|
|
/// Set an achievement to have at least the given number of steps completed.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// 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.
|
|
/// </remarks>
|
|
/// <param name="achId">Ach identifier.</param>
|
|
/// <param name="steps">Steps.</param>
|
|
/// <param name="callback">Callback.</param>
|
|
void SetStepsAtLeast(string achId, int steps, Action<bool> callback);
|
|
|
|
/// <summary>
|
|
/// Shows the appropriate platform-specific achievements UI.
|
|
/// <param name="callback">The callback to invoke when complete. If null,
|
|
/// no callback is called. </param>
|
|
/// </summary>
|
|
void ShowAchievementsUI(Action<UIStatus> callback);
|
|
|
|
/// <summary>
|
|
/// Shows the appropriate platform-specific friends sharing UI.
|
|
/// <param name="callback">The callback to invoke when complete. If null,
|
|
/// no callback is called. </param>
|
|
/// </summary>
|
|
void AskForLoadFriendsResolution(Action<UIStatus> callback);
|
|
|
|
/// <summary>
|
|
/// Returns the latest LoadFriendsStatus obtained from loading friends.
|
|
/// </summary>
|
|
LoadFriendsStatus GetLastLoadFriendsStatus();
|
|
|
|
/// <summary>
|
|
/// Shows the Play Games Player Profile UI for a specific user identifier.
|
|
/// </summary>
|
|
/// <param name="otherUserId">User Identifier.</param>
|
|
/// <param name="otherPlayerInGameName">
|
|
/// The game's own display name of the player referred to by userId.
|
|
/// </param>
|
|
/// <param name="currentPlayerInGameName">
|
|
/// The game's own display name of the current player.
|
|
/// </param>
|
|
/// <param name="callback">Callback invoked upon completion.</param>
|
|
void ShowCompareProfileWithAlternativeNameHintsUI(
|
|
string otherUserId, string otherPlayerInGameName, string currentPlayerInGameName,
|
|
Action<UIStatus> callback);
|
|
|
|
/// <summary>
|
|
/// Returns if the user has allowed permission for the game to access the friends list.
|
|
/// </summary>
|
|
/// <param name="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 {@code
|
|
/// false} to gain advantages of data caching.</param> <param name="callback">Callback
|
|
/// invoked upon completion.</param>
|
|
void GetFriendsListVisibility(bool forceReload,
|
|
Action<FriendsListVisibilityStatus> callback);
|
|
|
|
/// <summary>
|
|
/// Loads the first page of the user's friends
|
|
/// </summary>
|
|
/// <param name="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.
|
|
/// </param>
|
|
/// <param name="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 {@code false} to gain advantages
|
|
/// of data caching.</param>
|
|
/// <param name="callback">Callback invoked upon completion.</param>
|
|
void LoadFriends(int pageSize, bool forceReload, Action<LoadFriendsStatus> callback);
|
|
|
|
/// <summary>
|
|
/// Loads the friends list page
|
|
/// </summary>
|
|
/// <param name="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.
|
|
/// </param>
|
|
/// <param name="callback"></param>
|
|
void LoadMoreFriends(int pageSize, Action<LoadFriendsStatus> callback);
|
|
|
|
/// <summary>
|
|
/// Shows the leaderboard UI for a specific leaderboard.
|
|
/// </summary>
|
|
/// <remarks>If the passed ID is <code>null</code>, all leaderboards are displayed.
|
|
/// </remarks>
|
|
/// <param name="leaderboardId">The leaderboard to display. <code>null</code> to display
|
|
/// all.</param>
|
|
/// <param name="span">Timespan to display for the leaderboard</param>
|
|
/// <param name="callback">If non-null, the callback to invoke when the
|
|
/// leaderboard is dismissed.
|
|
/// </param>
|
|
void ShowLeaderboardUI(string leaderboardId,
|
|
LeaderboardTimeSpan span,
|
|
Action<UIStatus> callback);
|
|
|
|
/// <summary>
|
|
/// Loads the score data for the given leaderboard.
|
|
/// </summary>
|
|
/// <param name="leaderboardId">Leaderboard identifier.</param>
|
|
/// <param name="start">Start indicating the top scores or player centric</param>
|
|
/// <param name="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.</param>
|
|
/// <param name="collection">leaderboard collection: public or social</param>
|
|
/// <param name="timeSpan">leaderboard timespan</param>
|
|
/// <param name="callback">callback with the scores, and a page token.
|
|
/// The token can be used to load next/prev pages.</param>
|
|
void LoadScores(string leaderboardId, LeaderboardStart start,
|
|
int rowCount, LeaderboardCollection collection,
|
|
LeaderboardTimeSpan timeSpan,
|
|
Action<LeaderboardScoreData> callback);
|
|
|
|
/// <summary>
|
|
/// Loads the more scores for the leaderboard.
|
|
/// </summary>
|
|
/// <remarks>The token is accessed
|
|
/// by calling LoadScores() with a positive row count.
|
|
/// </remarks>
|
|
/// <param name="token">Token for tracking the score loading.</param>
|
|
/// <param name="rowCount">max number of scores to return.
|
|
/// This can be limited by the SDK.</param>
|
|
/// <param name="callback">Callback.</param>
|
|
void LoadMoreScores(ScorePageToken token, int rowCount,
|
|
Action<LeaderboardScoreData> callback);
|
|
|
|
/// <summary>
|
|
/// Returns the max number of scores returned per call.
|
|
/// </summary>
|
|
/// <returns>The max results.</returns>
|
|
int LeaderboardMaxResults();
|
|
|
|
/// <summary>
|
|
/// Submits the passed score to the passed leaderboard.
|
|
/// </summary>
|
|
/// <remarks>This operation will immediately fail
|
|
/// if the user is not authenticated (i.e. the callback will immediately be invoked with
|
|
/// <code>false</code>).
|
|
/// </remarks>
|
|
/// <param name="leaderboardId">Leaderboard identifier.</param>
|
|
/// <param name="score">Score.</param>
|
|
/// <param name="successOrFailureCalllback">Callback used to indicate whether the operation
|
|
/// succeeded or failed.</param>
|
|
void SubmitScore(string leaderboardId, long score,
|
|
Action<bool> successOrFailureCalllback);
|
|
|
|
/// <summary>
|
|
/// Submits the score for the currently signed-in player.
|
|
/// </summary>
|
|
/// <param name="score">Score.</param>
|
|
/// <param name="leaderboardId">leaderboard id.</param>
|
|
/// <param name="metadata">metadata about the score.</param>
|
|
/// <param name="successOrFailureCalllback">Callback upon completion.</param>
|
|
void SubmitScore(string leaderboardId, long score, string metadata,
|
|
Action<bool> successOrFailureCalllback);
|
|
|
|
/// <summary>
|
|
/// Asks user to give permissions for the given scopes.
|
|
/// </summary>
|
|
/// <param name="scopes">list of scopes to ask permission for</param>
|
|
/// <param name="callback">Callback used to indicate the outcome of the operation.</param>
|
|
void RequestPermissions(string[] scopes, Action<SignInStatus> callback);
|
|
|
|
/// <summary>
|
|
/// Returns whether or not user has given permissions for given scopes
|
|
/// </summary>
|
|
/// <seealso cref="GooglePlayGames.BasicApi.IPlayGamesClient.HasPermissions"/>
|
|
/// <param name="scopes">list of scopes</param>
|
|
/// <returns><c>true</c>, if given, <c>false</c> otherwise.</returns>
|
|
bool HasPermissions(string[] scopes);
|
|
|
|
/// <summary>
|
|
/// Gets the saved game client.
|
|
/// </summary>
|
|
/// <returns>The saved game client.</returns>
|
|
SavedGame.ISavedGameClient GetSavedGameClient();
|
|
|
|
/// <summary>
|
|
/// Gets the events client.
|
|
/// </summary>
|
|
/// <returns>The events client.</returns>
|
|
Events.IEventsClient GetEventsClient();
|
|
|
|
/// <summary>
|
|
/// Gets the video client.
|
|
/// </summary>
|
|
/// <returns>The video client.</returns>
|
|
Video.IVideoClient GetVideoClient();
|
|
|
|
IUserProfile[] GetFriends();
|
|
|
|
/// <summary>
|
|
/// Sets the gravity for popups (Android only).
|
|
/// </summary>
|
|
/// <remarks>This can only be called after authentication. It affects
|
|
/// popups for achievements and other game services elements.</remarks>
|
|
/// <param name="gravity">Gravity for the popup.</param>
|
|
void SetGravityForPopups(Gravity gravity);
|
|
}
|
|
}
|
|
#endif
|