الأصدقاء في ألعاب 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" من داخل لعبتك. تتيح هذه الصفحة للاعبين إرسال دعوات صداقة وقبولها للاعب الذي تتم مشاهدة ملفه الشخصي. لا يتطلّب هذا العرض الوصول إلى قائمة الأصدقاء. بالإضافة إلى ذلك، إذا كانت لعبتك تتضمّن مفهومًا خاصًا لأسماء اللاعبين يختلف عن أسماء اللاعبين التعريفية في &quot;ألعاب Play&quot;، يمكنك نقل هذه الأسماء إلى عرض الملف الشخصي لتضمينها في أي دعوات صداقة للحصول على سياق إضافي.

لعرض الملف الشخصي لمستخدم آخر، اتّبِع الخطوات التالية:

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