يوضّح هذا المستند كيفية نقل الألعاب الحالية من حزمة SDK لألعاب الإصدار 1 إلى حزمة SDK لألعاب الإصدار 2.
قبل البدء
يمكنك استخدام أي بيئة تطوير متكاملة مفضّلة، مثل "استوديو Android"، لنقل لعبتك. أكمِل الخطوات التالية قبل نقل البيانات إلى الإصدار 2 من "ألعاب Play":
- تنزيل "استوديو Android" وتثبيته
- يجب أن تستخدم لعبتك الإصدار 1 من حزمة تطوير البرامج (SDK) للألعاب.
تعديل التبعيات
في ملف
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
لا تتوفّر واجهة برمجة التطبيقات GoogleSignIn
ونطاقاتها في حزمة تطوير البرامج (SDK) لألعاب الإصدار 2. استبدِل رمز GoogleSignIn
API
لنطاقات OAuth 2.0 برمز
GamesSignInClient
API كما هو موضّح في المثال التالي:
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" من لعبتك. إذا اختار المستخدم عدم تسجيل الدخول عند تشغيل اللعبة،
يستمر عرض زر يحمل رمز "خدمات ألعاب 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
}
}
}
تعديل أسماء فئات العملاء وطُرقهم
عند نقل البيانات إلى الإصدار 2 من ألعاب Google، تختلف الأساليب المستخدَمة للحصول على أسماء فئات العملاء.
استخدِم طُرق
PlayGames.getxxxClient()
المقابلة بدلاً من طُرق
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
.
تعديل فئات الوصول من جهة الخادم
لطلب رمز دخول من جهة الخادم، استخدِم الأسلوب
GamesSignInClient.requestServerSideAccess()
بدلاً من الأسلوب
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
لحزمة تطوير البرامج (SDK) الخاصة بـ "خدمات ألعاب Play". تم إيقاف هذا الإجراء نهائيًا في أواخر عام 2017
وتم استبداله بعملاء "بدون اتصال". لنقل البيانات، يمكنك استبدال فئة
GoogleApiClient
بمكافئ "بدون اتصال".
في ما يلي تعيين للفئات الشائعة:
الإصدار 2 من الألعاب
// 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
إنشاء اللعبة وتشغيلها
لإنشاء التطبيق وتشغيله على 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 ]
ضمان اتساق مكونات واجهة المستخدم
يتم عرض النوافذ المنبثقة ولوحات الصدارة والإنجازات بشكل صحيح وبثبات على أحجام شاشات واتجاهات مختلفة في واجهة مستخدم "خدمات ألعاب Play".
لا يظهر خيار تسجيل الخروج في واجهة مستخدم "خدمات ألعاب Play".
تأكَّد من أنّه يمكنك استرداد معرّف اللاعب بنجاح، ومن أنّ ميزات جهة الخادم تعمل على النحو المتوقّع، إن أمكن.
إذا كانت اللعبة تستخدم مصادقة من جهة الخادم، اختبِر بدقة خطوات
requestServerSideAccess
. تأكَّد من أنّ الخادم يتلقّى رمز التفويض ويمكنه استبداله برمز مميّز للوصول. اختبِر سيناريوهات النجاح والفشل لأخطاء الشبكة وسيناريوهاتclient ID
غير الصالحة.
إذا كانت لعبتك تستخدم أيًا من الميزات التالية، اختبِرها للتأكّد من أنّها تعمل بالطريقة نفسها التي كانت تعمل بها قبل نقل البيانات:
- قوائم الصدارة: يمكنك إرسال النتائج والاطّلاع على قوائم الصدارة. تأكَّد من صحة ترتيب اللاعبين وأسماءهم ونتائجهم المعروضة.
- الإنجازات: يمكنك فتح قفل الإنجازات والتأكّد من تسجيلها وعرضها بشكل صحيح في واجهة مستخدم تطبيق "ألعاب Play".
- الألعاب المحفوظة: إذا كانت اللعبة تستخدم ميزة "حفظ الألعاب"، تأكَّد من أنّ ميزة حفظ مستوى التقدّم في اللعبة وتحميله تعمل بسلاسة. وهذا أمر مهم بشكل خاص لاختبار التطبيقات على عدة أجهزة وبعد تحديثها.
مهام ما بعد نقل البيانات
أكمِل الخطوات التالية بعد نقل البيانات إلى الإصدار 2 من "ألعاب Google Play".
نشر اللعبة
أنشئ حِزم APK وانشِر اللعبة في Play Console.
- في قائمة Android Studio، اختَر إنشاء > إنشاء حِزم / حِزم APK > إنشاء حِزم APK.
- انشر لعبتك. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة نشر التطبيقات الخاصة من Play Console.