Di chuyển sang Dịch vụ trò chơi của Play phiên bản 2 (Unity)
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Tài liệu này mô tả cách di chuyển các trò chơi hiện có từ SDK games v1 sang SDK games v2.
Trình bổ trợ Play Games cho Unity (phiên bản 10 trở về trước) sử dụng SDK của phiên bản 1.
Trước khi bắt đầu
Đảm bảo rằng bạn đã thiết lập Play Console và cài đặt Unity Hub.
Tải trình bổ trợ Google Play Games cho Unity xuống
Để tận dụng các tính năng mới nhất trong Dịch vụ Play Games, hãy tải và cài đặt phiên bản trình bổ trợ mới nhất. Tải xuống qua kho lưu trữ gitHub.
Xoá trình bổ trợ cũ
Trong Unity Hub, hãy xoá các thư mục hoặc tệp sau.
Xoá các thư mục được đánh dấu trong dự án Unity của bạn (nhấp để phóng to).
Nhập trình bổ trợ mới vào dự án Unity
Để nhập trình bổ trợ vào dự án Unity, hãy làm theo các bước sau:
Mở dự án trò chơi của bạn.
Trong Unity Hub, hãy nhấp vào Assets > Import Package > Custom Package (Nội dung > Nhập gói > Gói tuỳ chỉnh) để nhập tệp unitypackage đã tải xuống vào nội dung của dự án.
Hãy đảm bảo nền tảng bản dựng hiện tại của bạn được đặt là Android.
Trong trình đơn chính, hãy nhấp vào File > Build Settings (Tệp > Cài đặt bản dựng).
Chọn Android rồi nhấp vào Switch Platform (Chuyển nền tảng).
Sẽ có một mục mới trong trình đơn tại Window > Google Play Games (Cửa sổ > Google Play Games). Nếu không có, hãy làm mới nội dung bằng cách nhấp vào Assets > Refresh (Nội dung > Làm mới), sau đó thử đặt lại nền tảng bản dựng.
Trong Unity Hub, hãy nhấp vào File > Build Settings > Player Settings > Other Settings (Tệp > Cài đặt bản dựng > Cài đặt trình phát > Các chế độ cài đặt khác).
Trong hộp Cấp API mục tiêu, hãy chọn một phiên bản.
Trong hộp Scripting backend, hãy nhập IL2CPP.
Trong hộp Target architectures (Kiến trúc mục tiêu), hãy chọn một giá trị.
Ghi lại tên gói package_name.Bạn có thể sử dụng thông tin này sau.
Thay thế lớp khởi tạo PlayGamesClientConfiguration bằng lớp PlayGamesPlatform.Instance.Authenticate().
Bạn không cần khởi chạy và kích hoạt PlayGamesPlatform. Khi gọi PlayGamesPlatform.Instance.Authenticate(), hệ thống sẽ tìm nạp kết quả của tính năng đăng nhập tự động.
C#
Trong Unity Hub, hãy tìm các tệp có lớp PlayGamesClientConfiguration.
usingGooglePlayGames;usingGooglePlayGames.BasicApi;usingUnityEngine.SocialPlatforms;publicvoidStart(){PlayGamesClientConfigurationconfig=newPlayGamesClientConfiguration.Builder()// Enables saving game progress.EnableSavedGames()// Requests the email address of the player be available// will bring up a prompt for consent.RequestEmail()// Requests a server auth code be generated so it can be passed to an// associated backend server application and exchanged for an OAuth token.RequestServerAuthCode(false)// Requests an ID token be generated. This OAuth token can be used to// identify the player to other services such as Firebase..RequestIdToken().Build();PlayGamesPlatform.InitializeInstance(config);// recommended for debugging:PlayGamesPlatform.DebugLogEnabled=true;// Activate the Google Play Games platformPlayGamesPlatform.Activate();}
Và cập nhật nó như sau:
usingGooglePlayGames;publicvoidStart(){PlayGamesPlatform.Instance.Authenticate(ProcessAuthentication);}internalvoidProcessAuthentication(SignInStatusstatus){if(status==SignInStatus.Success){// Continue with Play Games Services}else{// Disable your integration with Play Games Services or show a login// button to ask users to sign-in. Clicking it should call// PlayGamesPlatform.Instance.ManuallyAuthenticate(ProcessAuthentication).}}
Xoá mã đăng xuất. Dịch vụ trò chơi của Play không còn yêu cầu nút đăng xuất trong trò chơi nữa.
Xoá mã xuất hiện trong ví dụ sau:
C#
// sign outPlayGamesPlatform.Instance.SignOut();
Kiểm thử trò chơi
Đảm bảo trò chơi của bạn hoạt động như thiết kế bằng cách kiểm thử trò chơi. Các bài kiểm thử mà bạn thực hiện sẽ tuỳ thuộc vào các tính năng của trò chơi.
Sau đây là danh sách các kiểm thử thường gặp 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.
Ví dụ về cửa sổ bật lên chào mừng (nhấp để phóng to).
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:
adblogcat|grepcom.google.android.
Thông báo nhật ký thành công xuất hiện trong ví dụ sau:
Đả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 Play.
Lựa chọn đăng xuất không xuất hiện trong giao diện người dùng của Dịch vụ Play Games.
Đảm bảo bạn có thể truy xuất Mã nhận dạng người chơi thành công và nếu có, các chức năng phía máy chủ hoạt động như dự kiến.
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ỹ 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ợp client 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ử để đảm bảo rằng các tính năng đó hoạt động giống như trước khi di chuyển:
Bảng xếp hạng: Gửi điểm số và xem bảng xếp hạng. Kiểm tra thứ hạng và cách hiển thị tên cũng như điểm số của người chơi.
Thành tích: Mở khoá thành tích và xác minh rằng thành tích được ghi lại và hiển thị chính xác trong giao diện người dùng Play Games.
Trò chơi đã lưu: Nếu trò chơi sử dụng tính năng trò chơi đã lưu, hãy đảm bảo rằng việc lưu và tải tiến trình chơi diễn ra suôn sẻ. Điều này đặc biệt quan trọng khi kiểm thử trên nhiều thiết bị và sau khi cập nhật ứng dụng.
Các việc cần làm sau khi di chuyển
Hãy hoàn tất các bước sau khi bạn đã di chuyển sang SDK trò chơi phiên bản 2.
Nội dung và mã mẫu trên trang này phải tuân thủ các giấy phép như mô tả trong phần Giấy phép nội dung. Java và OpenJDK là nhãn hiệu hoặc nhãn hiệu đã đăng ký của Oracle và/hoặc đơn vị liên kết của Oracle.
Cập nhật lần gần đây nhất: 2025-07-27 UTC.
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 2025-07-27 UTC."],[],[],null,["# Migrate to Play Games Services v2 (Unity)\n\nThis document describes how to migrate existing games from the [games v1\nSDK](https://developers.google.com/android/games_v1/reference/com/google/android/gms/games/package-summary)\nto the [games v2\nSDK](https://developers.google.com/android/reference/com/google/android/gms/games/package-summary).\nThe Play Games plugin for Unity, versions 10 and earlier, uses the games v1 SDK.\n\nBefore you begin\n----------------\n\n- Make sure that you have already set up Play Console and installed the Unity Hub.\n\nDownload the Google Play Games plugin for Unity\n-----------------------------------------------\n\nTo benefit from the latest features in the Play Games Services, download and\ninstall the latest plugin version. Download it from the [gitHub\nrepository](https://github.com/playgameservices/play-games-plugin-for-unity/tree/master/current-build).\n\nRemove the old plugin\n---------------------\n\nIn the Unity Hub, remove the following folders or files. \n\n```text\nAssets/GooglePlayGames\n\nAssets/GeneratedLocalRepo/GooglePlayGames\n\nAssets/Plugins/Android/GooglePlayGamesManifest.androidlib\n\nAssets/Plugins/Android\n```\n[](/static/images/games/pgs/unityfolders.png) Remove the highlighted folders in your Unity project (click to enlarge).\n\nImport the new plugin to your Unity project\n-------------------------------------------\n\nTo import the plugin to your Unity project, follow these steps:\n\n1. Open your game project.\n2. In the Unity Hub, click **Assets \\\u003e Import Package \\\u003e Custom Package** to import the downloaded [`unitypackage`](https://github.com/playgameservices/play-games-plugin-for-unity/tree/master/current-build) file into your project's assets.\n3. Make sure that your current build platform is set to **Android**.\n\n 1. In the main menu, click **File \\\u003e Build Settings**.\n\n 2. Select **Android** and click **Switch Platform**.\n\n 3. There should be a new menu item under **Window \\\u003e Google Play Games** . If\n there isn't, refresh the assets by clicking **Assets \\\u003e Refresh** and\n then try setting the build platform again.\n\n4. In the Unity Hub, click\n **File \\\u003e Build Settings \\\u003e Player Settings \\\u003e Other Settings**.\n\n5. In the **Target API level** box, select a version.\n\n6. In the **Scripting backend** box, enter `IL2CPP`.\n\n7. In the **Target architectures** box, select a value.\n\n8. Note the package name \u003cvar translate=\"no\"\u003epackage_name\u003c/var\u003e.You can use this information\n later.\n\n The player settings in your Unity project.\n9. [Copy the Android resources from Play Console](/games/pgs/unity/unity-start#copy-android-resources)\n\n10. [Add the Android resources to your Unity project](/games/pgs/unity/unity-start#set-up-unity-project)\n\nUpdate automatic sign-in code\n-----------------------------\n\nReplace the `PlayGamesClientConfiguration` initialization class with the\n`PlayGamesPlatform.Instance.Authenticate()` class.\nThe initialization and activation of\n[`PlayGamesPlatform`](/games/services/unity/v2/api/class/google-play-games/play-games-platform)\nis not required. Calling `PlayGamesPlatform.Instance.Authenticate()` fetches the\nresult of automatic sign-in. \n\n### C#\n\nIn the Unity Hub, locate the files with\n`PlayGamesClientConfiguration` class. \n\n using GooglePlayGames;\n using GooglePlayGames.BasicApi;\n using UnityEngine.SocialPlatforms;\n\n public void Start() {\n PlayGamesClientConfiguration config =\n new PlayGamesClientConfiguration.Builder()\n // Enables saving game progress\n .EnableSavedGames()\n // Requests the email address of the player be available\n // will bring up a prompt for consent\n .RequestEmail()\n // Requests a server auth code be generated so it can be passed to an\n // associated backend server application and exchanged for an OAuth token\n .RequestServerAuthCode(false)\n // Requests an ID token be generated. This OAuth token can be used to\n // identify the player to other services such as Firebase.\n .RequestIdToken()\n .Build();\n\n PlayGamesPlatform.InitializeInstance(config);\n // recommended for debugging:\n PlayGamesPlatform.DebugLogEnabled = true;\n // Activate the Google Play Games platform\n PlayGamesPlatform.Activate();\n }\n\nAnd update it to this: \n\n using GooglePlayGames;\n\n public void Start() {\n PlayGamesPlatform.Instance.Authenticate(ProcessAuthentication);\n }\n\n internal void ProcessAuthentication(SignInStatus status) {\n if (status == SignInStatus.Success) {\n // Continue with Play Games Services\n } else {\n // Disable your integration with Play Games Services or show a login\n // button to ask users to sign-in. Clicking it should call\n // PlayGamesPlatform.Instance.ManuallyAuthenticate(ProcessAuthentication).\n }\n }\n\nChoose a social platform\n------------------------\n\nTo choose a social platform, see\n[choose a social platform](/games/pgs/unity/unity-start#choose-social-platform).\n\nRetrieve server authentication codes\n------------------------------------\n\nTo get server side access codes,\nsee [retrieve server authentication codes](/games/pgs/unity/unity-start#retrieve_server_authentication_codes).\n\nRemove sign-out code\n--------------------\n\nRemove the code for sign-out. Play Games Services no longer requires an in-game\nsign-out button.\n\nRemove the code shown in the following example: \n\n### C#\n\n // sign out\n PlayGamesPlatform.Instance.SignOut();\n\nTest your game\n--------------\n\nEnsure your game functions as designed by testing it. The tests you perform\ndepend on your game's features.\n\nThe following is a list of common tests to run.\n\n1. **Successful sign-in**.\n\n 1. Automatic sign-in works. The user should be signed in to\n Play Games Services upon launching the game.\n\n 2. The welcome popup is displayed.\n\n\n [](/static/images/games/pgs/welcometoast.png) Sample welcome popup (click to enlarge).\n\n \u003cbr /\u003e\n\n 3. Successful log messages are displayed. Run the following\n command in the terminal:\n\n ```bash\n adb logcat | grep com.google.android.\n ```\n\n A successful log message is shown in the following example: \n\n ```bash\n [$PlaylogGamesSignInAction$SignInPerformerSource@e1cdecc\n number=1 name=GAMES_SERVICE_BROKER\u003e], returning true for shouldShowWelcomePopup.\n [CONTEXT service_id=1 ]\n ```\n2. **Ensure UI component consistency**.\n\n 1. Pop ups, leaderboards, and achievements display correctly and\n consistently on various screen sizes and orientations in the\n Play Games Services user interface (UI).\n\n 2. Sign-out option is not visible in the Play Games Services\n UI.\n\n 3. Make sure you can successfully retrieve Player ID, and if applicable,\n server-side capabilities work as expected.\n\n 4. If the game uses server-side authentication, thoroughly test the\n `requestServerSideAccess` flow. Ensure the server receives the auth code\n and can exchange it for an access token.\n Test both success and failure scenarios for network errors, invalid\n `client ID` scenarios.\n\nIf your game was using any of the following features, test them to ensure that\nthey work the same as before the migration:\n\n- **Leaderboards**: Submit scores and view leaderboards. Check for the correct ranking and display of player names and scores.\n- **Achievements**: Unlock achievements and verify they are correctly recorded and displayed in the Play Games UI.\n- **Saved Games**: If the game uses saved games, ensure that saving and loading the game progress works flawlessly. This is particularly critical to test across multiple devices and after app updates.\n\nPost migration tasks\n--------------------\n\nComplete the following steps after you have migrated to games v2 SDK.\n\n1. [Use Play App Signing](/games/pgs/unity/unity-start#create-test-release)\n\n2. [Create an AAB file](/games/pgs/unity/unity-start#create_an_aab_file)\n\n3. [Create an internal testing release](/games/pgs/unity/unity-start#create_an_internal_testing_release)\n\n4. [Verify your App signing credentials](/games/pgs/unity/unity-start#set-up-app-signin)"]]
