این راهنما نحوه استفاده از میاناهای برنامهسازی کاربردی دوستان را در پروژههای «استودیو Android» شرح میدهد.
بار کردن دوستان
میتوانید فهرستی از بازیکنانی را که با کاربر فعلی دوست هستند بازیابی و (در بازی) نمایش دهید. بهعنوان کاربر، میتوانید کنترل کنید کدام بازیها به فهرست دوستان دسترسی داشته باشند. وقتی فهرست دوستان را بازیابی میکنید، باید موردی را که اجازه لازم است مدیریت کنید. همه اینها در میانای برنامهسازی کاربردی گنجانده شده است تا درخواست دسترسی و متعاقباً استفاده از فهرست دوستان به کاری ساده تبدیل شود. برای بار کردن فهرست دوستان، این مراحل را دنبال کنید:
- روش
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» دارد، میتوانید این نامها را به نمای نمایه منتقل کنید تا بتوانند در هر دعوت دوستی برای زمینه بیشتر گنجانده شوند.
برای نمایش نمایه بازیکن دیگر، این مراحل را دنبال کنید:
- روش
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);
// ...
}});
اگر بازی نام خودش را برای بازیکنان داشته باشد، این نامها را میتوان به فراخوانی میانای برنامهسازی کاربردی اضافه کرد. این کار به «بازیهای 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);
// ...
}});