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

این راهنما نحوه استفاده از میاناهای برنامه‌سازی کاربردی دوستان را در پروژه‌های «استودیو Android» شرح می‌دهد.

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

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

  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» دارد، می‌توانید این نام‌ها را به نمای نمایه منتقل کنید تا بتوانند در هر دعوت دوستی برای زمینه بیشتر گنجانده شوند.

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

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

اگر بازی نام خودش را برای بازیکنان داشته باشد، این نام‌ها را می‌توان به فراخوانی میانای برنامه‌سازی کاربردی اضافه کرد. این کار به «بازی‌های Play» امکان می‌دهد نام مستعار بازیکنانی را که از داخل بازی شما دعوت دوستی ارسال می‌کنند به «<نام مختص بازی> از <نام بازی شما>» تنظیم کند («بازی‌های Play» به‌طور خودکار «از <نام بازی شما>» را اضافه می‌کند):

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