במסמך הזה נסביר איך להעביר משחקים קיימים מ-games v1 SDK ל-games v2 SDK.
לפני שמתחילים
אתם יכולים להשתמש בכל סביבת פיתוח משולבת (IDE) מועדפת, כמו Android Studio, כדי להעביר את המשחק. לפני שמעבירים את המשחקים לגרסה 2:
- הורדה והתקנה של Android Studio
- במשחק צריך להשתמש ב-SDK של שירותי המשחקים בגרסה 1
מעדכנים את יחסי התלות
בקובץ
build.gradle
של המודול, מחפשים את השורה הזו ביחסי התלות ברמת המודול.implementation "com.google.android.gms:play-services-games-v1:+"
מחליפים אותו בקוד הבא:
implementation "com.google.android.gms:play-services-games-v2:version"
מחליפים את version בגרסה האחרונה של ה-SDK של המשחקים.
אחרי שמעדכנים את יחסי התלות, חשוב לבצע את כל השלבים שמפורטים במסמך הזה.
העברה מכניסה לחשבון Google שהוצאה משימוש
מחליפים את הכיתה GoogleSignInClient
בכיתה GamesSignInClient
.
Java
מאתרים את הקבצים בכיתה GoogleSignInClient
.
import com.google.android.gms.auth.api.signin.GoogleSignIn;
import com.google.android.gms.auth.api.signin.GoogleSignInClient;
import com.google.android.gms.auth.api.signin.GoogleSignInOptions;
// ... existing code
@Override
public void onCreate(@Nullable Bundle bundle) {
super.onCreate(bundle);
// ... existing code
val signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN
// Client used to sign in to Google services
GoogleSignInClient googleSignInClient =
GoogleSignIn.getClient(this, signInOptions);
}
ומעדכנים אותו כך:
import com.google.android.gms.games.PlayGamesSdk;
import com.google.android.gms.games.PlayGames;
import com.google.android.gms.games.GamesSignInClient;
// ... existing code
@Override
public void onCreate(){
super.onCreate();
// Client used to sign in to Google services
GamesSignInClient gamesSignInClient =
PlayGames.getGamesSignInClient(getActivity());
}
Kotlin
מאתרים את הקבצים בכיתה GoogleSignInClient
.
import com.google.android.gms.auth.api.signin.GoogleSignIn
import com.google.android.gms.auth.api.signin.GoogleSignInClient
import com.google.android.gms.auth.api.signin.GoogleSignInOptions
// ... existing code
val signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN
// ... existing code
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val googleSignInClient: GoogleSignInClient =
GoogleSignIn.getClient(this, signInOptions)
}
ומעדכנים אותו כך:
import com.google.android.gms.games.PlayGames
import com.google.android.gms.games.PlayGamesSdk
import com.google.android.gms.games.GamesSignInClient
// ... existing code
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
PlayGamesSdk.initialize(this)
// client used to sign in to Google services
val gamesSignInClient: GamesSignInClient =
PlayGames.getGamesSignInClient(this)
}
מעדכנים את הקוד GoogleSignIn
אין תמיכה ב-API ובהיקפי הגישה של GoogleSignIn
ב-SDK למשחקים בגרסה 2. מחליפים את קוד ה-API GoogleSignIn
של היקפי ההרשאות של OAuth 2.0 ב-API GamesSignInClient
, כפי שמתואר בדוגמה הבאה:
Java
מאתרים את הקבצים עם הכיתה וההיקפים של GoogleSignIn
.
// Request code used when invoking an external activity.
private static final int RC_SIGN_IN = 9001;
private boolean isSignedIn() {
GoogleSignInAccount account = GoogleSignIn.getLastSignedInAccount(this);
GoogleSignInOptions signInOptions =
GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
return GoogleSignIn.hasPermissions(account, signInOptions.getScopeArray());
}
private void signInSilently() {
GoogleSignInOptions signInOptions =
GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOptions);
signInClient
.silentSignIn()
.addOnCompleteListener(
this,
task -> {
if (task.isSuccessful()) {
// The signed-in account is stored in the task's result.
GoogleSignInAccount signedInAccount = task.getResult();
showSignInPopup();
} else {
// Perform interactive sign in.
startSignInIntent();
}
});
}
private void startSignInIntent() {
GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
Intent intent = signInClient.getSignInIntent();
startActivityForResult(intent, RC_SIGN_IN);
}
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (requestCode == RC_SIGN_IN) {
GoogleSignInResult result =
Auth.GoogleSignInApi.getSignInResultFromIntent(data);
if (result.isSuccess()) {
// The signed-in account is stored in the result.
GoogleSignInAccount signedInAccount = result.getSignInAccount();
showSignInPopup();
} else {
String message = result.getStatus().getStatusMessage();
if (message == null || message.isEmpty()) {
message = getString(R.string.signin_other_error);
}
new AlertDialog.Builder(this).setMessage(message)
.setNeutralButton(android.R.string.ok, null).show();
}
}
}
private void showSignInPopup() {
Games.getGamesClient(requireContext(), signedInAccount)
.setViewForPopups(contentView)
.addOnCompleteListener(
task -> {
if (task.isSuccessful()) {
logger.atInfo().log("SignIn successful");
} else {
logger.atInfo().log("SignIn failed");
}
});
}
ומעדכנים אותו כך:
private void signInSilently() {
gamesSignInClient.isAuthenticated().addOnCompleteListener(isAuthenticatedTask -> {
boolean isAuthenticated =
(isAuthenticatedTask.isSuccessful() &&
isAuthenticatedTask.getResult().isAuthenticated());
if (isAuthenticated) {
// Continue with Play Games Services
} else {
// If authentication fails, either disable Play Games Services
// integration or
// display a login button to prompt players to sign in.
// Use`gamesSignInClient.signIn()` when the login button is clicked.
}
});
}
@Override
protected void onResume() {
super.onResume();
// When the activity is inactive, the signed-in user's state can change;
// therefore, silently sign in when the app resumes.
signInSilently();
}
Kotlin
מאתרים את הקבצים עם הכיתה וההיקפים של GoogleSignIn
.
// Request codes we use when invoking an external activity.
private val RC_SIGN_IN = 9001
// ... existing code
private fun isSignedIn(): Boolean {
val account = GoogleSignIn.getLastSignedInAccount(this)
val signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN
return GoogleSignIn.hasPermissions(account, *signInOptions.scopeArray)
}
private fun signInSilently() {
val signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN
val signInClient = GoogleSignIn.getClient(this, signInOptions)
signInClient.silentSignIn().addOnCompleteListener(this) { task ->
if (task.isSuccessful) {
// The signed-in account is stored in the task's result.
val signedInAccount = task.result
// Pass the account to showSignInPopup.
showSignInPopup(signedInAccount)
} else {
// Perform interactive sign in.
startSignInIntent()
}
}
}
private fun startSignInIntent() {
val signInClient = GoogleSignIn.getClient(this, GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
val intent = signInClient.signInIntent
startActivityForResult(intent, RC_SIGN_IN)
}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == RC_SIGN_IN) {
val result = Auth.GoogleSignInApi.getSignInResultFromIntent(data)
if (result.isSuccess) {
// The signed-in account is stored in the result.
val signedInAccount = result.signInAccount
showSignInPopup(signedInAccount) // Pass the account to showSignInPopup.
} else {
var message = result.status.statusMessage
if (message == null || message.isEmpty()) {
message = getString(R.string.signin_other_error)
}
AlertDialog.Builder(this)
.setMessage(message)
.setNeutralButton(android.R.string.ok, null)
.show()
}
}
}
private fun showSignInPopup(signedInAccount: GoogleSignInAccount) {
// Add signedInAccount parameter.
Games.getGamesClient(this, signedInAccount)
.setViewForPopups(contentView) // Assuming contentView is defined.
.addOnCompleteListener { task ->
if (task.isSuccessful) {
logger.atInfo().log("SignIn successful")
} else {
logger.atInfo().log("SignIn failed")
}
}
}
ומעדכנים אותו כך:
private fun signInSilently() {
gamesSignInClient.isAuthenticated.addOnCompleteListener { isAuthenticatedTask ->
val isAuthenticated = isAuthenticatedTask.isSuccessful &&
isAuthenticatedTask.result.isAuthenticated
if (isAuthenticated) {
// Continue with Play Games Services
} else {
// To handle a user who is not signed in, either disable Play Games Services integration
// or display a login button. Selecting this button calls `gamesSignInClient.signIn()`.
}
}
}
override fun onResume() {
super.onResume()
// Since the state of the signed in user can change when the activity is
// not active it is recommended to try and sign in silently from when the
// app resumes.
signInSilently()
}
מוסיפים את הקוד GamesSignInClient
אם השחקן הצליח להיכנס לחשבון, תוכלו להסיר מהמשחק את הלחצן לכניסה ל-Play Games Services. אם המשתמש בוחר לא להיכנס לחשבון כשהמשחק מופעל, ממשיכים להציג לחצן עם הסמל של שירותי המשחקים של Play, ומתחילים את תהליך הכניסה באמצעות GamesSignInClient.signIn()
.
Java
private void startSignInIntent() {
gamesSignInClient
.signIn()
.addOnCompleteListener( task -> {
if (task.isSuccessful() && task.getResult().isAuthenticated()) {
// sign in successful
} else {
// sign in failed
}
});
}
Kotlin
private fun startSignInIntent() {
gamesSignInClient
.signIn()
.addOnCompleteListener { task ->
if (task.isSuccessful && task.result.isAuthenticated) {
// sign in successful
} else {
// sign in failed
}
}
}
הסרת קוד היציאה
מסירים את הקוד של GoogleSignInClient.signOut
.
מסירים את הקוד שמוצג בדוגמה הבאה:
Java
// ... existing code
private void signOut() {
GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
signInClient.signOut().addOnCompleteListener(this,
new OnCompleteListener() {
@Override
public void onComplete(@NonNull Task task) {
// At this point, the user is signed out.
}
});
}
Kotlin
// ... existing code
private fun signOut() {
val signInClient = GoogleSignIn.getClient(this, GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
signInClient.signOut().addOnCompleteListener(this) {
// At this point, the user is signed out.
}
}
בדיקה שהכניסה האוטומטית בוצעה בהצלחה
מוסיפים את הקוד הבא כדי לבדוק אם נכנסתם לחשבון באופן אוטומטי, ומוסיפים את הלוגיקה בהתאמה אישית אם היא זמינה.
Java
private void checkIfAutomaticallySignedIn() {
gamesSignInClient.isAuthenticated().addOnCompleteListener(isAuthenticatedTask -> {
boolean isAuthenticated =
(isAuthenticatedTask.isSuccessful() &&
isAuthenticatedTask.getResult().isAuthenticated());
if (isAuthenticated) {
// Continue with Play Games Services
// If your game requires specific actions upon successful sign-in,
// you can add your custom logic here.
// For example, fetching player data or updating UI elements.
} else {
// Disable your integration with Play Games Services or show a
// login button to ask players to sign-in. Clicking it should
// call GamesSignInClient.signIn().
}
});
}
Kotlin
private void checkIfAutomaticallySignedIn() {
gamesSignInClient.isAuthenticated()
.addOnCompleteListener { task ->
val isAuthenticated = task.isSuccessful && task.result?.isAuthenticated ?: false
if (isAuthenticated) {
// Continue with Play Games Services
} else {
// Disable your integration or show a login button
}
}
}
עדכון השמות והשיטות של כיתות הלקוח
כשעוברים לגרסה games v2, השיטות לקבלת שמות של כיתות לקוח שונות.
משתמשים ב-methods המתאימים של PlayGames.getxxxClient()
במקום ב-methods של Games.getxxxClient()
.
לדוגמה, עבור LeaderboardsClient
צריך להשתמש ב-PlayGames.getLeaderboardsClient()
במקום בשיטה Games.getLeaderboardsClient()
.
Java
מאתרים את הקוד של LeaderboardsClient
.
import com.google.android.gms.games.LeaderboardsClient;
import com.google.android.gms.games.Games;
@Override
public void onCreate(@Nullable Bundle bundle) {
super.onCreate(bundle);
// Get the leaderboards client using Play Games services.
LeaderboardsClient leaderboardsClient = Games.getLeaderboardsClient(this,
GoogleSignIn.getLastSignedInAccount(this));
}
ומעדכנים אותו כך:
import com.google.android.gms.games.LeaderboardsClient;
import com.google.android.gms.games.PlayGames;
@Override
public void onCreate(@Nullable Bundle bundle) {
super.onCreate(bundle);
// Get the leaderboards client using Play Games services.
LeaderboardsClient leaderboardsClient = PlayGames.getLeaderboardsClient(getActivity());
}
Kotlin
מאתרים את הקוד של LeaderboardsClient
.
import com.google.android.gms.games.LeaderboardsClient
import com.google.android.gms.games.Games
// Initialize the variables.
private lateinit var leaderboardsClient: LeaderboardsClient
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
leaderboardsClient = Games.getLeaderboardsClient(this,
GoogleSignIn.getLastSignedInAccount(this))
}
ומעדכנים אותו כך:
import com.google.android.gms.games.LeaderboardsClient
import com.google.android.gms.games.PlayGames
// Initialize the variables.
private lateinit var leaderboardsClient: LeaderboardsClient
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
leaderboardsClient = PlayGames.getLeaderboardsClient(this)
}
באופן דומה, משתמשים בשיטות התואמות ללקוחות הבאים:
AchievementsClient
, EventsClient
, GamesSignInClient
,
PlayerStatsClient
, RecallClient
, SnapshotsClient
או PlayersClient
.
עדכון של כיתות הגישה בצד השרת
כדי לבקש אסימון גישה בצד השרת, משתמשים ב-method GamesSignInClient.requestServerSideAccess()
במקום ב-method GoogleSignInAccount.getServerAuthCode()
.
בדוגמה הבאה מוסבר איך לבקש אסימון גישה בצד השרת.
Java
מאתרים את הקוד של הכיתה GoogleSignInOptions
.
private static final int RC_SIGN_IN = 9001;
private GoogleSignInClient googleSignInClient;
private void startSignInForAuthCode() {
/** Client ID for your backend server. */
String webClientId = getString(R.string.webclient_id);
GoogleSignInOptions signInOption = new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
.requestServerAuthCode(webClientId)
.build();
GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOption);
Intent intent = signInClient.getSignInIntent();
startActivityForResult(intent, RC_SIGN_IN);
}
/** Auth code to send to backend server */
private String mServerAuthCode;
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (requestCode == RC_SIGN_IN) {
GoogleSignInResult result = Auth.GoogleSignInApi.getSignInResultFromIntent(data);
if (result.isSuccess()) {
mServerAuthCode = result.getSignInAccount().getServerAuthCode();
} else {
String message = result.getStatus().getStatusMessage();
if (message == null || message.isEmpty()) {
message = getString(R.string.signin_other_error);
}
new AlertDialog.Builder(this).setMessage(message)
.setNeutralButton(android.R.string.ok, null).show();
}
}
}
ומעדכנים אותו כך:
private void startRequestServerSideAccess() {
GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(this);
gamesSignInClient
.requestServerSideAccess(OAUTH_2_WEB_CLIENT_ID, /* forceRefreshToken= */ false)
.addOnCompleteListener(task -> {
if (task.isSuccessful()) {
String serverAuthToken = task.getResult();
// Send authentication code to the backend game server.
// Exchange for an access token.
// Verify the player with Play Games Services REST APIs.
} else {
// Authentication code retrieval failed.
}
});
}
Kotlin
מאתרים את הקוד של הכיתה GoogleSignInOptions
.
// ... existing code
private val RC_SIGN_IN = 9001
private lateinit var googleSignInClient: GoogleSignInClient
// Auth code to send to backend server.
private var mServerAuthCode: String? = null
private fun startSignInForAuthCode() {
// Client ID for your backend server.
val webClientId = getString(R.string.webclient_id)
val signInOption = GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
.requestServerAuthCode(webClientId)
.build()
googleSignInClient = GoogleSignIn.getClient(this, signInOption)
val intent = googleSignInClient.signInIntent
startActivityForResult(intent, RC_SIGN_IN)
}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == RC_SIGN_IN) {
val result = Auth.GoogleSignInApi.getSignInResultFromIntent(data)
if (result.isSuccess) {
mServerAuthCode = result.signInAccount.serverAuthCode
} else {
var message = result.status.statusMessage
if (message == null || message.isEmpty()) {
message = getString(R.string.signin_other_error)
}
AlertDialog.Builder(this).setMessage(message)
.setNeutralButton(android.R.string.ok, null).show()
}
}
}
ומעדכנים אותו כך:
private void startRequestServerSideAccess() {
GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(this);
gamesSignInClient
.requestServerSideAccess(OAUTH_2_WEB_CLIENT_ID, /* forceRefreshToken= */ false)
.addOnCompleteListener(task -> {
if (task.isSuccessful()) {
String serverAuthToken = task.getResult();
// Send authentication code to the backend game server.
// Exchange for an access token.
// Verify the player with Play Games Services REST APIs.
} else {
// Authentication code retrieval failed.
}
});
}
מעבר מ-GoogleApiClient
בשילובים קיימים ישנים יותר, יכול להיות שהמשחק שלכם תלוי בגרסה GoogleApiClient
של ממשק ה-API של ה-SDK של Play Games Services. האפשרות הזו הווצאה משימוש בסוף שנת 2017 והוחלפה בלקוחות 'ללא חיבור'. כדי להעביר את הקוד, אפשר להחליף את הכיתה GoogleApiClient
ברכיב מקביל ללא חיבור.
לפניכם מיפוי של כיתות נפוצות:
games v2
// Replace com.google.android.gms.games.achievement.Achievements
com.google.android.gms.games.AchievementsClient
// Replace com.google.android.gms.games.leaderboard.Leaderboard
com.google.android.gms.games.LeaderboardsClient
// Replace com.google.android.gms.games.snapshot.Snapshots
com.google.android.gms.games.SnapshotsClient
// Replace com.google.android.gms.games.stats.PlayerStats
com.google.android.gms.games.PlayerStatsClient
// Replace com.google.android.gms.games.Players
com.google.android.gms.games.PlayersClient
// Replace com.google.android.gms.games.GamesStatusCodes
com.google.android.gms.games.GamesClientStatusCodes
games v1
com.google.android.gms.games.achievement.Achievements
com.google.android.gms.games.leaderboard.Leaderboard
com.google.android.gms.games.snapshot.Snapshots
com.google.android.gms.games.stats.PlayerStats
com.google.android.gms.games.Players
com.google.android.gms.games.GamesStatusCodes
פיתוח והרצה של המשחק
במאמר יצירת build והרצה של האפליקציה מוסבר איך יוצרים build ומריצים אותו ב-Android Studio.
בדיקה של המשחק
מומלץ לבדוק את המשחק כדי לוודא שהוא פועל כמצופה. הבדיקות שאתם מבצעים תלויות בתכונות של המשחק.
בהמשך מפורטת רשימה של בדיקות נפוצות שאפשר להריץ.
הכניסה בוצעה בהצלחה.
הכניסה האוטומטית פועלת. המשתמש צריך להיכנס לחשבון בשירותי המשחקים של Play כשמפעילים את המשחק.
מוצג החלון הקופץ של קבלת הפנים.
מוצגות הודעות יומן על פעולות שהושלמו בהצלחה. מריצים את הפקודה הבאה במסוף:
adb logcat | grep com.google.android.
דוגמה להודעה ביומן על הצלחה:
[
$PlaylogGamesSignInAction$SignInPerformerSource@e1cdecc number=1 name=GAMES_SERVICE_BROKER>], returning true for shouldShowWelcomePopup. [CONTEXT service_id=1 ]
מוודאים שיש עקביות ברכיבי ממשק המשתמש.
חלונות קופצים, לוחות לידרבורד והישגים מוצגים בצורה תקינה ועקבית בגודלי מסך ובכיוונים שונים בממשק המשתמש (UI) של Play Games Services.
האפשרות ליציאה לא מוצגת בממשק המשתמש של שירותי המשחקים של Play.
מזהה המשתמש עקבי וניתן להשתמש בו בשילוב עם הקצה העורפי.
אם המשחק משתמש באימות בצד השרת, צריך לבדוק היטב את התהליך
requestServerSideAccess
. מוודאים שהשרת מקבל את קוד האימות ויכול להחליף אותו באסימון גישה. בדיקת תרחישי הצלחה וכשל של שגיאות רשת, תרחישיclient ID
לא חוקיים.
אם המשחק שלכם השתמש באחת מהתכונות הבאות, כדאי לבדוק אותן כדי לוודא שהן פועלות כמו לפני ההעברה:
- לידרבורדים: שליחת ציונים וצפייה בלוחות לידרבורד. בודקים את הדירוג הנכון ואת הצגת השמות והציונים של השחקנים.
- הישגים: ביטול הנעילה של הישגים ואימות שהם מתועדים בצורה נכונה ומוצגים בממשק המשתמש של Play Games.
- משחקים שמורים: אם המשחק משתמש במשחקים שמורים, חשוב לוודא שהשמירה והטעינה של ההתקדמות במשחק פועלות בצורה חלקה. חשוב במיוחד לבדוק את הנושא במספר מכשירים ואחרי עדכוני אפליקציות.
משימות לאחר ההעברה
אחרי שמשלימים את המעבר לגרסה 2 של Google Play Games, מבצעים את השלבים הבאים.
פרסום המשחק
יוצרים את קובצי ה-APK ומפרסמים את המשחק ב-Play Console.
- בתפריט של Android Studio, בוחרים באפשרות Build > Build Bundles(s) / APK(s) > Build APK(s).
- מפרסמים את המשחק. מידע נוסף זמין במאמר פרסום אפליקציות פרטיות מ-Play Console.