تسجيل الدخول في "ألعاب 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().
   • إذا لم تنجح عملية تسجيل الدخول، يمكنك إرسال طلب تسجيل الدخول لبدء مسار تسجيل دخول تفاعلي. للحصول على قائمة بمستقبلي المكالمات الإضافية التي يمكنك استخدامها، يُرجى الاطّلاع على دليل مطوّري واجهة برمجة التطبيقات Tasks API ومرجع واجهة برمجة التطبيقات 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 على أي معلومات متعلقة باللاعب. إذا كانت لعبتك تستخدِم معلومات اللاعب، مثل الاسم المعروض للاعب ورقم تعريفه، يمكنك اتّباع هذه الخطوات لاسترداد هذه المعلومات.