בעקבות הוצאה משימוש של 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 של תמונות מצב שמוצע על ידי שירותי המשחקים של Google Play. ממשקי ה-API נמצאים בחבילות com.google.android.gms.games.snapshot
ו-com.google.android.gms.games
.
לפני שמתחילים
אם עדיין לא עשיתם זאת, כדאי לעיין במושגים בנושא משחקים שמורים.
- חשוב להפעיל תמיכה במשחקים שמורים במשחק ב-Google Play Console.
- מורידים את דוגמת הקוד של המשחקים השמורים מדף הדוגמאות ל-Android ובודקים אותה.
- מומלץ לעיין בהמלצות שמתוארות ברשימת הבדיקה לאיכות.
הורדת לקוח של תמונות מצב
כדי להתחיל להשתמש ב-Snapshots API, המשחק שלכם צריך קודם לקבל אובייקט SnapshotsClient
. כדי לעשות את זה, צריך להפעיל את השיטה Games.getSnapshotsClient()
ולהעביר את הפעילות ואת GoogleSignInAccount
של השחקן הנוכחי. במאמר כניסה למשחקי Android מוסבר איך לאחזר את פרטי חשבון השחקן.
ציון היקף ההרשאות של Drive
ממשק ה-API של התמונות המיידיות מסתמך על Google Drive API לאחסון משחקים שמורים. כדי לגשת ל-Drive API, האפליקציה צריכה לציין את היקף ההרשאה Drive.SCOPE_APPFOLDER
כשיוצרים את לקוח הכניסה לחשבון Google.
דוגמה לאופן ההגדרה בשיטה onResume()
לפעילות הכניסה:
private GoogleSignInClient mGoogleSignInClient; @Override protected void onResume() { super.onResume(); signInSilently(); } private void signInSilently() { GoogleSignInOptions signInOption = new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN) // Add the APPFOLDER scope for Snapshot support. .requestScopes(Drive.SCOPE_APPFOLDER) .build(); GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOption); signInClient.silentSignIn().addOnCompleteListener(this, new OnCompleteListener<GoogleSignInAccount>() { @Override public void onComplete(@NonNull Task<GoogleSignInAccount> task) { if (task.isSuccessful()) { onConnected(task.getResult()); } else { // Player will need to sign-in explicitly using via UI } } }); }
הצגת משחקים שמורים
אפשר לשלב את snapshots API בכל מקום במשחק שבו השחקנים יכולים לשמור או לשחזר את ההתקדמות שלהם. יכול להיות שהמשחק יציג אפשרות כזו בנקודות שמירה או שחזור ייעודיות, או יאפשר לשחקנים לשמור או לשחזר את ההתקדמות בכל שלב.
אחרי שהשחקנים בוחרים באפשרות השמירה או השחזור במשחק שלכם, המשחק יכול להציג מסך שבו השחקנים מתבקשים להזין פרטים למשחק חדש שנשמר או לבחור משחק קיים שנשמר כדי לשחזר אותו.
כדי לפשט את הפיתוח, ה-API של התמונות המיידיות מספק ממשק משתמש (UI) לבחירת משחקים שמורים שמוגדר כברירת מחדל, וניתן להשתמש בו ללא שינויים. ממשק המשתמש של בחירת המשחקים השמורים מאפשר לשחקנים ליצור משחק שמור חדש, לראות פרטים על משחקים שמורים קיימים ולטעון משחקים שמורים קודמים.
כדי להפעיל את ממשק המשתמש של ברירת המחדל של משחקים שמורים:
- מתקשרים אל
SnapshotsClient.getSelectSnapshotIntent()
כדי לקבלIntent
להפעלת ממשק המשתמש של בחירת משחקים שמורים שמוגדר כברירת מחדל. - מתקשרים אל
startActivityForResult()
ומעבירים אתIntent
. אם הקריאה תצליח, ממשק המשתמש של בחירת המשחק השמור יוצג במשחק, יחד עם האפשרויות שציינתם.
דוגמה להפעלת ממשק המשתמש לבחירת משחקים שמורים שמוגדר כברירת מחדל:
private static final int RC_SAVED_GAMES = 9009; private void showSavedGamesUI() { SnapshotsClient snapshotsClient = Games.getSnapshotsClient(this, GoogleSignIn.getLastSignedInAccount(this)); int maxNumberOfSavedGamesToShow = 5; Task<Intent> intentTask = snapshotsClient.getSelectSnapshotIntent( "See My Saves", true, true, maxNumberOfSavedGamesToShow); intentTask.addOnSuccessListener(new OnSuccessListener<Intent>() { @Override public void onSuccess(Intent intent) { startActivityForResult(intent, RC_SAVED_GAMES); } }); }
אם השחקן בוחר ליצור משחק חדש שמור או לטעון משחק שמור קיים,
ממשק המשתמש שולח בקשה ל-Google Play Games Services. אם הבקשה מצליחה, Google Play Games Services מחזיר מידע ליצירה או לשחזור של המשחק השמור באמצעות הקריאה החוזרת onActivityResult()
. המשחק יכול לבטל את הקריאה החוזרת הזו כדי לבדוק אם אירעו שגיאות במהלך הבקשה.
בקטע הקוד הבא מוצגת דוגמה להטמעה של onActivityResult()
:
private String mCurrentSaveName = "snapshotTemp"; /** * This callback will be triggered after you call startActivityForResult from the * showSavedGamesUI method. */ @Override protected void onActivityResult(int requestCode, int resultCode, Intent intent) { if (intent != null) { if (intent.hasExtra(SnapshotsClient.EXTRA_SNAPSHOT_METADATA)) { // Load a snapshot. SnapshotMetadata snapshotMetadata = intent.getParcelableExtra(SnapshotsClient.EXTRA_SNAPSHOT_METADATA); mCurrentSaveName = snapshotMetadata.getUniqueName(); // Load the game data from the Snapshot // ... } else if (intent.hasExtra(SnapshotsClient.EXTRA_SNAPSHOT_NEW)) { // Create a new snapshot named with a unique string String unique = new BigInteger(281, new Random()).toString(13); mCurrentSaveName = "snapshotTemp-" + unique; // Create the new snapshot // ... } } }
כתיבת משחקים שמורים
כדי לשמור תוכן במשחק שמור:
- פותחים תמונת מצב באופן אסינכרוני באמצעות
SnapshotsClient.open()
. לאחר מכן, מאחזרים את אובייקטSnapshot
מתוצאת המשימה על ידי קריאה ל-SnapshotsClient.DataOrConflict.getData()
. - מאחזרים מופע של
SnapshotContents
באמצעותSnapshotsClient.SnapshotConflict
. - מתקשרים אל
SnapshotContents.writeBytes()
כדי לאחסן את נתוני השחקן בפורמט בייט. - אחרי שכותבים את כל השינויים, קוראים ל-
SnapshotsClient.commitAndClose()
כדי לשלוח את השינויים לשרתים של Google. בשיחה לשיטה, המשחק יכול לספק מידע נוסף כדי להסביר לשירות המשחקים של Google Play איך להציג את המשחק השמור לשחקנים. המידע הזה מיוצג באובייקטSnapshotMetaDataChange
שהמשחק יוצר באמצעותSnapshotMetadataChange.Builder
.
בקטע הקוד הבא אפשר לראות איך המשחק שלכם יכול לבצע שינויים במשחק שמור:
private Task<SnapshotMetadata> writeSnapshot(Snapshot snapshot, byte[] data, Bitmap coverImage, String desc) { // Set the data payload for the snapshot snapshot.getSnapshotContents().writeBytes(data); // Create the change operation SnapshotMetadataChange metadataChange = new SnapshotMetadataChange.Builder() .setCoverImage(coverImage) .setDescription(desc) .build(); SnapshotsClient snapshotsClient = Games.getSnapshotsClient(this, GoogleSignIn.getLastSignedInAccount(this)); // Commit the operation return snapshotsClient.commitAndClose(snapshot, metadataChange); }
אם המכשיר של השחקן לא מחובר לרשת כשהאפליקציה קוראת ל-SnapshotsClient.commitAndClose()
, שירותי Google Play Games מאחסנים את נתוני המשחק השמורים באופן מקומי במכשיר. כשמתחברים מחדש למכשיר, שירות המשחקים של Google Play מסנכרן את השינויים במשחק השמור שנשמרו במטמון המקומי עם השרתים של Google.
טעינת משחקים שמורים
כדי לאחזר משחקים שמורים של השחקן שמחובר כרגע:
- פותחים תמונת מצב באופן אסינכרוני באמצעות
SnapshotsClient.open()
. לאחר מכן, מאחזרים את אובייקטSnapshot
מתוצאת המשימה על ידי קריאה ל-SnapshotsClient.DataOrConflict.getData()
. לחלופין, המשחק יכול גם לאחזר תמונת מצב ספציפית דרך ממשק המשתמש לבחירת משחקים שמורים, כפי שמתואר במאמר בנושא הצגת משחקים שמורים. - מאחזרים את מופע
SnapshotContents
באמצעותSnapshotsClient.SnapshotConflict
. - מתקשרים למספר
SnapshotContents.readFully()
כדי לקרוא את התוכן של התמונה.
בקטע הקוד הבא אפשר לראות איך טוענים משחק ספציפי ששמור:
Task<byte[]> loadSnapshot() { // Display a progress dialog // ... // Get the SnapshotsClient from the signed in account. SnapshotsClient snapshotsClient = Games.getSnapshotsClient(this, GoogleSignIn.getLastSignedInAccount(this)); // In the case of a conflict, the most recently modified version of this snapshot will be used. int conflictResolutionPolicy = SnapshotsClient.RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED; // Open the saved game using its name. return snapshotsClient.open(mCurrentSaveName, true, conflictResolutionPolicy) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.e(TAG, "Error while opening Snapshot.", e); } }).continueWith(new Continuation<SnapshotsClient.DataOrConflict<Snapshot>, byte[]>() { @Override public byte[] then(@NonNull Task<SnapshotsClient.DataOrConflict<Snapshot>> task) throws Exception { Snapshot snapshot = task.getResult().getData(); // Opening the snapshot was a success and any conflicts have been resolved. try { // Extract the raw data from the snapshot. return snapshot.getSnapshotContents().readFully(); } catch (IOException e) { Log.e(TAG, "Error while reading Snapshot.", e); } return null; } }).addOnCompleteListener(new OnCompleteListener<byte[]>() { @Override public void onComplete(@NonNull Task<byte[]> task) { // Dismiss progress dialog and reflect the changes in the UI when complete. // ... } }); }
טיפול בהתנגשויות במשחקים שמורים
כשמשתמשים ב-API של התמונות הממוזערות במשחק, יכול להיות שכמה מכשירים יבצעו קריאות וכתיבות באותו משחק שמור. אם מכשיר מאבד זמנית את החיבור לרשת ואחר כך מתחבר מחדש, יכול להיות שיהיו סתירות בנתונים. במקרה כזה, המשחק השמור שמאוחסן במכשיר המקומי של השחקן לא יהיה מסונכרן עם הגרסה המרוחקת שמאוחסנת בשרתי Google.
Snapshots API מספק מנגנון לפתרון קונפליקטים שמציג את שני סטים של משחקים שמורים שמתנגשים בזמן הקריאה, ומאפשר לכם להטמיע אסטרטגיית פתרון שמתאימה למשחק שלכם.
כששירות המשחקים של Google Play מזהה נתונים סותרים, השיטה SnapshotsClient.DataOrConflict.isConflict()
מחזירה ערך של true
במקרה כזה, המחלקה SnapshotsClient.SnapshotConflict
מספקת שתי גרסאות של המשחק השמור:
- גרסת השרת: הגרסה הכי עדכנית ששירות המשחקים של Google Play מכיר, והיא מדויקת למכשיר של השחקן.
- גרסה מקומית: גרסה שעברה שינוי וזוהתה באחד מהמכשירים של הצופה, שמכילה תוכן או מטא-נתונים שסותרים את הגרסה המקורית. יכול להיות שהגרסה הזו שונה מהגרסה שניסיתם לשמור.
המשחק צריך להחליט איך לפתור את הבעיה על ידי בחירה באחת מהגרסאות שסופקו או מיזוג הנתונים של שתי הגרסאות השמורות של המשחק.
כדי לזהות ולפתור התנגשויות במשחקים שמורים:
- קוראים לפונקציה
SnapshotsClient.open()
. תוצאת המשימה מכילה מחלקה בשםSnapshotsClient.DataOrConflict
. - מבצעים קריאה ל-method
SnapshotsClient.DataOrConflict.isConflict()
. אם התוצאה היא true, יש לכם קונפליקט שצריך לפתור. - כדי לאחזר מופע של
SnapshotsClient.snapshotConflict
, צריך להתקשר למספרSnapshotsClient.DataOrConflict.getConflict()
. - מתקשרים אל
SnapshotsClient.SnapshotConflict.getConflictId()
כדי לאחזר את מזהה הקונפליקט שמזהה באופן ייחודי את הקונפליקט שזוהה. המשחק שלכם צריך את הערך הזה כדי לשלוח בקשה לפתרון סכסוכים בשלב מאוחר יותר. - כדי לקבל את הגרסה המקומית, מתקשרים למספר
SnapshotsClient.SnapshotConflict.getConflictingSnapshot()
. - מתקשרים למספר
SnapshotsClient.SnapshotConflict.getSnapshot()
כדי לקבל את גרסת השרת. - כדי לפתור את הבעיה של המשחק השמור, בוחרים גרסה שרוצים לשמור בשרת כגרסה הסופית ומעבירים אותה לשיטה
SnapshotsClient.resolveConflict()
.
בדוגמה הבאה אפשר לראות איך המשחק יכול לטפל בקונפליקט של משחק שמור על ידי בחירת המשחק השמור שעבר את השינוי האחרון כגרסה הסופית לשמירה:
private static final int MAX_SNAPSHOT_RESOLVE_RETRIES = 10; Task<Snapshot> processSnapshotOpenResult(SnapshotsClient.DataOrConflict<Snapshot> result, final int retryCount) { if (!result.isConflict()) { // There was no conflict, so return the result of the source. TaskCompletionSource<Snapshot> source = new TaskCompletionSource<>(); source.setResult(result.getData()); return source.getTask(); } // There was a conflict. Try resolving it by selecting the newest of the conflicting snapshots. // This is the same as using RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED as a conflict resolution // policy, but we are implementing it as an example of a manual resolution. // One option is to present a UI to the user to choose which snapshot to resolve. SnapshotsClient.SnapshotConflict conflict = result.getConflict(); Snapshot snapshot = conflict.getSnapshot(); Snapshot conflictSnapshot = conflict.getConflictingSnapshot(); // Resolve between conflicts by selecting the newest of the conflicting snapshots. Snapshot resolvedSnapshot = snapshot; if (snapshot.getMetadata().getLastModifiedTimestamp() < conflictSnapshot.getMetadata().getLastModifiedTimestamp()) { resolvedSnapshot = conflictSnapshot; } return Games.getSnapshotsClient(theActivity, GoogleSignIn.getLastSignedInAccount(this)) .resolveConflict(conflict.getConflictId(), resolvedSnapshot) .continueWithTask( new Continuation< SnapshotsClient.DataOrConflict<Snapshot>, Task<Snapshot>>() { @Override public Task<Snapshot> then( @NonNull Task<SnapshotsClient.DataOrConflict<Snapshot>> task) throws Exception { // Resolving the conflict may cause another conflict, // so recurse and try another resolution. if (retryCount < MAX_SNAPSHOT_RESOLVE_RETRIES) { return processSnapshotOpenResult(task.getResult(), retryCount + 1); } else { throw new Exception("Could not resolve snapshot conflicts"); } } }); }
שינוי משחקים שמורים לצורך פתרון בעיות
כדי למזג נתונים מכמה משחקים שמורים או לשנות קובץ Snapshot
קיים כדי לשמור אותו בשרת כגרסה הסופית, פועלים לפי השלבים הבאים:
- קוראים לפונקציה
SnapshotsClient.open()
. - מתקשרים למספר
SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent()
כדי לקבל אובייקט חדש שלSnapshotContents
. - ממזגים את הנתונים מ-
SnapshotsClient.SnapshotConflict.getConflictingSnapshot()
ומ-SnapshotsClient.SnapshotConflict.getSnapshot()
לאובייקטSnapshotContents
מהשלב הקודם. - אופציונלי: יוצרים מופע של
SnapshotMetadataChange
אם יש שינויים בשדות המטא-נתונים. - קוראים לפונקציה
SnapshotsClient.resolveConflict()
. בשיטת הקריאה, מעבירים אתSnapshotsClient.SnapshotConflict.getConflictId()
כארגומנט הראשון, ואת האובייקטיםSnapshotMetadataChange
ו-SnapshotContents
ששיניתם קודם לכן כארגומנטים השני והשלישי בהתאמה. - אם הקריאה אל
SnapshotsClient.resolveConflict()
מצליחה, ה-API שומר את האובייקטSnapshot
בשרת ומנסה לפתוח את אובייקט התמונה במכשיר המקומי.- אם יש התנגשות, הפונקציה
SnapshotsClient.DataOrConflict.isConflict()
מחזירהtrue
. במקרה כזה, המשחק אמור לחזור לשלב 2 ולחזור על השלבים לשינוי התמונה עד שהבעיות ייפתרו. - אם אין התנגשות, הפונקציה
SnapshotsClient.DataOrConflict.isConflict()
מחזירה את הערךfalse
והאובייקטSnapshot
פתוח לשינוי במשחק.
- אם יש התנגשות, הפונקציה