تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
بعد إيقاف واجهة برمجة التطبيقات
Google Sign-In API
نهائيًا، سنزيل حزمة تطوير البرامج (SDK) لألعاب الإصدار 1 في عام 2026. بعد شباط (فبراير) 2025، لن تتمكّن من نشر
العناوين التي تم دمجها حديثًا مع حزمة تطوير البرامج (SDK) لإصدار 1 من "ألعاب Google Play" على Google Play. ننصحك باستخدام
حزمة تطوير البرامج (SDK) لإصدار 2 من "ألعاب Google Play" بدلاً من ذلك.
على الرغم من أنّ العناوين الحالية التي تم دمجها مع الإصدار 1 من الألعاب السابقة ستظل تعمل لعدة
سنوات، ننصحك بنقل بياناتها إلى الإصدار 2
اعتبارًا من حزيران (يونيو) 2025.
يتناول هذا الدليل استخدام حزمة تطوير البرامج (SDK) لإصدار 1 من "خدمات ألعاب Play". للحصول على معلومات
عن أحدث إصدار من حزمة SDK، يُرجى الاطّلاع على
مستندات الإصدار 2.
اتّبِع الخطوات الواردة في هذا الدليل لتنفيذ واجهات برمجة تطبيقات "الأصدقاء" في رمز لعبة Java.
تحميل الأصدقاء
يمكنك استرداد قائمة باللاعبين الذين هم أصدقاء
للمستخدم الحالي وعرضها (في اللعبة). بصفتك مستخدمًا، يمكنك التحكّم في الألعاب التي يمكنها
الوصول إلى قائمة الأصدقاء. عند استرداد قائمة الأصدقاء، عليك معالجة
الحالة التي يكون فيها الإذن مطلوبًا. يتم تضمين كل هذه الإجراءات في واجهة برمجة التطبيقات لجعل طلب الوصول إلى قائمة الأصدقاء واستخدامها بعد ذلك مهمة سهلة. لتحميل قائمة الأصدقاء، اتّبِع الخطوات التالية:
إذا تمكّنت من إجراء المكالمة بنجاح (سبق أن منَح المستخدم الإذن بالوصول إلى قائمة الأصدقاء)، ستُعرِض "خدمات ألعاب Google Play" ملفًا شخصيًا مُشارَكًا
PlayerBuffer
يمثّل أصدقاء المستخدم.
إذا كان اللاعب بحاجة إلى منح الإذن بالوصول إلى قائمة الأصدقاء، ستتعذّر المكالمة مع رمز الخطأ
a
FriendsResolutionRequiredException.
لم يتم عرض أي مربّعات حوار حتى الآن.
يحتوي هذا الاستثناء على Intent يؤدي إلى عرض مربّع حوار لطلب موافقة
المشغّل. يمكنك تشغيل هذا Intent على الفور لفتح مربع حوار
الموافقة. يمكنك استخدام هذا Intent مرة واحدة فقط.
إذا كانت نتيجة نشاط "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(newOnSuccessListener<AnnotatedData<PlayerBuffer>>(){@OverridepublicvoidonSuccess(AnnotatedData<PlayerBuffer>data){PlayerBufferplayerBuffer=data.get();// ...}).addOnFailureListener(exception->{if(exceptioninstanceofFriendsResolutionRequiredException){PendingIntentpendingIntent=((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. */@OverridepublicvoidonActivityResult(intrequestCode,intresult,Intentdata){if(requestCode==SHOW_SHARING_FRIENDS_CONSENT){if(result==Activity.RESULT_OK){// We got consent from the user to access their friends. Retry loading the friendscallLoadFriends();}else{// User did not grant consent.}}}
عرض الملف الشخصي للاعب آخر
يمكنك عرض ملف شخصي للاعب آخر على تطبيق "ألعاب Play" من
داخل لعبتك. تتيح طريقة العرض هذه للاعبين إرسال دعوات صداقة وقبولها
للاعب الذي تتم مشاهدته. لا يتطلب هذا العرض الوصول إلى قائمة الأصدقاء. بالإضافة إلى ذلك، إذا كانت لعبتك تتضمّن أسماء لاعبين منفصلة
عن الأسماء التعريفية للاعبين في "ألعاب Play"، يمكنك إرسال هذه الأسماء إلى عرض الملف الشخصي
حتى يمكن تضمينها في أي دعوات أصدقاء لتوفير سياق إضافي.
في حال نجاح الطلب، تعرض "خدمات ألعاب Google Play" رمز تشغيل يؤدي إلى شاشة يمكن للمستخدم من خلالها مقارنة نفسه بملف شخصي للاعب آخر.
استخدِم الرمز Intent من الخطوة السابقة لبدء نشاط.
// Retrieve and launch an Intent to show a player profile within the game.Games.getPlayersClient(this,GoogleSignIn.getLastSignedInAccount(this)).getCompareProfileIntent(otherPlayerId).addOnSuccessListener(newOnSuccessListener<Intent>(){@OverridepublicvoidonSuccess(Intentintent){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(newOnSuccessListener<Intent>(){@OverridepublicvoidonSuccess(Intentintent){startActivityForResult(intent,RC_SHOW_PROFILE);// ...}});
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Integrate the Friends APIs (Java)\n\nFollowing the deprecation of the\n[Google Sign-In](https://android-developers.googleblog.com/2024/09/streamlining-android-authentication-credential-manager-replaces-legacy-apis.html)\nAPI, we are removing the games v1 SDK in 2026. After February 2025, you will be unable to publish\ntitles that are newly integrated with games v1 SDK, on Google Play. We recommend that you use the\ngames v2 SDK instead. \n\nWhile existing titles with the previous games v1 integrations continue to function for a\ncouple of years, you are encouraged to\n[migrate to v2](/games/pgs/android/migrate-to-v2)\nstarting June 2025. \n\nThis guide is for using the Play Games Services v1 SDK. For information\non the latest SDK version, see the\n[v2 documentation](/games/pgs/android/friends).\n\nUse the steps in this guide to implement the Friends APIs in your Java game code.\n\nLoad friends\n------------\n\nYou can retrieve and display (in the game) a list of players who are friends\nwith the current user. As a user, it is possible to control which games have\naccess to the friends list. When you retrieve the friends list, you must handle\nthe case where permission is required. This is all encapsulated in the API to\nmake requesting access and subsequently using the friends list a straightforward\ntask. To load the friends list, follow these steps:\n\n1. Call the [`PlayersClient.loadFriends()`](https://developers.google.com/android/reference/com/google/android/gms/games/PlayersClient#loadFriends(int,%20boolean)) method, which is an asynchronous call returning a [`Task`](https://developers.google.com/android/reference/com/google/android/gms/tasks/Task) object.\n2. If the call is successful (the user already granted access to the friends list), Google Play Games Services returns an annotated [`PlayerBuffer`](https://developers.google.com/android/reference/com/google/android/gms/games/PlayerBuffer) that represents the user's friends.\n3. If the player needs to grant access to the friends list, the call fails with\n a\n [`FriendsResolutionRequiredException`](https://developers.google.com/android/reference/com/google/android/gms/games/FriendsResolutionRequiredException).\n No dialogs are shown yet.\n\n 1. This exception contains an `Intent` that triggers a dialog to ask the player for consent. You can launch this `Intent` immediately to open a consent dialog. You can only use this `Intent` once.\n 2. If the result of the `Intent`'s activity is `Activity.RESULT_OK`, then\n consent was granted. Call `loadFriends()` again to return the friends\n list. If the result is `Activity.RESULT_CANCELLED`, the user did\n not consent and `loadFriends()` will continue to return\n `FriendsResolutionRequiredException`.\n\n | **Note:** If you call `loadFriends()` from your server and determine that you need to request consent, you need to call `loadFriends()` again from your game client. This second call won't succeed, but it will provide you the `Intent` required to show the consent dialog.\n\nThe following code shows how to implement loading the friends list: \n\n // Attempt loading friends.\n // Register a success listener to handle the successfully loaded friends list.\n // Register a failure listener to handle asking for permission to access the list.\n Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))\n .loadFriends(PAGE_SIZE, /* forceReload= */ false)\n .addOnSuccessListener(\n new OnSuccessListener\u003cAnnotatedData\u003cPlayerBuffer\u003e\u003e() {\n @Override\n public void onSuccess(AnnotatedData\u003cPlayerBuffer\u003e data) {\n PlayerBuffer playerBuffer = data.get();\n // ...\n })\n\n .addOnFailureListener(\n exception -\u003e {\n if (exception instanceof FriendsResolutionRequiredException) {\n PendingIntent pendingIntent =\n ((FriendsResolutionRequiredException) task.getException())\n .getResolution();\n parentActivity.startIntentSenderForResult(\n pendingIntent.getIntentSender(),\n /* requestCode */ SHOW_SHARING_FRIENDS_CONSENT,\n /* fillInIntent */ null,\n /* flagsMask */ 0,\n /* flagsValues */ 0,\n /* extraFlags */ 0,\n /* options */ null);\n }\n });\n return;\n }\n\nThe following code shows how to handle the result from the request for consent: \n\n /** Handle the activity result from the request for consent. */\n @Override\n public void onActivityResult(int requestCode, int result, Intent data) {\n if (requestCode == SHOW_SHARING_FRIENDS_CONSENT) {\n if (result == Activity.RESULT_OK) {\n // We got consent from the user to access their friends. Retry loading the friends\n callLoadFriends();\n } else {\n // User did not grant consent.\n }\n }\n }\n\nView another player's profile\n-----------------------------\n\nYou can display a view of another player's Play Games profile from\nwithin your game. This view allows players to send and accept friend invitations\nfor the player being viewed. This view does not require access to the friends\nlist. Additionally, if your game has its own concept of player names separate\nfrom Play Games Gamer IDs, you can pass these along to the profile view\nso that they can be included in any friend invitations for additional context.\n\nTo show another player's profile, follow these steps:\n\n1. Call the [`PlayersClient.getCompareProfileIntent()`](https://developers.google.com/android/reference/com/google/android/gms/games/PlayersClient) method, which is an asynchronous call returning a [`Task`](https://developers.google.com/android/reference/com/google/android/gms/tasks/Task) object.\n2. If the call is successful, Google Play Games Services returns an Intent that will display a screen where the user can compare themselves against another player's profile.\n3. Use the `Intent` from the previous step to start an activity.\n\n // Retrieve and launch an Intent to show a player profile within the game.\n Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))\n .getCompareProfileIntent(otherPlayerId)\n .addOnSuccessListener(new OnSuccessListener\u003cIntent\u003e() {\n @Override\n public void onSuccess(Intent intent) {\n startActivityForResult(intent, RC_SHOW_PROFILE);\n // ...\n }});\n\nIf the game has its own name for players, these can be added to the API call.\nThis enables Play Games to set the nickname of players who send friend\ninvitations from within your game to \"\\\u003cgame-specific-name\\\u003e from\n\\\u003cyour-game-name\\\u003e\" (Play Games automatically appends \"from\n\\\u003cyour-game-name\\\u003e\"): \n\n // Show a player profile within the game, with additional hints containing the\n // game-specific names for both players.\n // - otherPlayerId is the Play Games playerId of the player to view.\n // - otherPlayerInGameName is the game-specific name of the player being viewed.\n // - currentPlayerInGameName is the game-specific name of the player who is signed\n // in. Hence if the player sends an invitation to the profile they are viewing,\n // their game-specific name can be included.\n Games.PlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))\n .getCompareProfileIntentWithAlternativeNameHints(otherPlayerId, otherPlayerInGameName, currentPlayerInGameName)\n .addOnSuccessListener(new OnSuccessListener\u003cIntent\u003e() {\n @Override\n public void onSuccess(Intent intent) {\n startActivityForResult(intent, RC_SHOW_PROFILE);\n // ...\n }});"]]