تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
استخدِم واجهات برمجة التطبيقات Friends API لدعم وتحسين نظام الأصدقاء الحالي في اللعبة
والأنظمة الاجتماعية الأخرى التي يمكن أن تصل إليها لعبتك. يتيح لك ذلك السماح للاعبين بما يلي:
العثور على أصدقائهم في لعبتك
مقارنة النتائج مع الأصدقاء على لوحات الصدارة
دمج قائمة أصدقائهم في "ألعاب Play" مع قوائم الأصدقاء الحالية داخل الألعاب
تحديد لاعب آخر من خلال نافذة منبثقة لملفه الشخصي داخل اللعبة تعرض هذه النافذة المنبثقة اسمًا بدلاً من اسم اللاعب الحالي، وذلك ليعرف صديقه من هو اللاعب الذي يلعب معه.
الأساسيات
تتيح لك واجهات برمجة التطبيقات هذه تنفيذ الإجراءات التالية:
تحميل الأصدقاء: يمكنك التحقّق مما إذا كان اللاعب قد سمح للّعبة بالوصول إلى
معلومات قائمة الأصدقاء. في حال منح الإذن بالوصول، يمكنك الحصول على قائمة بعناصر Player
المرتبطة بأصدقاء اللاعب الذي سجّل الدخول.
فتح عرض لملف شخصي آخر على تطبيق "ألعاب Play": يمكنك فتح
هذا العرض لعرض الاسم الذي منحه اللاعب الآخر لنفسه. تقدّم طريقة العرض هذه أيضًا عناصر تحكّم لإدارة الصداقات ولن تؤدي إلى إزالة
اللاعب من لعبتك.
توفير عناصر تحكّم للمستخدم: يتوفّر للمستخدم عناصر تحكّم لإدارة كيفية ظهور ملفه الشخصي في "ألعاب Play" للأصدقاء وكيفية ظهور قائمة أصدقائه للألعاب. بالنسبة إلى الوصول إلى قائمة الأصدقاء، يمكن للمستخدم اختيار
منح الإذن بالوصول تلقائيًا لجميع الألعاب أو اختيار
الموافقة على الوصول بشكل فردي لكل لعبة. نتيجةً لذلك، عند تحميل قائمة الأصدقاء،
قد تكون النتيجة هي طلب إعادة الاتصال لعرض طلب الوصول.
استيراد قائمة أصدقاء في "ألعاب Play"
يمكنك استخدام Friends APIs للحصول على قائمة بأصدقاء اللاعبين على "ألعاب Play"
وإضافتهم إلى قائمة الأصدقاء داخل اللعبة.
سيحصل المستخدمون الجدد على قائمة أساسية بالأصدقاء للعب معهم، ويمكن للمستخدمين الحاليين
استيراد أصدقائهم في "ألعاب Play" إلى أي قوائم أصدقاء داخل اللعبة.
ونتيجةً لذلك، سيحظى المستخدمون بأكبر مجموعة ممكنة من اللاعبين للعب معهم أو التنافس معهم.
إضافة أصدقائك في "ألعاب Play" إلى لعبتك
يمكنك إضافة أصدقائك في "ألعاب Play" إلى أي قائمة حالية للأصدقاء داخل اللعبة من خلال
ربط معرّف "ألعاب Play" الخاص بهم بمعلومات اللاعب المقابلة في
قاعدة بياناتك الداخلية. تأكَّد من توفُّر زر يحمل رمز "ألعاب Play" بجانب هؤلاء الأصدقاء، والذي يعرض الملف الشخصي للّاعبين الآخرين عند الضغط عليه،
كي يتمكّن المستخدمون من معرفة هوية الأصدقاء.
عند استخدام قائمة الأصدقاء من خادم خلفية، يجب
تحميلها بأمان
باستخدام واجهة برمجة التطبيقات REST API بدلاً من تمرير نتيجة واجهة برمجة التطبيقات Android API. احرص على استخدام رقم تعريف اللاعب الذي يعرضه الإجراء
players.get(me)
في واجهة برمجة التطبيقات REST API الخاص باللاعب الذي سجّل الدخول حاليًا، لأنّ هذا الرقم سيكون متسقًا
مع رقم التعريف الذي يظهر للّاعبين الآخرين.
إذا لم يتم تخزين قائمة الأصدقاء المحسّنة (ولكن تم استخدامها فقط في وقت
العرض)، لن يكون هناك حاجة إلى إجراء إضافي.
منح إذن الوصول إلى "ألعاب Play"
إذا لم تكن لعبتك تملك إذن الوصول إلى "ألعاب Play"، يمكنك عندها
طلب موافقة المستخدمين عندما يشاهدون قائمة الأصدقاء داخل اللعبة. على سبيل المثال، يمكنك إضافة زر بعنوان استيراد أصدقاء "ألعاب Play"، والذي يطلب من المستخدم الموافقة عند النقر عليه. (احرص على استخدام
شعار "ألعاب Play" على أي زر يشير إلى الخدمة).
عرض الملف الشخصي للاعب آخر
يمكنك السماح للاعب الذي سجّل الدخول بعرض ملف شخصي للاعب آخر على
"ألعاب Play". يتيح ذلك للاعب الذي سجّل الدخول الاطّلاع على الاسم الذي منح إذا لم يكن اللاعبان صديقَين بعد،
سيظهر للاعب الذي سجّل الدخول عناصر التحكّم في إدارة الصداقة في عرض
الملف الشخصي. عند إنشاء صداقات من داخل اللعبة، تكون الأسماء التلقائية
لللاعبَين هي أسماؤهما داخل اللعبة (إذا تم تقديمها). ويتم أيضًا عرض اسم
اللعبة التي بدأت فيها الصداقة.
قوائم الصدارة في وسائل التواصل الاجتماعي
يمكن أيضًا استخدام Friends APIs في قوائم الصداقة. استخدِم هذه الميزة لعرض رتبة اللاعب الحالي بين أصدقائه في "ألعاب Play". يُرجى العِلم أنّه
لا ينطبق ذلك إلا على المستخدمين الذين اختاروا مشاركة هذه المعلومات مع
تطبيقك، وإذا كان المستخدمون أصدقاء في "ألعاب Play". ولتفعيل هذه الميزة، تعرض اللعبة عنصر تحكّم للمستخدم. يستخدم عنصر التحكّم هذا الوسيطة
collection لاختيار طريقة العرض الاجتماعية لقائمة الصدارة. للاطّلاع على مزيد من المعلومات، يمكنك الاطّلاع على القسم المخصص لموضوع قوائم الصدارة العامة والتواصل الاجتماعي.
في حال تنفيذ مجموعة قوائم الصدارة الاجتماعية، قد يؤدي طلب تحميل
نتائج قائمة الصدارة إلى عرض استثناء حلّ يتطلب الموافقة مشابهًا لمحاولة التحميل من
loadFriends().
إذا نفّذت واجهة المستخدم التلقائية التي تقدّمها "ألعاب Play" (مثل
getLeaderboardIntent())،
سيتم تنفيذ ذلك تلقائيًا نيابةً عنك.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Friends\n\nUse the Friends APIs to complement and enhance your existing in-game friends system\nand other social systems your game may access. This lets you enable players to:\n\n- Find their friends in your game.\n\n- Compare scores with their friends on leaderboards.\n\n- Combine the list of their Play Games friends with existing in-game lists of\n friends.\n\n- Identify another player with an in-game profile popup. This popup shows a\n nickname that the current player has given to their friend, so they know who\n they are playing with.\n\nBasics\n------\n\nThese APIs allow you to perform the following actions:\n\n- **Load friends**: You can check if the player has allowed the game to access Friends list information. If access is granted, you can get a list of Player objects corresponding to the friends of the signed-in player.\n- **Launch a view of another player's Play Games profile**: You can open up this view to show the name given to the other player by the signed-in player. This view also offers friendship management controls and won't take the player out of your game.\n- **Provide user controls**: The user has controls to manage how their Play Games profile is visible to friends and how their friends list is visible to games. For friends list access, the user can choose to automatically grant access for all games or they can choose to individually approve access for each game. Consequently, when loading the friends list, the result may be a callback to display a request for access.\n\nImport a Play Games friends list\n--------------------------------\n\nYou can use the Friends APIs to get a list of your players' Play Games\nfriends and add them to your in-game friends list.\n\nNew users will have a starting list of friends to play with, and existing users\ncan import their Play Games friends into any in-game lists of friends.\nAs a result, your users will have the largest possible set of players to play\nwith or compete against.\n| **Note:** If you store any relationships from Play Games, you must regularly check the friends list to ensure that the relationships, and consent to use them, are still valid.\n\n### Add Play Games friends to your game\n\nAdd Play Games friends to any existing in-game friends list by\nassociating their Play Games ID with corresponding player information in\nyour internal database. Make sure you have a button with the Play Games\nicon next to these friends, which shows the other player's profile when pressed,\nso your users can know who the friends are.\n\nWhen using the friends list from a backend server,\n[load it securely](/games/pgs/signin#secure-access)\nusing the REST API rather than passing the result of the Android API. Make sure\nto use the player ID returned by\n[`players.get(me)`](/games/services/web/api/rest/v1/players/get)\nin the REST API for the currently signed-in player, as this will be consistent\nwith the ID seen by other players.\n\nIf the augmented friends list is not stored (but just used at the time of\nviewing), then no additional work is needed.\n\n### Grant Play Games access\n\nIf your game doesn't already have Play Games access, a good time to\nprompt users for their consent is when they view your in-game friends list. For\nexample, you might add a button called **Import Play Games friends**, which\nprompts the user for consent when tapped. (Make sure to use the\nPlay Games logo on any button that mentions the service.)\n\nView another player's profile\n-----------------------------\n\nYou can allow your signed-in player to view another player's\nPlay Games profile. This allows the signed-in player to see the name they\nhave given the other player and whether or not they are already friends, giving\nthem added context about the relationship. If the players are not yet friends,\nthe signed-in player will see friendship management controls on the profile\nview. When friendships are created from within the game, the default names for\nthe two players are their in-game names (if provided). The name of the\ngame where the friendship was initiated is also shown.\n\nSocial leaderboards\n-------------------\n\nThe Friends APIs can also be used for leaderboards. Use this feature to show the\nranking of the current player among their Play Games friends. Note that\nthis only applies to users who have chosen to share this information with your\napplication, and if the users are friends in Play Games. To support this\nfeature, the game exposes a control to the user. This control uses the\n`collection` argument to select the social view of the leaderboard. To learn\nmore, see the section on\n[public and social leaderboards](/games/pgs/leaderboards#public_and_social_leaderboards).\n\nIf you implement the social leaderboards collection, the call to load the\nleaderboard scores may return a consent-required resolution exception similar to\nthat from\n[`loadFriends()`](https://developers.google.com/android/reference/com/google/android/gms/games/PlayersClient#loadFriends(int,%20boolean)).\nIf you implement the default Play Games-provided UI (for example,\n[`getLeaderboardIntent()`](https://developers.google.com/android/reference/com/google/android/gms/games/LeaderboardsClient.html#getLeaderboardIntent(java.lang.String))),\nthen this is handled for you automatically.\n\nNext steps\n----------\n\nBefore you start to use the Friends APIs, do the following:\n\n- Download and review a code sample:\n - [Java](https://github.com/playgameservices/android-basic-samples)\n - [Unity sample app](https://github.com/playgameservices/play-games-plugin-for-unity/tree/master/Samples/SmokeTest) using the [Unity plugin](https://github.com/playgameservices/play-games-plugin-for-unity)\n- Familiarize yourself with the recommendations described in the [Quality Checklist](/games/pgs/quality#friends).\n- Implement the [Friends APIs in a Java client](/games/pgs/android/friends)."]]
