دوستان در بازی های اندروید

این راهنما نحوه استفاده از API های دوستان را در پروژه های Android Studio شرح می دهد.

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

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

  1. متد PlayersClient.loadFriends() را فراخوانی کنید که یک فراخوانی ناهمزمان است که یک شی Task را برمی گرداند.
  2. اگر تماس با موفقیت انجام شود (کاربر قبلاً اجازه دسترسی به لیست دوستان را داده است)، خدمات بازی‌های Google Play یک 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.
PlayGames.getPlayersClient(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 بازیکن دیگری را از داخل بازی خود نمایش دهید. این نما به بازیکنان اجازه می‌دهد تا دعوت‌نامه‌های دوستان را برای بازیکنی که در حال مشاهده است ارسال و قبول کنند. این نما نیازی به دسترسی به لیست دوستان ندارد. علاوه بر این، اگر بازی شما مفهوم خاص خود را از نام بازیکنان جدا از شناسه‌های بازیکن Play Games دارد، می‌توانید این نام‌ها را به نمای نمایه ارسال کنید تا در دعوت‌نامه‌های دوستان برای زمینه اضافی گنجانده شوند.

برای نمایش نمایه بازیکن دیگر، این مراحل را دنبال کنید:

  1. متد PlayersClient.getCompareProfileIntent() را فراخوانی کنید که یک فراخوانی ناهمزمان است که یک شی Task را برمی گرداند.
  2. اگر تماس با موفقیت انجام شود، خدمات بازی‌های Google Play یک Intent برمی‌گرداند که صفحه‌ای را نشان می‌دهد که در آن کاربر می‌تواند خود را با نمایه بازیکن دیگر مقایسه کند.
  3. برای شروع یک فعالیت از Intent مرحله قبل استفاده کنید. 
// Retrieve and launch an Intent to show a player profile within the game.
PlayGames.getPlayersClient(this)
    .getCompareProfileIntent(otherPlayerId)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});

اگر بازی نام خاص خود را برای بازیکنان دارد، می توان آنها را به فراخوانی API اضافه کرد. این به بازی‌های Play امکان می‌دهد نام مستعار بازیکنانی را که از داخل بازی شما دعوت نامه‌های دوستان ارسال می‌کنند، روی «<game-specific-name> از <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.
PlayGames.PlayersClient(this)
    .getCompareProfileIntentWithAlternativeNameHints(otherPlayerId, otherPlayerInGameName, currentPlayerInGameName)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});