בעקבות הוצאה משימוש של Google Sign-In API, אנחנו מסירים את ה-SDK בגרסה Games v1 בשנת 2026. אחרי פברואר 2025, לא תהיה לך אפשרות לפרסם ב-Google Play משחקים ששולבו לאחרונה עם ה-SDK בגרסה Games v1. מומלץ להשתמש ב-SDK בגרסה Games v2.
משחקים קיימים עם שילובים קודמים של Games v1 ימשיכו לפעול למשך כמה שנים, אבל מומלץ לעבור לגרסה 2 החל מיוני 2025.
המדריך הזה מיועד לשימוש ב-Play Games Services SDK בגרסה 1. מידע על גרסת ה-SDK העדכנית זמין במאמרי העזרה בנושא גרסה 2.
במדריך הזה מוסבר איך להטמיע את ממשקי ה-API של Friends בקוד המשחק שלכם ב-Java.
טעינת החברים
אפשר לאחזר ולהציג (במשחק) רשימה של שחקנים שהם חברים של המשתמש הנוכחי. כמשתמשים, אתם יכולים לקבוע לאילו משחקים תהיה גישה לרשימת החברים. כשמאחזרים את רשימת החברים, צריך לטפל במקרים שבהם נדרשת הרשאה. הכול כלול ב-API כדי שהבקשה לגישה ובהמשך השימוש ברשימת החברים יהיו פשוטים. כדי לטעון את רשימת החברים:
- מבצעים קריאה ל-method
PlayersClient.loadFriends()
, שהיא קריאה אסינכרונית שמחזירה אובייקטTask
. - אם השיחה תתבצע בהצלחה (המשתמש כבר העניק גישה לרשימת החברים), שירותי Google Play Games יחזירו
PlayerBuffer
עם הערות שמייצגות את החברים של המשתמש. אם השחקן צריך לתת גישה לרשימת החברים, הקריאה תיכשל עם
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(
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 Games מתוך המשחק. בתצוגה הזו השחקנים יכולים לשלוח הזמנות להיות חברים ולקבל הזמנות כאלה מהשחקן שמוצג. התצוגה הזו לא דורשת גישה לרשימת החברים. בנוסף, אם במשחק יש מושג משלו של שמות שחקנים, ששונה מכינויי הגיימר ב-Play Games, אפשר להעביר את השמות האלה לתצוגת הפרופיל כדי שייכללו בהזמנות לחברים ויוסיפו הקשר.
כדי להציג את הפרופיל של שחקן אחר:
- מבצעים קריאה ל-method
PlayersClient.getCompareProfileIntent()
, שהיא קריאה אסינכרונית שמחזירה אובייקטTask
. - אם הקריאה תתבצע בהצלחה, שירותי Google Play Games יחזירו Intent שיציג מסך שבו המשתמש יוכל להשוות את עצמו לפרופיל של שחקן אחר.
- משתמשים ב
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);
// ...
}});
אם למשחק יש שם משלו לשחקנים, אפשר להוסיף אותו לקריאה ל-API. ההגדרה הזו מאפשרת ל-Play Games להגדיר את הכינוי של שחקנים ששולחים הזמנות לחברות מתוך המשחק שלכם ל'<שם ספציפי למשחק> מ<שם המשחק שלכם>' (Play Games מוסיף אוטומטית את 'מ<שם המשחק שלכם>'):
// 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);
// ...
}});