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

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

پس از منسوخ شدن رابط برنامه‌نویسی کاربردی ورود گوگل (Google Sign-In API)، ما در سال ۲۰۲۶ کیت توسعه نرم‌افزاری بازی‌ها نسخه ۱ (games v1 SDK) را حذف خواهیم کرد. پس از فوریه ۲۰۲۵، شما قادر به انتشار عناوینی که به تازگی با کیت توسعه نرم‌افزاری بازی‌ها نسخه ۱ (games v1 SDK) ادغام شده‌اند، در گوگل پلی نخواهید بود. توصیه می‌کنیم به جای آن از کیت توسعه نرم‌افزاری بازی‌ها نسخه ۲ (games v2 SDK) استفاده کنید.
در حالی که عناوین موجود با بازی‌های قبلی نسخه ۱ ادغام‌شده تا چند سال دیگر به کار خود ادامه می‌دهند، توصیه می‌شود از ژوئن ۲۰۲۵ به نسخه ۲ مهاجرت کنید .
این راهنما برای استفاده از SDK نسخه ۱ سرویس بازی‌های Play Games Services است. برای اطلاعات بیشتر در مورد آخرین نسخه SDK، به مستندات نسخه ۲ مراجعه کنید.

برای دسترسی به قابلیت‌های خدمات بازی‌های گوگل پلی، بازی شما باید حساب کاربری بازیکن وارد شده را ارائه دهد. اگر بازیکن احراز هویت نشود، ممکن است بازی شما هنگام فراخوانی APIهای خدمات بازی‌های گوگل پلی با خطا مواجه شود. این مستندات نحوه پیاده‌سازی یک تجربه ورود بدون مشکل در بازی شما را شرح می‌دهد.

پیاده‌سازی ورود بازیکن

کلاس 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();
```
احتیاط: هیچ محدوده یا اطلاعات پروفایل گوگل دیگری را درخواست نکنید، مگر اینکه برای مورد استفاده شما ضروری باشند. هر محدوده دیگری باعث می‌شود اولین ورود بی‌صدا با شکست مواجه شود، به جز برای کاربرانی که قبلاً با موفقیت در دستگاه دیگری وارد سیستم شده‌اند.
متد GoogleSignIn.getClient() را فراخوانی کنید و گزینه‌هایی را که در مراحل قبلی پیکربندی کرده‌اید، به آن ارسال کنید. اگر فراخوانی موفقیت‌آمیز باشد، API ورود به سیستم گوگل (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 موفقیت یا شکست ورود بازیکن را مدیریت کنید.
- اگر عملیات ورود به سیستم موفقیت‌آمیز بود، با فراخوانی getResult() شیء GoogleSignInAccount را دریافت کنید.
- اگر ورود به سیستم موفقیت‌آمیز نبود، می‌توانید یک هدف ورود به سیستم ارسال کنید تا یک جریان ورود به سیستم تعاملی راه‌اندازی شود. برای فهرستی از شنونده‌های فراخوانی اضافی که می‌توانید استفاده کنید، به راهنمای توسعه‌دهندگان API وظایف و مرجع 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 نشان می‌دهد که بازیکن باید اقدام صریحی برای ورود به سیستم انجام دهد. در این حالت، برنامه شما باید یک جریان ورود تعاملی را همانطور که در بخش بعدی توضیح داده شده است، راه‌اندازی کند.

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

اگر نتیجه ورود موفقیت‌آمیز بود، شیء 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 که API ورود به سیستم گوگل برمی‌گرداند، حاوی هیچ اطلاعات بازیکنی نیست. اگر بازی شما از اطلاعات بازیکن، مانند نام نمایشی و شناسه بازیکن، استفاده می‌کند، می‌توانید این مراحل را برای بازیابی این اطلاعات دنبال کنید.

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

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

یک com.google.android.gms.common.SignInButton در طرح‌بندی فعالیت اصلی قرار دهید؛ یا
یک دکمه ورود سفارشی مطابق با دستورالعمل‌های برندسازی ورود به سیستم گوگل طراحی کنید.

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

این قطعه کد نشان می‌دهد که چگونه می‌توانید یک دکمه ورود به سیستم را در متد onCreate() برای activity خود اضافه کنید.

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

وارد بازی های اندروید شوید با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

پیاده‌سازی ورود بازیکن

بررسی کنید که آیا بازیکن قبلاً وارد سیستم شده است یا خیر

ورود بی‌صدا (Silent Sign-in) را انجام دهید

ورود تعاملی را انجام دهید

بازیابی اطلاعات بازیکن

دکمه ورود به سیستم را فراهم کنید

نمایش پاپ‌آپ‌های بازی

بازیکن را از سیستم خارج کنید

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