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

يمكنك الحصول على كائن 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.
        }
      });
}