این راهنما نحوه استفاده از API های دوستان را در پروژه های Android Studio شرح می دهد.
دوستان را بارگیری کنید
می توانید لیستی از بازیکنانی که با کاربر فعلی دوست هستند بازیابی و نمایش دهید (در بازی). به عنوان یک کاربر، می توان کنترل کرد که کدام بازی ها به لیست دوستان دسترسی دارند. هنگامی که لیست دوستان را بازیابی می کنید، باید مواردی را که مجوز لازم است رسیدگی کنید. این همه در API کپسوله شده است تا درخواست دسترسی و متعاقباً استفاده از لیست دوستان به یک کار ساده تبدیل شود. برای بارگیری لیست دوستان، مراحل زیر را دنبال کنید:
- متد
PlayersClient.loadFriends()
را فراخوانی کنید که یک فراخوانی ناهمزمان است که یک شیTask
را برمی گرداند. - اگر تماس با موفقیت انجام شود (کاربر قبلاً اجازه دسترسی به لیست دوستان را داده است)، خدمات بازیهای Google Play یک
PlayerBuffer
حاشیهنویسی را برمیگرداند که نمایانگر دوستان کاربر است. اگر بازیکن نیاز به اجازه دسترسی به لیست دوستان داشته باشد، تماس با
FriendsResolutionRequiredException
ناموفق است. هنوز هیچ دیالوگی نشان داده نشده است.- این استثنا شامل یک
Intent
است که گفتگویی را برای درخواست رضایت از بازیکن راه اندازی می کند. میتوانید بلافاصله اینIntent
برای باز کردن یک گفتگوی رضایت راهاندازی کنید. شما فقط یک بار می توانید از اینIntent
استفاده کنید. اگر نتیجه فعالیت
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 دارد، میتوانید این نامها را به نمای نمایه ارسال کنید تا در دعوتنامههای دوستان برای زمینه اضافی گنجانده شوند.
برای نمایش نمایه بازیکن دیگر، این مراحل را دنبال کنید:
- متد
PlayersClient.getCompareProfileIntent()
را فراخوانی کنید که یک فراخوانی ناهمزمان است که یک شیTask
را برمی گرداند. - اگر تماس با موفقیت انجام شود، خدمات بازیهای Google Play یک Intent برمیگرداند که صفحهای را نشان میدهد که در آن کاربر میتواند خود را با نمایه بازیکن دیگر مقایسه کند.
- برای شروع یک فعالیت از
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);
// ...
}});