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

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

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

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

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

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

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

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

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

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

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

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