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

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

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

הטמעה של כניסה לשחקן

המחלקה 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() ומעבירים מבין האפשרויות שהגדרתם בשלבים הקודמים. אם השיחה הוא מחזיר מופע של 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().
- אם הכניסה לא הצליחה, תוכלו לשלוח כוונה לכניסה כדי להפעיל תהליך כניסה אינטראקטיבי. לרשימה של מאזינים נוספים לקריאה חוזרת (callback) שבהם אפשר להשתמש, אפשר לעיין ב מדריך למפתחים של 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 מציין שהנגן צריך לבצע פעולה מפורשת כדי להיכנס. במקרה כזה, האפליקציה צריכה להפעיל תהליך כניסה אינטראקטיבי כמו שמתואר בחלק הבא.

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

כדי להיכנס באמצעות אינטראקציה של הנגן, האפליקציה צריכה להפעיל את כוונת הכניסה. אם הפעולה מצליחה, בממשק ה-API לכניסה באמצעות חשבון Google מוצג ממשק משתמש שמבקש מהשחקן להזין את פרטי הכניסה שלו כדי להיכנס. גישה זו מפשטת את תהליך הפיתוח של אפליקציות, מפני שפעילות הכניסה מטפלת תרחישים כמו עדכון Google Play Services או הצגת הודעות לבקשת הסכמה באפליקציה בשם. התוצאה מוחזרת באמצעות 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);
}
```

בonActivityResult() קריאה חוזרת (callback), טיפול בתוצאה מה-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 כפרמטר.
משתמשים ב-methods PlayersClient כדי לטעון באופן אסינכרוני את Player שמכיל את הפרטים של השחקן. לדוגמה, אפשר להתקשר למספר getCurrentPlayer() כדי לטעון את הנגן שמחובר כרגע. אם המשימה מחזירה ApiException עם קוד סטטוס מתוך SIGN_IN_REQUIRED, מעיד על כך שצריך לאמת מחדש את הנגן. לשם כך, התקשרו GoogleSignInClient.getSignInIntent() כדי להיכנס לנגן באופן אינטראקטיבי.
אם המשימה מחזירה את האובייקט Player, אפשר לקרוא ל-methods של אובייקט 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 להפעלת חלונות קופצים בתצוגות במשחק, 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.
        }
      });
}