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