تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

أنشئ عنصر تسجيل دخول من خلال عنصر GoogleSignInOptions ، كما هو موضّح في مقتطف الرمز البرمجي التالي. في GoogleSignInOptions.Builder لضبط عملية تسجيل الدخول، عليك تحديد GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN.
```
GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
```
إذا كنت تريد استخدام رمز SnapshotsClient، أضِف .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS) إلى GoogleSignInOptions.Builder كما هو موضّح في مقتطف الرمز البرمجي التالي:
```
GoogleSignInOptions  signInOptions =
    new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
        .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS)
        .build();
```
تحذير: لا تطلب أي نطاقات أخرى أو بيانات ملف شخصي على Google ما لم يكن ذلك ضروريًا لحالة الاستخدام. ويؤدي أي نطاق آخر إلى تعذُّر تسجيل الدخول بدون إشعار في المرة الأولى، باستثناء المستخدمين الذين سبق لهم تسجيل الدخول بنجاح على جهاز مختلف.
استخدِم طريقة GoogleSignIn.getClient() وأدخِل الخيارات التي ضبطتها في الخطوات السابقة. إذا كان الطلب ناجحًا، تعرض Google Sign-In API مثيلًا لمحاولة تسجيل الدخول باستخدام GoogleSignInClient.

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

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

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

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

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

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

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

استخدِم طريقة silentSignIn() في GoogleSignInClient لبدء عملية تسجيل الدخول بدون إشعار. تعرض هذه الاستدعاء كائن Task<GoogleSignInAccount> يحتوي على GoogleSignInAccount إذا تم تسجيل الدخول بدون صوت.
يمكنك التعامل مع نجاح أو تعذُّر تسجيل دخول اللاعب من خلال إلغاء 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.

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

اتصل بـ 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);
}
```

في دالة 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 على أي معلومات متعلقة باللاعب. إذا كانت لعبتك تستخدم معلومات اللاعب، مثل الاسم المعروض للّاعب والرقم التعريفي للّاعب، يمكنك اتّباع هذه الخطوات لاسترداد هذه المعلومات.

ملاحظة: يجب عدم تخزين معرّف اللاعب الذي يتم إرجاعه من حزمة تطوير البرامج (SDK) لنظام التشغيل Android في

احصل على عنصر PlayersClient من خلال استدعاء الطريقة getPlayersClient()، وإدخال GoogleSignInAccount كمَعلمة.
استخدِم طرق PlayersClient لتحميل عنصر Player الذي يحتوي على معلومات اللاعب بشكل غير متزامن. على سبيل المثال، يمكنك طلب getCurrentPlayer() لتحميل المشغّل الذي سجّلت الدخول إليه حاليًا. إذا عرضت المهمة رمز ApiException مع رمز الحالة SIGN_IN_REQUIRED، يشير ذلك إلى أنّه يجب إعادة المصادقة على المشغّل. لإجراء ذلك، اتصل بالرقم GoogleSignInClient.getSignInIntent() لتسجيل دخول اللاعب بشكل تفاعلي.
إذا عرضت المهمة العنصر Player بنجاح، يمكنك بعد ذلك استدعاء طرق العنصر Player لاسترداد تفاصيل محدّدة عن اللاعب (على سبيل المثال، getDisplayName() أو getPlayerId()).

لتوفير زر تسجيل الدخول العادي إلى Google في لعبتك، يمكنك استخدام إحدى الطرق التالية:

تضمين com.google.android.gms.common.SignInButton في تنسيق النشاط الرئيسي
تصميم زر تسجيل دخول مخصّص وفقًا لإرشادات علامة Google التجارية

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

يوضّح مقتطف الرمز هذا كيفية إضافة زر تسجيل الدخول في طريقة onCreate() لنشاطك.

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_sign_in);
  findViewById(R.id.sign_in_button).setOnClickListener(this);
  findViewById(R.id.sign_out_button).setOnClickListener(this);
}

يوضِّح مقتطف الرمز البرمجي التالي كيفية إرسال نية تسجيل الدخول عندما ينقر المستخدم على زر تسجيل الدخول.

@Override
public void onClick(View view) {
  if (view.getId() == R.id.sign_in_button) {
    // start the asynchronous sign in flow
    startSignInIntent();
  } else if (view.getId() == R.id.sign_out_button) {
    // sign out.
    signOut();
    // show sign-in button, hide the sign-out button
    findViewById(R.id.sign_in_button).setVisibility(View.VISIBLE);
    findViewById(R.id.sign_out_button).setVisibility(View.GONE);
  }
}

عرض النوافذ المنبثقة للألعاب

يمكنك عرض طرق عرض النافذة المنبثقة في لعبتك باستخدام فئة GamesClient. على سبيل المثال، يمكن أن تعرِض لعبتك نافذة منبثقة بعنوان "مرحبًا بك مجددًا" أو "تم تحقيق الإنجازات". للسماح لـ "خدمات ألعاب Google Play" بعرض النوافذ المنبثقة في طرق العرض في لعبتك، يمكنك استدعاء الأسلوب setViewForPopups(). يمكنك تخصيص مكان ظهور النافذة المنبثقة على الشاشة بشكل أكبر من خلال الاتصال بالرقم setGravityForPopups().

تسجيل خروج اللاعب

يتم الخروج من الحساب من خلال استدعاء الطريقة signOut() في GoogleSignInClient.

private void signOut() {
  GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
      GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
  signInClient.signOut().addOnCompleteListener(this,
      new OnCompleteListener<Void>() {
        @Override
        public void onComplete(@NonNull Task<Void> task) {
          // at this point, the user is signed out.
        }
      });
}