يوضّح هذا الدليل كيفية استخدام واجهات برمجة التطبيقات الخاصة بـ الأصدقاء في "استوديو Android".
تحميل قائمة الأصدقاء
يمكنك استرداد وعرض (في اللعبة) قائمة باللاعبين الذين هم أصدقاء للمستخدم الحالي. بصفتك مستخدمًا، يمكنك التحكّم في الألعاب التي يمكنها الوصول إلى قائمة الأصدقاء. عند استرداد قائمة الأصدقاء، عليك التعامل مع الحالة التي يكون فيها الإذن مطلوبًا. يتم تضمين كل ذلك في واجهة برمجة التطبيقات لجعل طلب الوصول إلى قائمة الأصدقاء واستخدامها بعد ذلك مهمة بسيطة. لتحميل قائمة الأصدقاء، اتّبِع الخطوات التالية:
- استدعِ طريقة
PlayersClient.loadFriends()، وهي مكالمة غير متزامنة تعرض كائنTask. - إذا نجحت المكالمة (سبق أن منح المستخدم إذن الوصول إلى قائمة الأصدقاء
)، تعرض "خدمات ألعاب Google Play" عنصرًا مشروحًا
PlayerBufferيمثّل أصدقاء المستخدم. إذا كان على اللاعب منح إذن الوصول إلى قائمة الأصدقاء، ستفشل المكالمة وتعرض a
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 ضبط اسم مستعار للاعبين الذين يرسلون دعوات صداقة من داخل لعبتك على "<game-specific-name> من <your-game-name>" (تضيف "ألعاب Play" تلقائيًا عبارة "من <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 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);
// ...
}});