نقل البيانات إلى الإصدار 2 من "خدمات ألعاب Play" (Unity)

يوضّح هذا المستند كيفية نقل الألعاب الحالية من الإصدار v1 من حزمة SDK للألعاب إلى الإصدار v2 من حزمة SDK للألعاب. يستخدم الإصداران 10 والإصدارات الأقدم من مكوّن ألعاب Play الإضافي لمحرّك الألعاب Unity الإصدار v1 من حزمة SDK للألعاب.

قبل البدء

• تأكَّد من أنّك أعددت Play Console وثبّت Unity Editor.

تنزيل مكوّن ألعاب Google Play الإضافي لمحرّك الألعاب Unity

للاستفادة من أحدث الميزات في "خدمات ألعاب Play"، نزِّل أحدث إصدار من المكوّن الإضافي وثبِّته. يمكنك تنزيله من مستودع gitHub repository.

إزالة المكوّن الإضافي القديم

في Unity Editor، أزِل المجلدات أو الملفات التالية.

Assets/GooglePlayGames

Assets/GeneratedLocalRepo/GooglePlayGames

Assets/Plugins/Android/GooglePlayGamesManifest.androidlib

Assets/Plugins/Android

استيراد المكوّن الإضافي الجديد إلى مشروع Unity

لاستيراد المكوّن الإضافي إلى مشروع Unity، اتّبِع الخطوات التالية:

1. افتح مشروع لعبتك.
2. في Unity Editor، انقر على مواد العرض (Assets) > استيراد حزمة (Import Package) > حزمة مخصّصة (Custom Package) لاستيراد الملف الذي تم تنزيله unitypackage إلى مواد عرض مشروعك.

3. تأكَّد من أنّ منصة الإصدار الحالية مضبوطة على Android.

   1. في القائمة الرئيسية، انقر على ملف (File) > إعدادات الإصدار (Build Settings).

   2. اختَر Android وانقر على تبديل المنصة (Switch Platform).

   3. من المفترض أن يظهر عنصر قائمة جديد ضمن نافذة (Window) > ألعاب Google Play (Google Play Games). إذا لم يظهر، أعِد تحميل مواد العرض بالنقر على مواد العرض (Assets) > إعادة تحميل (Refresh) ، ثم حاوِل ضبط منصة الإصدار مرة أخرى.

4. في Unity Editor، انقر على ملف (File) > إعدادات الإصدار (Build Settings) > إعدادات المشغّل (Player Settings) > إعدادات أخرى (Other Settings).

5. في مربّع مستوى واجهة برمجة التطبيقات المستهدَف ، اختَر إصدارًا.

6. في مربّع الواجهة الخلفية للبرمجة النصية ، أدخِل IL2CPP.

7. في مربّع البنيات المستهدَفة ، اختَر قيمة.

8. دوِّن اسم الحزمة package_name.يمكنك استخدام هذه المعلومات لاحقًا.

   

9. نسخ موارد Android من Play Console

10. إضافة موارد Android إلى مشروع Unity

مسارات نقل البيانات

يعتمد مسار نقل البيانات الصحيح للعبتك على كيفية تنفيذها للإصدار v1 من "خدمات ألعاب Play" ومعالجتها لهوية اللاعب. لضمان عملية نقل سلسة ومنع فقدان بيانات اللاعب، حدِّد السيناريو الذي يطابق إعدادك الحالي على أفضل وجه واتّبِع الخطوات المقابلة.

الخيار 1: للألعاب التي يكون فيها حساب اللاعب داخل اللعبة (IGA) مرتبطًا بمعرّف اللاعب في "خدمات ألعاب Play"

ينطبق هذا السيناريو على الألعاب التي استخدمت Player ID في "خدمات ألعاب Play" كمعرّف وحيد لحساب اللاعب داخل اللعبة (IGA) ولم تطلب أو تخزِّن OpenID من قبل. التحدي الرئيسي هو ربط حساب اللاعب الحالي داخل اللعبة (IGA) بمعرّف أساسي (OpenID) بدون فقدان الاتصال بمستوى تقدّم اللاعب.

يتضمّن مسار نقل البيانات الخطوات التالية:

1. عند تشغيل اللعبة، تصادق حزمة تطوير البرامج (SDK) للإصدار v2 من "خدمات ألعاب Play" على المنصة تلقائيًا وبدون أي إجراء من المستخدم.

2. تعرض اللعبة شاشة تسجيل الدخول. يجب أن تتضمّن هذه الشاشة زر تسجيل الدخول باستخدام حساب Google (SiWG) ، بدلاً من زر Google Play. لدمج الميزة:

   1. نزِّل CredManBridge.java إلى مجلدك. يعمل صف Java هذا كجسر بين Unity ومكتبة androidx.credentials.

      CredManBridge.java

      
      package com.wickedcube.trivialkart;
      import android.accounts.Account;
      import android.content.Context;
      import android.util.Log;
      import android.os.CancellationSignal;
      import androidx.credentials.CredentialManager;
      import androidx.credentials.GetCredentialRequest;
      import androidx.credentials.GetCredentialResponse;
      import androidx.credentials.exceptions.GetCredentialException;
      import androidx.credentials.exceptions.NoCredentialException;
      import com.google.android.libraries.identity.googleid.GetGoogleIdOption;
      import com.google.android.libraries.identity.googleid.GoogleIdTokenCredential;
      import com.google.android.gms.auth.api.identity.AuthorizationClient;
      import com.google.android.gms.auth.api.identity.AuthorizationRequest;
      import com.google.android.gms.auth.api.identity.AuthorizationResult;
      import com.google.android.gms.common.api.ApiException;
      import com.google.android.gms.auth.api.identity.Identity;
      import com.google.android.gms.common.api.Scope;
      import com.unity3d.player.UnityPlayer;
      import java.util.Collections;
      import java.util.List;
      import java.util.concurrent.Executor;
      import java.util.concurrent.Executors;
      
      
      public class CredManBridge {
      
      // --- MODE 1: SILENT SIGN-IN (Called on Awake) ---
      // Tries to auto-select an authorized account. If it fails, it does NOT show UI.
      public static void signInSilent(Context context, String webClientId) {
        CredentialManager credentialManager = CredentialManager.create(context);
        CancellationSignal cancellationSignal = new CancellationSignal();
        Executor executor = Executors.newSingleThreadExecutor();
      
      Log.d("CredMan", "Attempting Silent Sign-In...");
      
      GetGoogleIdOption silentOption = new GetGoogleIdOption.Builder()
          .setFilterByAuthorizedAccounts(true) // Strict: Only authorized accounts
          .setServerClientId(webClientId)
          .setAutoSelectEnabled(true)          // Auto-select if possible
          .build();
      
      GetCredentialRequest silentRequest = new GetCredentialRequest.Builder()
          .addCredentialOption(silentOption)
          .build();
      
      credentialManager.getCredentialAsync(
          context,
          silentRequest,
          cancellationSignal,
          executor,
          new androidx.credentials.CredentialManagerCallback<GetCredentialResponse, GetCredentialException>() {
              @Override
              public void onResult(GetCredentialResponse result) {
                  Log.d("CredMan", "Silent Sign-In Successful!");
                  handleSignInResult(context, result, webClientId);
              }
          @Override
          public void onError(GetCredentialException e) {
              // Send a specific error code so Unity knows to just stay on the Start Screen
              Log.d("CredMan", "Silent sign-in failed. Keeping UI hidden.");
              UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "SilentFailed");
          }
      }
      
      );
      }
      
      // --- MODE 2: INTERACTIVE SIGN-IN (Called on Button Click) ---
      // Forces the Account Selection / "Add Account" sheet to appear.
      public static void signInInteractive(Context context, String webClientId) {
        CredentialManager credentialManager = CredentialManager.create(context);
        CancellationSignal cancellationSignal = new CancellationSignal();
        Executor executor = Executors.newSingleThreadExecutor();
      
      Log.d("CredMan", "Starting Interactive Sign-In...");
      
      GetGoogleIdOption interactiveOption = new GetGoogleIdOption.Builder()
          .setFilterByAuthorizedAccounts(false) // Show ALL accounts (and "Add Account")
          .setServerClientId(webClientId)
          .setAutoSelectEnabled(false)          // Force the UI to show
          .build();
      
      GetCredentialRequest interactiveRequest = new GetCredentialRequest.Builder()
          .addCredentialOption(interactiveOption)
          .build();
      
      credentialManager.getCredentialAsync(
          context,
          interactiveRequest,
          cancellationSignal,
          executor,
          new androidx.credentials.CredentialManagerCallback<getcredentialresponse, getcredentialexception="">() {
              @Override
              public void onResult(GetCredentialResponse result) {
                  Log.d("CredMan", "Interactive Sign-In Successful!");
                  handleSignInResult(context, result, webClientId);
              }</getcredentialresponse,>
          @Override
          public void onError(GetCredentialException e) {
              Log.e("CredMan", "Interactive Sign-In Canceled or Failed", e);
              UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "Canceled");
          }
      }
      
      );
      }
      
      private static void handleSignInResult(Context context, GetCredentialResponse result, String webClientId) {
        try {
          GoogleIdTokenCredential credential = GoogleIdTokenCredential.createFrom(result.getCredential().getData());
          String email = credential.getId();
      Account account = new Account(email, "com.google");
      // Requesting GAMES_LITE scope to check for pre-existing V1 grants
      List<Scope> requestedScopes = Collections.singletonList(new Scope("https://www.googleapis.com/auth/games_lite"));
      
      AuthorizationRequest authRequest = new AuthorizationRequest.Builder()
          .setRequestedScopes(requestedScopes)
          .setAccount(account)
          .requestOfflineAccess(webClientId)
          .build();
      
      AuthorizationClient authClient = Identity.getAuthorizationClient(context);
      
      authClient.authorize(authRequest)
          .addOnSuccessListener(authorizationResult -> {
              if (authorizationResult.getServerAuthCode() != null) {
                  // CASE 1: RETURNING USER (Success)
                  // The user has already granted GAMES_LITE in the past.
                  // We got the code directly without showing UI.
                  Log.i("CredMan", "PGS v1: Existing grant found. Returning user detected. Auth Code retrieved.");
                  UnityPlayer.UnitySendMessage("AuthManager", "OnSignInSuccess", authorizationResult.getServerAuthCode());
              }
              else if (authorizationResult.hasResolution()) {
                  // CASE 2: NEW USER (PendingIntent)
                  // The user has NOT granted GAMES_LITE before. The API returned a PendingIntent
                  // (authorizationResult.getPendingIntent()) to show the consent screen.
                  // As per your flow, we DISCARD this intent and do not show UI.
                  Log.i("CredMan", "PGS v1: No existing grant (PendingIntent returned). This is a NEW user or they revoked access.");
                  Log.i("CredMan", "PGS v1: Discarding PendingIntent. Proceeding as New User.");
      
                  // Notify Unity that this is a "New User" so it can trigger V2 logic instead of failing
                  UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "NewUser_NoGrant");
              }
              else {
                  // Edge Case: No code and no resolution?
                  Log.e("CredMan", "PGS v1: Authorization success but no Auth Code or Resolution returned.");
                  UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "No Auth Code returned");
              }
          })
          .addOnFailureListener(e -> {
              // CASE 3: GENERIC FAILURE
              Log.e("CredMan", "PGS v1: Authorization failed completely.", e);
              UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "Authorization Failed: " + e.getMessage());
          });
      
      } catch (Exception e) {
          UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "Parsing Error: " + e.getMessage());
      }
      }
      }
      
      
      
      

   2. دمج "مدير بيانات الاعتماد":

      • استخدِم GetGoogleIdOption مع setFilterByAuthorizedAccounts(true) لعمليات تسجيل الدخول بدون أي إجراء من المستخدم لتسجيل دخول المستخدمين الذين سبق لهم منح الإذن للتطبيق فقط.
      • استخدِم setFilterByAuthorizedAccounts(false) لعمليات تسجيل الدخول التفاعلية للسماح للمستخدمين باختيار حساب أو إضافة حساب جديد.

   3. طلب النطاق:

      • بعد الحصول على بيانات اعتماد Google الأساسية، يتم إنشاء AuthorizationRequest يطلب النطاق القديم المحدد: https://www.googleapis.com/auth/games_lite.
      • هذا النطاق مهم لأنه يمنح الخادم إذن البحث عن `معرّف اللاعب` القديم للمستخدم.

   4. معالجة النتائج:

      • إذا منح المستخدم الإذن (أو سبق له منحه)، يعرض الجسر ServerAuthCode على Unity.
      • إذا لم يمنح المستخدم الإذن (سيناريو المستخدم الجديد)، تعرض واجهة برمجة التطبيقات PendingIntent. في هذا المثال، يتم تجاهل الغرض، ويتم التعامل مع المستخدم كمستخدم جديد لتبسيط المسار.

3. لدعم Credential Manager وGoogle Identity services، تأكَّد من إضافة التبعيات التالية إلى إعدادات Gradle في mainTemplate.gradle.

   dependencies {
   // Standard Unity dependencies
   implementation fileTree(dir: 'libs', include: ['*.jar'])
   
   // Credential Manager and Identity Libraries
   implementation 'androidx.credentials:credentials:1.3.0'
   implementation 'androidx.credentials:credentials-play-services-auth:1.3.0'
   implementation 'com.google.android.libraries.identity.googleid:googleid:1.1.1'
   
   // Play Services Auth for legacy scope handling
   implementation 'com.google.android.gms:play-services-auth:21.2.0'
   }

   • مدير بيانات الاعتماد: يعالج التنسيق الأساسي للهوية وواجهة المستخدم لاختيار الحساب.
   • مكتبة GoogleID: توفّر على وجه التحديد GetGoogleIdOption لـ استرداد رموز OpenID Connect المميزة.
   • المصادقة في "خدمات Play": مطلوبة للحفاظ على التوافق وطلب النطاق GAMES_LITE لاسترداد Player ID القديم.

4. عندما ينقر اللاعب على زر "تسجيل الدخول باستخدام حساب Google" (SiWG) ويختار حسابًا على Google، يجب أن تسترد اللعبة معرّفَين مميّزَين:

   • OpenID، وهو المعرّف الأساسي لربط حساب اللاعب داخل اللعبة (IGA).
   • Player ID في "خدمات ألعاب Play"، الذي يتم استرداده باستخدام النطاق GAMES_LITE، للبحث عن حساب اللاعب داخل اللعبة (IGA) في نظامك الخلفي وإجراء عملية الربط.

5. في عمليات تشغيل اللعبة اللاحقة، يمكن للاعبين الوصول إلى حساباتهم داخل اللعبة (IGA) من خلال مسار "تسجيل الدخول باستخدام حساب Google" (SiWG)، بدون أن تضطر الألعاب إلى استخدام Player ID كمعرّف أساسي.

using GooglePlayGames;
using GooglePlayGames.BasicApi;
using UnityEngine.SocialPlatforms;

public void Start() {
    PlayGamesClientConfiguration config =
        new PlayGamesClientConfiguration.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 platform
    PlayGamesPlatform.Activate();
}

using GooglePlayGames;

public void Start() {
    PlayGamesPlatform.Instance.Authenticate(ProcessAuthentication);
}

internal void ProcessAuthentication(SignInStatus status) {
    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).
    }
}

// sign out
PlayGamesPlatform.Instance.SignOut();