دمج واجهات برمجة تطبيقات Friends (Java)

اتّبِع الخطوات الواردة في هذا الدليل لتنفيذ واجهات برمجة تطبيقات "الأصدقاء" في رمز لعبتك المكتوب بلغة Java.

تحميل الأصدقاء

يمكنك استرداد قائمة باللاعبين الذين هم أصدقاء للمستخدم الحالي وعرضها (في اللعبة). بصفتك مستخدمًا، يمكنك التحكّم في الألعاب التي يمكنها الوصول إلى قائمة الأصدقاء. عند استرداد قائمة الأصدقاء، يجب عليك التعامل مع الحالة التي يكون فيها الإذن مطلوبًا. يتم تضمين كل هذه الإجراءات في واجهة برمجة التطبيقات لجعل طلب الوصول إلى قائمة الأصدقاء واستخدامها بعد ذلك مهمة سهلة. لتحميل قائمة الأصدقاء، اتبع الخطوات التالية:

  1. استخدِم الطريقة PlayersClient.loadFriends() ، وهي عبارة عن طلب غير متزامن يعرض كائن Task.
  2. إذا تمكّنت من إجراء المكالمة بنجاح (سبق أن منَح المستخدم الإذن بالوصول إلى قائمة الأصدقاء)، ستُعرِض "خدمات ألعاب Google Play" ملفًا شخصيًا مُعلَقًا PlayerBuffer يمثّل أصدقاء المستخدم.

  3. إذا كان اللاعب بحاجة إلى منح الإذن بالوصول إلى قائمة الأصدقاء، ستتعذّر المكالمة مع رمز الخطأ a 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.
Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(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" هدفًا يعرض شاشة يمكن للمستخدم من خلالها مقارنة نفسه بالملف الشخصي للاعب آخر.
  3. استخدِم الرمز Intent من الخطوة السابقة لبدء نشاط.
// Retrieve and launch an Intent to show a player profile within the game.
Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(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 signed
//   in. Hence if the player sends an invitation to the profile they are viewing,
//   their game-specific name can be included.
Games.PlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .getCompareProfileIntentWithAlternativeNameHints(otherPlayerId, otherPlayerInGameName, currentPlayerInGameName)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});