דף זה תורגם על ידי Cloud Translation API.

כניסה לחשבון במשחקי Android

בעקבות הוצאה משימוש של Google Sign-In API, אנחנו מסירים את ה-SDK בגרסה Games v1 בשנת 2026. אחרי פברואר 2025, לא תהיה לך אפשרות לפרסם ב-Google Play משחקים ששולבו לאחרונה עם ה-SDK בגרסה Games v1. מומלץ להשתמש ב-SDK בגרסה Games v2.
פריטים קיימים עם שילובים קודמים של משחקים בגרסה 1 ימשיכו לפעול למשך כמה שנים, אבל מומלץ לעבור לגרסה 2 החל מיוני 2025.
המדריך הזה מיועד לשימוש ב-SDK של Play Games Services בגרסה 1. מידע על גרסת ה-SDK העדכנית זמין במאמרי העזרה בנושא גרסה 2.

כדי לגשת לפונקציונליות של Google Play Games Services, המשחק צריך לספק את החשבון של השחקן המחובר. אם השחקן לא מאומת, יכול להיות שיופיעו שגיאות במשחק כשמתבצעות קריאות לממשקי ה-API של Google Play Games Services. במסמכי התיעוד האלה מוסבר איך להטמיע במשחק חוויית כניסה חלקה.

הטמעת כניסה לנגן

הכיתה GoogleSignInClient היא נקודת הכניסה הראשית לאחזור החשבון של השחקן שמחובר כרגע, ולכניסה של השחקן אם הוא לא נכנס לאפליקציה במכשיר בעבר.

כדי ליצור לקוח כניסה, פועלים לפי השלבים הבאים:

יוצרים לקוח כניסה באמצעות האובייקט GoogleSignInOptions, כמו שמוצג בקטע הקוד הבא. כדי להגדיר את הכניסה לחשבון, צריך לציין את הפרטים הבאים בתוך התג GoogleSignInOptions.Builder: GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN.
```
GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
```
אם רוצים להשתמש ב-SnapshotsClient, צריך להוסיף את .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS) ל-GoogleSignInOptions.Builder, כמו שמוצג בקטע הקוד הבא:
```
GoogleSignInOptions  signInOptions =
    new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
        .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS)
        .build();
```
זהירות: אל תבקשו היקפי הרשאות אחרים או נתוני פרופיל Google, אלא אם הם חיוניים לתרחיש השימוש שלכם. כל היקף אחר יגרום לכניסה השקטה הראשונה להיכשל, למעט משתמשים שכבר נכנסו בהצלחה במכשיר אחר.
מתקשרים לשיטה GoogleSignIn.getClient() ומעבירים את האפשרויות שהגדרתם בשלבים הקודמים. אם השיחה מצליחה, Google Sign-In API מחזיר מופע של GoogleSignInClient.

בדיקה אם השחקן כבר מחובר לחשבון

אפשר לבדוק אם כבר מחוברים לחשבון במכשיר הנוכחי באמצעות GoogleSignIn.getLastSignedInAccount(), ואם כבר ניתנו לחשבון הזה ההרשאות הנדרשות באמצעות GoogleSignIn.hasPermissions(). אם שני התנאים מתקיימים – כלומר, הפונקציה getLastSignedInAccount() מחזירה ערך שאינו null והפונקציה hasPermissions() מחזירה את הערך true – אפשר להשתמש בבטחה בחשבון שמוחזר מהפונקציה getLastSignedInAccount(), גם אם המכשיר במצב אופליין.

אפשר להתקשר אל silentSignIn() כדי לאחזר את החשבון של השחקן שמחובר כרגע, ולנסות לחבר שחקנים בלי להציג ממשק משתמש אם הם התחברו בהצלחה לאפליקציה שלכם במכשיר אחר.

השיטה silentSignIn() מחזירה Task<GoogleSignInAccount>. כשהמשימה מסתיימת, מגדירים את השדה GoogleSignInAccount שהצהרתם עליו קודם לכן לחשבון הכניסה שהמשימה מחזירה כתוצאה, או ל-null, כדי לציין שאין משתמש מחובר.

אם ניסיון הכניסה השקט נכשל, אפשר לשלוח את כוונת הכניסה כדי להציג ממשק משתמש לכניסה, כמו שמתואר במאמר ביצוע כניסה אינטראקטיבית.

מכיוון שהמצב של השחקן המחובר יכול להשתנות כשהפעילות לא ברקע, מומלץ לקרוא ל-silentSignIn() מהשיטה onResume() של הפעילות.

כדי לבצע כניסה שקטה:

מפעילים את השיטה silentSignIn() ב-GoogleSignInClient כדי להתחיל את תהליך הכניסה השקט. הקריאה הזו מחזירה אובייקט Task<GoogleSignInAccount> שמכיל GoogleSignInAccount אם הכניסה השקטה הצליחה.
כדי לטפל בהצלחה או בכישלון של הכניסה לחשבון בנגן, צריך לבטל את ההגדרה של OnCompleteListener.
- אם משימת הכניסה הושלמה בהצלחה, מקבלים את אובייקט GoogleSignInAccount על ידי קריאה ל-getResult().
- אם הכניסה לא הצליחה, אפשר לשלוח כוונת כניסה כדי להפעיל תהליך כניסה אינטראקטיבי. רשימה של מאזינים נוספים לקריאה חוזרת זמינה במדריך למפתחים של Tasks API ובמאמר Task בנושא הפניות ל-API.

קטע הקוד הבא מראה איך האפליקציה יכולה לבצע כניסה שקטה:

private void signInSilently() {
  GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
  GoogleSignInAccount account = GoogleSignIn.getLastSignedInAccount(this);
  if (GoogleSignIn.hasPermissions(account, signInOptions.getScopeArray())) {
    // Already signed in.
    // The signed in account is stored in the 'account' variable.
    GoogleSignInAccount signedInAccount = account;
  } else {
    // Haven't been signed-in before. Try the silent sign-in first.
    GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOptions);
    signInClient
        .silentSignIn()
        .addOnCompleteListener(
            this,
            new OnCompleteListener<GoogleSignInAccount>() {
              @Override
              public void onComplete(@NonNull Task<GoogleSignInAccount> task) {
                if (task.isSuccessful()) {
                  // The signed in account is stored in the task's result.
                  GoogleSignInAccount signedInAccount = task.getResult();
                } else {
                  // Player will need to sign-in explicitly using via UI.
                  // See [sign-in best practices](http://developers.google.com/games/services/checklist) for guidance on how and when to implement Interactive Sign-in,
                  // and [Performing Interactive Sign-in](http://developers.google.com/games/services/android/signin#performing_interactive_sign-in) for details on how to implement
                  // Interactive Sign-in.
                }
              }
            });
  }
}

@Override
protected void onResume() {
  super.onResume();
  signInSilently();
}

אם ניסיון הכניסה השקט נכשל, אפשר להתקשר אל getException() כדי לקבל ApiException עם קוד הסטטוס המפורט. קוד סטטוס CommonStatusCodes.SIGN_IN_REQUIRED מציין שהמשתמש צריך לבצע פעולה מפורשת כדי להיכנס לחשבון. במקרה כזה, האפליקציה צריכה להפעיל תהליך אינטראקטיבי לכניסה לחשבון, כמו שמתואר בקטע הבא.

כדי להיכנס באמצעות אינטראקציה עם השחקן, האפליקציה צריכה להפעיל את כוונת הכניסה. אם הפעולה מצליחה, Google Sign-In API מציג ממשק משתמש שמבקש מהשחקן להזין את פרטי הכניסה שלו כדי להיכנס לחשבון. הגישה הזו מפשטת את פיתוח האפליקציה, כי פעילות הכניסה מטפלת בתרחישים כמו הצורך לעדכן את שירותי Google Play או הצגת בקשות להסכמה, בשם האפליקציה. התוצאה מוחזרת באמצעות הקריאה החוזרת (callback) onActivityResult.

כדי להיכנס באופן אינטראקטיבי, פועלים לפי השלבים הבאים:

מתקשרים אל getSigninIntent() ב-GoogleSignInClient כדי לקבל כוונת כניסה, ואז מתקשרים אל startActivity() ומעבירים את הכוונה הזו. בקטע הקוד הבא אפשר לראות איך האפליקציה יכולה להפעיל תהליך אינטראקטיבי של כניסה לחשבון:
```
private void startSignInIntent() {
  GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
      GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
  Intent intent = signInClient.getSignInIntent();
  startActivityForResult(intent, RC_SIGN_IN);
}
```

ב-callback‏ onActivityResult(), מטפלים בתוצאה מה-intent שהוחזר.

אם הכניסה בוצעה בהצלחה, מקבלים את אובייקט GoogleSignInAccount מ-GoogleSignInResult.
אם הכניסה לא הצליחה, צריך לטפל בשגיאת הכניסה (למשל, על ידי הצגת הודעת שגיאה בהתראה). בקטע הקוד הבא מוצג איך האפליקציה יכולה לטפל בתוצאות של כניסת שחקנים:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  if (requestCode == RC_SIGN_IN) {
    GoogleSignInResult result = Auth.GoogleSignInApi.getSignInResultFromIntent(data);
    if (result.isSuccess()) {
      // The signed in account is stored in the result.
      GoogleSignInAccount signedInAccount = result.getSignInAccount();
    } else {
      String message = result.getStatus().getStatusMessage();
      if (message == null || message.isEmpty()) {
        message = getString(R.string.signin_other_error);
      }
      new AlertDialog.Builder(this).setMessage(message)
          .setNeutralButton(android.R.string.ok, null).show();
    }
  }
}

אחזור מידע על שחקנים

ה-GoogleSignInAccount שמוחזר על ידי Google Sign-In API לא מכיל מידע על השחקן. אם המשחק משתמש בפרטי השחקן, כמו השם המוצג ומזהה השחקן, אפשר לפעול לפי השלבים הבאים כדי לאחזר את הפרטים האלה.

משיגים אובייקט PlayersClient על ידי הפעלת השיטה getPlayersClient() והעברת GoogleSignInAccount כפרמטר.
משתמשים בשיטות PlayersClient כדי לטעון באופן אסינכרוני את אובייקט Player שמכיל את פרטי השחקן. לדוגמה, אפשר להתקשר אל getCurrentPlayer() כדי לטעון את הנגן שאליו מחוברים כרגע. אם המשימה מחזירה את הערך ApiException עם קוד סטטוס של SIGN_IN_REQUIRED, המשמעות היא שצריך לאמת מחדש את הזהות של המשתמש בנגן. כדי לעשות את זה, קוראים ל-GoogleSignInClient.getSignInIntent() כדי שהשחקן או השחקנית ייכנסו באופן אינטראקטיבי.
אם המשימה מחזירה את האובייקט Player, אפשר לקרוא לשיטות של האובייקט Player כדי לאחזר פרטים ספציפיים על השחקן (לדוגמה, getDisplayName() או getPlayerId()).

כדי לספק לחצן כניסה סטנדרטי לחשבון Google במשחק, אפשר להשתמש באחת מהגישות הבאות:

לכלול com.google.android.gms.common.SignInButton בפריסת הפעילות הראשית, או
מעצבים כפתור כניסה בהתאמה אישית לפי ההנחיות למיתוג של כניסה באמצעות חשבון Google.

כשמשתמשים לוחצים על לחצן הכניסה, המשחק צריך להתחיל את תהליך הכניסה על ידי שליחת כוונת כניסה, כפי שמתואר במאמר בנושא ביצוע כניסה אינטראקטיבית.

בקטע הקוד הבא מוצג איך אפשר להוסיף לחצן כניסה בשיטה onCreate() לפעילות.

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_sign_in);
  findViewById(R.id.sign_in_button).setOnClickListener(this);
  findViewById(R.id.sign_out_button).setOnClickListener(this);
}

בקטע הקוד הבא אפשר לראות איך שולחים את כוונת הכניסה כשהמשתמש לוחץ על לחצן הכניסה.

@Override
public void onClick(View view) {
  if (view.getId() == R.id.sign_in_button) {
    // start the asynchronous sign in flow
    startSignInIntent();
  } else if (view.getId() == R.id.sign_out_button) {
    // sign out.
    signOut();
    // show sign-in button, hide the sign-out button
    findViewById(R.id.sign_in_button).setVisibility(View.VISIBLE);
    findViewById(R.id.sign_out_button).setVisibility(View.GONE);
  }
}

הצגת חלונות קופצים של משחקים

אפשר להציג תצוגות קופצות במשחק באמצעות המחלקה GamesClient. לדוגמה, במשחק יכול להופיע חלון קופץ עם הכיתוב 'ברוך שובך' או 'הישגים שנפתחו'. כדי לאפשר ל-Google Play Games Services להציג חלונות קופצים בתצוגות במשחק, צריך לקרוא לשיטה setViewForPopups(). כדי להתאים אישית עוד יותר את המיקום של החלון הקופץ במסך, אפשר להשתמש ב-setGravityForPopups().

יציאה מהחשבון של הנגן

כדי להתנתק, מפעילים את השיטה signOut() ב-GoogleSignInClient.

private void signOut() {
  GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
      GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
  signInClient.signOut().addOnCompleteListener(this,
      new OnCompleteListener<Void>() {
        @Override
        public void onComplete(@NonNull Task<Void> task) {
          // at this point, the user is signed out.
        }
      });
}

כניסה לחשבון במשחקי Android קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

הטמעת כניסה לנגן

בדיקה אם השחקן כבר מחובר לחשבון

ביצוע כניסה שקטה

ביצוע כניסה אינטראקטיבית

אחזור מידע על שחקנים

הוספת כפתור כניסה

הצגת חלונות קופצים של משחקים

יציאה מהחשבון של הנגן

כניסה לחשבון במשחקי Android