تسجيل الدخول في "ألعاب Android"

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

تنفيذ عملية تسجيل الدخول إلى اللاعب

فئة GoogleSignInClient هي نقطة الدخول الرئيسية لاسترداد حساب اللاعب الذي سجّل الدخول حاليًا، ولتسجيل دخول اللاعب إذا لم يسبق له ذلك على تطبيقك في الجهاز.

لإنشاء برنامج عملاء لتسجيل الدخول، اتّبِع الخطوات التالية:

1. أنشئ عنصر تسجيل دخول من خلال عنصر GoogleSignInOptions ، كما هو موضّح في مقتطف الرمز البرمجي التالي. في GoogleSignInOptions.Builder لضبط عملية تسجيل الدخول، عليك تحديد GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN.

   GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;

2. إذا كنت تريد استخدام رمز SnapshotsClient، أضِف .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS) إلى GoogleSignInOptions.Builder كما هو موضّح في مقتطف الرمز البرمجي التالي:

   GoogleSignInOptions  signInOptions =
       new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
           .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS)
           .build();

3. استخدِم طريقة GoogleSignIn.getClient() وأدخِل الخيارات التي ضبطتها في الخطوات السابقة. إذا كان الطلب ناجحًا، تعرض Google Sign-In API مثيلًا لمحاولة تسجيل الدخول باستخدام GoogleSignInClient.

التحقّق مما إذا كان اللاعب قد سجّل الدخول من قبل

يمكنك التحقّق مما إذا كان قد تم تسجيل الدخول إلى حساب على الجهاز الحالي باستخدام GoogleSignIn.getLastSignedInAccount() وما إذا كان هذا الحساب قد حصل على الأذونات المطلوبة باستخدام GoogleSignIn.hasPermissions(). إذا كان كلا الشرطَين صحيحَين، أي أنّ getLastSignedInAccount() يعرض قيمة غير صفرية وhasPermissions() يعرض true، يمكنك استخدام الحساب الذي تم إرجاعه من getLastSignedInAccount() بأمان، حتى إذا كان الجهاز غير متصل بالإنترنت.

تسجيل الدخول بدون صوت

يمكنك الاتصال بـ silentSignIn() لاسترداد حساب اللاعب الذي سجّل الدخول حاليًا، ومحاولة تسجيل دخول اللاعبين بدون عرض واجهة مستخدم إذا سبق لهم تسجيل دخولهم بنجاح إلى تطبيقك على جهاز مختلف.

تُرجع الطريقة silentSignIn() Task<GoogleSignInAccount>. عند اكتمال المهمة، يمكنك ضبط الحقل GoogleSignInAccount الذي أعلنت عنه سابقًا على حساب تسجيل الدخول الذي تُرجعه المهمة كنتيجة، أو على null للإشارة إلى عدم توفّر مستخدم سجّل الدخول.

إذا تعذّرت محاولة تسجيل الدخول بدون إشعار، يمكنك اختياريًا إرسال نية تسجيل الدخول لعرض واجهة مستخدم تسجيل الدخول، كما هو موضّح في تنفيذ عملية تسجيل دخول تفاعلية.

بما أنّ حالة اللاعب الذي سجّل الدخول يمكن أن تتغيّر عندما لا يكون النشاط في المقدّمة، ننصحك بالاتّصال بـ silentSignIn() من onResume() طريقة النشاط.

لإجراء عملية تسجيل الدخول بدون إشعار، اتّبِع الخطوات التالية:

1. استخدِم طريقة silentSignIn() في GoogleSignInClient لبدء عملية تسجيل الدخول بدون إشعار. تعرض هذه الاستدعاء كائن Task<GoogleSignInAccount> يحتوي على GoogleSignInAccount إذا تم تسجيل الدخول بدون صوت.
2. يمكنك التعامل مع نجاح أو تعذُّر تسجيل دخول اللاعب من خلال إلغاء OnCompleteListener.
   • إذا نجحت مهمة تسجيل الدخول، احصل على كائن GoogleSignInAccount من خلال استدعاء getResult().
   • إذا لم ينجح تسجيل الدخول، يمكنك إرسال هدف تسجيل الدخول لبدء عملية تسجيل دخول تفاعلية. للحصول على قائمة بأدوات استماع معاودة الاتصال الإضافية التي يمكنك استخدامها، يمكنك الاطّلاع على دليل المطوِّر لواجهة برمجة تطبيقات "مهام Google" وTask مرجع واجهة برمجة التطبيقات.

يعرض مقتطف الرمز التالي طريقة تسجيل الدخول بدون صوت في تطبيقك:

private void signInSilently() {
  GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
  GoogleSignInAccount account = GoogleSignIn.getLastSignedInAccount(this);
  if (GoogleSignIn.hasPermissions(account, signInOptions.getScopeArray())) {
    // Already signed in.
    // The signed in account is stored in the 'account' variable.
    GoogleSignInAccount signedInAccount = account;
  } else {
    // Haven't been signed-in before. Try the silent sign-in first.
    GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOptions);
    signInClient
        .silentSignIn()
        .addOnCompleteListener(
            this,
            new OnCompleteListener<GoogleSignInAccount>() {
              @Override
              public void onComplete(@NonNull Task<GoogleSignInAccount> task) {
                if (task.isSuccessful()) {
                  // The signed in account is stored in the task's result.
                  GoogleSignInAccount signedInAccount = task.getResult();
                } else {
                  // Player will need to sign-in explicitly using via UI.
                  // See [sign-in best practices](http://developers.google.com/games/services/checklist) for guidance on how and when to implement Interactive Sign-in,
                  // and [Performing Interactive Sign-in](http://developers.google.com/games/services/android/signin#performing_interactive_sign-in) for details on how to implement
                  // Interactive Sign-in.
                }
              }
            });
  }
}

@Override
protected void onResume() {
  super.onResume();
  signInSilently();
}

إذا تعذّرت محاولة تسجيل الدخول بدون إشعار، يمكنك الاتصال برقم getException() للحصول على ApiException مع رمز الحالة المفصّل. يشير رمز الحالة CommonStatusCodes.SIGN_IN_REQUIRED إلى أنّ المشغّل يحتاج إلى اتخاذ إجراء صريح لتسجيل الدخول. في هذه الحالة، يجب أن يؤدي تطبيقك إلى بدء عملية تسجيل دخول تفاعلية كما هو موضّح في القسم التالي.

إجراء عملية تسجيل دخول تفاعلية

لتسجيل الدخول من خلال تفاعل اللاعب، يجب أن يطلق تطبيقك نية تسجيل الدخول. في حال نجاح عملية تسجيل الدخول، تعرِض Google Sign-In API واجهة مستخدم تطلب من اللاعب إدخال بيانات الاعتماد لتسجيل الدخول. يعمل هذا الأسلوب على تبسيط عملية تطوير التطبيق، لأنّ نشاط تسجيل الدخول يتعامل مع سيناريوهات مثل الحاجة إلى تحديث خدمات Google Play أو عرض طلبات الموافقة نيابةً عن تطبيقك. يتم عرض النتيجة من خلال دالّة callback الخاصة بالاستدعاء onActivityResult.

لإجراء تسجيل الدخول بشكل تفاعلي، اتبع الخطوات التالية:

1. اتصل بـ getSigninIntent() على GoogleSignInClient للحصول على نية تسجيل الدخول، ثم اتصل بـ startActivity() وأدخِل هذه النية. يوضّح مقتطف الرمز البرمجي التالي كيفية بدء عملية تسجيل دخول تفاعلية في تطبيقك:

   private void startSignInIntent() {
     GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
         GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
     Intent intent = signInClient.getSignInIntent();
     startActivityForResult(intent, RC_SIGN_IN);
   }

2. في دالة onActivityResult() المخصّصة لمعاودة الاتصال، يمكنك معالجة النتيجة من النية التي تم إرجاعها.

   • إذا كانت نتيجة تسجيل الدخول ناجحة، احصل على عنصر GoogleSignInAccount من GoogleSignInResult.
   • إذا لم تنجح نتيجة تسجيل الدخول، عليك التعامل مع خطأ تسجيل الدخول (على سبيل المثال، من خلال عرض رسالة خطأ في تنبيه). يعرض مقتطف الرمز التالي طريقة تعامل تطبيقك مع نتائج تسجيل الدخول إلى المشغّل:

   @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();
       } 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();
       }
     }
   }

استرداد معلومات اللاعب

لا يحتوي GoogleSignInAccount الذي تعرضه Google Sign-In API على أي معلومات متعلقة باللاعب. إذا كانت لعبتك تستخدم معلومات اللاعب، مثل الاسم المعروض للّاعب والرقم التعريفي للّاعب، يمكنك اتّباع هذه الخطوات لاسترداد هذه المعلومات.