الأصدقاء في ألعاب 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" تحديد ألقاب اللاعبين الذين يرسلون دعوات صداقة من داخل لعبتك إلى "<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 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);
          // ...
        }});