این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

وارد بازی های اندروید شوید

برای دسترسی به عملکرد سرویس‌های بازی‌های Google Play، بازی شما باید حساب بازیکن واردشده به سیستم را ارائه دهد. اگر پخش کننده احراز هویت نشده باشد، بازی شما ممکن است هنگام برقراری تماس با API های خدمات بازی های 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() فعالیت فراخوانی کنید.

برای انجام ورود به سیستم به صورت بی صدا، این مراحل را دنبال کنید:

برای شروع جریان ورود به GoogleSignInClient بی‌صدا، متد silentSignIn() را در GoogleSignInClient فراخوانی کنید. اگر ورود به سیستم بی‌صدا با موفقیت انجام شود، این تماس یک شی Task<GoogleSignInAccount> را برمی‌گرداند که حاوی یک GoogleSignInAccount است.
با نادیده گرفتن OnCompleteListener موفقیت یا شکست ورود به سیستم بازیکن را مدیریت کنید.
- اگر کار ورود به سیستم با موفقیت انجام شد، شیء GoogleSignInAccount را با فراخوانی getResult() دریافت کنید.
- اگر ورود به سیستم موفقیت آمیز نبود، می توانید یک هدف ورود به سیستم برای راه اندازی یک جریان ورود به سیستم تعاملی ارسال کنید. برای فهرستی از شنوندگان پاسخگوی تماس اضافی که می‌توانید استفاده کنید، به راهنمای برنامه‌نویس Tasks API و مرجع Task API مراجعه کنید.

قطعه کد زیر نشان می دهد که چگونه برنامه شما می تواند ورود به سیستم بی صدا را انجام دهد:

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 یا نمایش را انجام می دهد. درخواست رضایت، از طرف برنامه شما. نتیجه از طریق پاسخ به تماس onActivityResult برگردانده می شود.

برای انجام ورود به سیستم به صورت تعاملی، این مراحل را دنبال کنید:

در GoogleSignInClient با getSigninIntent() تماس بگیرید تا یک intent ورود پیدا کنید، سپس startActivity() فراخوانی کنید و آن intent را ارسال کنید. قطعه کد زیر نشان می دهد که چگونه برنامه شما می تواند یک جریان ورود به سیستم تعاملی راه اندازی کند:
```
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 برمی گرداند حاوی هیچ اطلاعات بازیکنی نیست. اگر بازی شما از اطلاعات بازیکن استفاده می کند، مانند نام نمایشی بازیکن و شناسه بازیکن، می توانید این مراحل را برای بازیابی این اطلاعات دنبال کنید.

با فراخوانی متد getPlayersClient() و ارسال در GoogleSignInAccount به عنوان یک پارامتر، یک شی PlayersClient به دست آورید.
از متدهای PlayersClient برای بارگیری ناهمزمان شی Player که حاوی اطلاعات بازیکن است استفاده کنید. برای مثال، می‌توانید برای بارگیری پخش‌کننده‌ای که در حال حاضر به سیستم وارد شده‌اید getCurrentPlayer() فراخوانی کنید. اگر وظیفه یک ApiException با کد وضعیت SIGN_IN_REQUIRED برمی گرداند، این نشان می دهد که پخش کننده باید دوباره احراز هویت شود. برای انجام این کار، با GoogleSignInClient.getSignInIntent() تماس بگیرید تا به صورت تعاملی وارد بازیکن شوید.
اگر وظیفه با موفقیت شی Player را برگرداند، سپس می توانید متدهای شی Player را برای بازیابی جزئیات خاص پخش کننده فراخوانی کنید (به عنوان مثال getDisplayName() یا getPlayerId() .

ارائه دکمه ورود به سیستم

برای ارائه یک دکمه استاندارد ورود به سیستم گوگل در بازی خود، می توانید از یکی از این روش ها استفاده کنید:

یک com.google.android.gms.common.SignInButton در طرح فعالیت اصلی اضافه کنید. یا
یک دکمه ورود سفارشی مطابق با دستورالعمل‌های نام تجاری Google Sign-In طراحی کنید.

هنگامی که کاربران روی دکمه ورود کلیک می کنند، بازی شما باید با ارسال یک هدف ورود به سیستم، جریان ورود به سیستم را آغاز کند، همانطور که در انجام ورود به سیستم تعاملی توضیح داده شده است.

این قطعه کد نشان می دهد که چگونه می توانید یک دکمه ورود به سیستم در متد 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 می توانید نماهای پاپ آپ را در بازی خود نمایش دهید. به عنوان مثال، بازی شما می تواند یک پاپ آپ "Welcome back" یا "Achievements unlocked" را نمایش دهد. برای اینکه به سرویس‌های بازی‌های 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.
        }
      });
}