Tài liệu này mô tả cách di chuyển các trò chơi hiện có từ SDK trò chơi v1 sang SDK trò chơi v2.
Trước khi bắt đầu
Bạn có thể sử dụng bất kỳ IDE nào mà bạn muốn, chẳng hạn như Android Studio, để di chuyển trò chơi. Hãy hoàn tất các bước sau trước khi di chuyển sang games v2:
- Tải và cài đặt Android Studio
- Trò chơi của bạn phải sử dụng SDK games v1
Cập nhật phần phụ thuộc
Trong tệp
build.gradle
của mô-đun, hãy tìm dòng này trong phần phụ thuộc cấp mô-đun.implementation "com.google.android.gms:play-services-games-v1:+"
Thay thế bằng mã sau:
implementation "com.google.android.gms:play-services-games-v2:version"
Thay thế version bằng phiên bản mới nhất của SDK trò chơi.
Sau khi cập nhật các phần phụ thuộc, hãy đảm bảo bạn hoàn tất tất cả các bước trong tài liệu này.
Di chuyển từ tính năng Đăng nhập bằng Google không dùng nữa
Thay thế lớp GoogleSignInClient
bằng lớp GamesSignInClient
.
Java
Tìm các tệp có lớp 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);
}
Và cập nhật nó như sau:
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
Tìm các tệp có lớp 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)
}
Và cập nhật nó như sau:
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)
}
Cập nhật mã GoogleSignIn
API và phạm vi GoogleSignIn
không được hỗ trợ trong SDK trò chơi phiên bản 2. Thay thế mã API GoogleSignIn
cho các phạm vi OAuth 2.0 bằng API GamesSignInClient
như trong ví dụ sau:
Java
Tìm các tệp có lớp và phạm vi 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");
}
});
}
Và cập nhật nó như sau:
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
Tìm các tệp có lớp và phạm vi 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")
}
}
}
Và cập nhật nó như sau:
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()
}
Thêm mã GamesSignInClient
Nếu người chơi đã đăng nhập thành công, hãy xoá nút đăng nhập vào Dịch vụ trò chơi của Play khỏi trò chơi của bạn. Nếu người dùng chọn không đăng nhập khi trò chơi khởi động, hãy tiếp tục hiển thị nút có biểu tượng Dịch vụ trò chơi của Play và bắt đầu quy trình đăng nhập bằng 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
}
}
}
Xoá mã đăng xuất
Xoá mã cho GoogleSignInClient.signOut
.
Xoá mã trong ví dụ sau:
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.
}
}
Kiểm tra việc tự động đăng nhập thành công
Thêm mã sau để kiểm tra xem bạn đã tự động đăng nhập hay chưa và thêm logic tuỳ chỉnh nếu bạn có.
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
}
}
}
Cập nhật tên và phương thức lớp ứng dụng
Khi bạn di chuyển sang games v2, các phương thức dùng để lấy tên lớp ứng dụng sẽ khác.
Sử dụng các phương thức PlayGames.getxxxClient()
tương ứng thay vì các phương thức Games.getxxxClient()
.
Ví dụ: đối với LeaderboardsClient
, hãy sử dụng PlayGames.getLeaderboardsClient()
thay vì phương thức Games.getLeaderboardsClient()
.
Java
Tìm mã cho 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));
}
Và cập nhật nó như sau:
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
Tìm mã cho 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))
}
Và cập nhật nó như sau:
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)
}
Tương tự, hãy sử dụng các phương thức tương ứng cho các ứng dụng sau: AchievementsClient
, EventsClient
, GamesSignInClient
, PlayerStatsClient
, RecallClient
, SnapshotsClient
hoặc PlayersClient
.
Cập nhật các lớp truy cập phía máy chủ
Để yêu cầu mã truy cập phía máy chủ, hãy sử dụng phương thức GamesSignInClient.requestServerSideAccess()
thay vì phương thức GoogleSignInAccount.getServerAuthCode()
.
Ví dụ sau đây cho thấy cách yêu cầu mã truy cập phía máy chủ.
Java
Tìm mã cho lớp 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();
}
}
}
Và cập nhật nó như sau:
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
Tìm mã cho lớp 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()
}
}
}
Và cập nhật nó như sau:
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.
}
});
}
Di chuyển từ GoogleApiClient
Đối với các chế độ tích hợp hiện có từ trước, có thể trò chơi của bạn đang phụ thuộc vào biến thể API GoogleApiClient
của SDK Dịch vụ trò chơi của Play. Biến thể này đã ngừng hoạt động từ cuối năm 2017, và được thay thế bằng các ứng dụng "không có kết nối". Để di chuyển, bạn có thể thay thế lớp GoogleApiClient
bằng một lớp tương đương "không có kết nối".
Dưới đây là bản đồ ánh xạ các lớp phổ biến:
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
Tạo bản dựng và chạy trò chơi
Để tạo và chạy trên Android Studio, hãy xem phần Tạo và chạy ứng dụng.
Kiểm thử trò chơi
Kiểm thử để đảm bảo trò chơi của bạn hoạt động như dự kiến. Các bài kiểm thử bạn thực hiện phụ thuộc vào tính năng của trò chơi.
Dưới đây là danh sách các kiểm thử phổ biến cần chạy.
Đăng nhập thành công.
Tính năng tự động đăng nhập hoạt động. Người dùng phải đăng nhập vào Dịch vụ trò chơi của Play khi khởi chạy trò chơi.
Cửa sổ bật lên chào mừng sẽ xuất hiện.
Thông báo nhật ký thành công sẽ xuất hiện. Chạy lệnh sau trong dòng lệnh:
adb logcat | grep com.google.android.
Thông báo nhật ký thành công được hiển thị trong ví dụ sau:
[
$PlaylogGamesSignInAction$SignInPerformerSource@e1cdecc number=1 name=GAMES_SERVICE_BROKER>], returning true for shouldShowWelcomePopup. [CONTEXT service_id=1 ]
Đảm bảo tính nhất quán của thành phần giao diện người dùng.
Cửa sổ bật lên, bảng xếp hạng và thành tích hiển thị chính xác và nhất quán trên nhiều kích thước màn hình và hướng trong giao diện người dùng (UI) của Dịch vụ trò chơi của Play.
Tuỳ chọn Đăng xuất không xuất hiện trong giao diện người dùng của Dịch vụ trò chơi của Play.
Mã nhận dạng người chơi nhất quán và có thể dùng để tích hợp phần phụ trợ.
Nếu trò chơi sử dụng phương thức xác thực phía máy chủ, hãy kiểm thử kỹ lưỡng quy trình
requestServerSideAccess
. Đảm bảo máy chủ nhận được mã xác thực và có thể trao đổi mã đó lấy mã truy cập. Kiểm thử cả trường hợp thành công và không thành công đối với lỗi mạng, trường hợpclient ID
không hợp lệ.
Nếu trò chơi của bạn đang sử dụng bất kỳ tính năng nào sau đây, hãy kiểm thử các tính năng đó để đảm bảo rằng chúng hoạt động giống như trước khi di chuyển:
- Bảng xếp hạng: Gửi điểm và xem bảng xếp hạng. Kiểm tra thứ hạng và cách hiển thị tên người chơi và điểm số.
- Thành tích: Mở khoá thành tích và xác minh rằng các thành tích đó được ghi lại và hiển thị chính xác trong giao diện người dùng của Play Games.
- Trò chơi đã lưu: Nếu trò chơi sử dụng trò chơi đã lưu, hãy đảm bảo rằng việc lưu và tải tiến trình trò chơi hoạt động hoàn hảo. Điều này đặc biệt quan trọng để kiểm thử trên nhiều thiết bị và sau khi cập nhật ứng dụng.
Đăng các tác vụ di chuyển
Hãy hoàn tất các bước sau đây sau khi bạn di chuyển sang games phiên bản 2.
Phát hành trò chơi
Tạo(các) tệp APK và phát hành trò chơi trong Play Console.
- Trong trình đơn Android Studio, hãy chọn Build > Build Bundle(s)/APK(s) > Build APK(s) (Tạo > Tạo gói/tệp APK > Tạo tệp APK).
- Phát hành trò chơi của bạn Để biết thêm thông tin, hãy xem phần Xuất bản ứng dụng riêng tư bằng Play Console.