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

استخدم الخطوات الواردة في هذا الدليل لتنفيذ واجهات برمجة تطبيقات الأصدقاء في شفرة لعبة جافا.

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

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

  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" نية عرض بحيث يمكن للمستخدم مقارنة نفسه بالملف الشخصي للاعب.
  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);
          // ...
        }});