ادغام API های دوستان (جاوا)

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

از مراحل این راهنما برای پیاده‌سازی APIهای Friends در کد بازی جاوای خود استفاده کنید.

دوستان را بارگیری کنید

شما می‌توانید فهرستی از بازیکنانی که با کاربر فعلی دوست هستند را بازیابی و (در بازی) نمایش دهید. به عنوان یک کاربر، می‌توانید کنترل کنید که کدام بازی‌ها به فهرست دوستان دسترسی دارند. هنگام بازیابی فهرست دوستان، باید مواردی را که نیاز به اجازه دارند، مدیریت کنید. همه اینها در API گنجانده شده است تا درخواست دسترسی و متعاقباً استفاده از فهرست دوستان را به یک کار ساده تبدیل کند. برای بارگیری فهرست دوستان، این مراحل را دنبال کنید:

1. متد PlayersClient.loadFriends() را فراخوانی کنید، که یک فراخوانی ناهمزمان است و یک شیء Task را برمی‌گرداند.
2. اگر فراخوانی موفقیت‌آمیز باشد (کاربر قبلاً به لیست دوستان دسترسی داشته باشد)، سرویس‌های بازی‌های گوگل پلی یک PlayerBuffer حاشیه‌نویسی‌شده را برمی‌گردانند که نشان‌دهنده‌ی دوستان کاربر است.

3. اگر بازیکن نیاز به اعطای دسترسی به لیست دوستان داشته باشد، درخواست با خطای FriendsResolutionRequiredException با شکست مواجه می‌شود. هنوز هیچ پنجره‌ی محاوره‌ای نمایش داده نمی‌شود.

   1. این استثنا شامل یک Intent است که یک دیالوگ برای درخواست رضایت از بازیکن ایجاد می‌کند. می‌توانید این Intent فوراً اجرا کنید تا یک دیالوگ رضایت باز شود. فقط می‌توانید یک بار از این Intent استفاده کنید.

   2. اگر نتیجه فعالیت Intent ، Activity.RESULT_OK باشد، پس رضایت داده شده است. تابع loadFriends() را دوباره فراخوانی کنید تا لیست دوستان را برگردانید. اگر نتیجه Activity.RESULT_CANCELLED باشد، کاربر رضایت نداده است و loadFriends() همچنان FriendsResolutionRequiredException برمی‌گرداند.

کد زیر نحوه‌ی پیاده‌سازی بارگذاری لیست دوستان را نشان می‌دهد:

// Attempt loading friends.
// Register a success listener to handle the successfully loaded friends list.
// Register a failure listener to handle asking for permission to access the list.
Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .loadFriends(PAGE_SIZE, /* forceReload= */ false)
    .addOnSuccessListener(
        new OnSuccessListener<AnnotatedData<PlayerBuffer>>() {
            @Override
            public void onSuccess(AnnotatedData<PlayerBuffer>  data) {
          PlayerBuffer playerBuffer = data.get();
          // ...
        })

    .addOnFailureListener(
        exception -> {
      if (exception instanceof FriendsResolutionRequiredException) {
        PendingIntent pendingIntent =
            ((FriendsResolutionRequiredException) task.getException())
            .getResolution();
        parentActivity.startIntentSenderForResult(
            pendingIntent.getIntentSender(),
            /* requestCode */ SHOW_SHARING_FRIENDS_CONSENT,
            /* fillInIntent */ null,
            /* flagsMask */ 0,
            /* flagsValues */ 0,
            /* extraFlags */ 0,
            /* options */ null);
     }
   });
 return;
}

کد زیر نحوه مدیریت نتیجه درخواست رضایت را نشان می‌دهد:

/** Handle the activity result from the request for consent. */
@Override
public void onActivityResult(int requestCode, int result, Intent data) {
  if (requestCode == SHOW_SHARING_FRIENDS_CONSENT) {
    if (result == Activity.RESULT_OK) {
      // We got consent from the user to access their friends. Retry loading the friends
      callLoadFriends();
    } else {
      // User did not grant consent.
    }
  }
}

مشاهده پروفایل بازیکن دیگر

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

برای نمایش پروفایل بازیکن دیگر، مراحل زیر را دنبال کنید:

1. متد PlayersClient.getCompareProfileIntent() را فراخوانی کنید، که یک فراخوانی ناهمزمان است و یک شیء Task را برمی‌گرداند.
2. اگر فراخوانی موفقیت‌آمیز باشد، سرویس‌های بازی‌های گوگل پلی یک Intent برمی‌گردانند که صفحه‌ای را نمایش می‌دهد که در آن کاربر می‌تواند خود را با پروفایل بازیکن دیگری مقایسه کند.
3. از Intent مرحله قبل برای شروع یک فعالیت استفاده کنید.

// Retrieve and launch an Intent to show a player profile within the game.
Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .getCompareProfileIntent(otherPlayerId)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});

اگر بازی نام مخصوص به خود را برای بازیکنان دارد، می‌توان این نام‌ها را به فراخوانی API اضافه کرد. این کار Play Games را قادر می‌سازد تا نام مستعار بازیکنانی را که از داخل بازی شما دعوت‌نامه دوستی ارسال می‌کنند، روی "<game-specific-name> from <your-game-name>" تنظیم کند (Play Games به طور خودکار "from <your-game-name>" را اضافه می‌کند):

// Show a player profile within the game, with additional hints containing the
// game-specific names for both players.
// - otherPlayerId is the Play Games playerId of the player to view.
// - otherPlayerInGameName is the game-specific name of the player being viewed.
// - currentPlayerInGameName is the game-specific name of the player who is signed
//   in. Hence if the player sends an invitation to the profile they are viewing,
//   their game-specific name can be included.
Games.PlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .getCompareProfileIntentWithAlternativeNameHints(otherPlayerId, otherPlayerInGameName, currentPlayerInGameName)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});