משחקים שמורים למשחקי Android

במדריך הזה מוסבר איך להטמיע משחקים שמורים באמצעות ה-API של התמונות שסופק על ידי שירותי Google Play Games. ממשקי ה-API נמצאים בחבילות com.google.android.gms.games.snapshot ו-com.google.android.gms.games.

לפני שמתחילים

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

הורדת לקוח של תמונות מצב

כדי להתחיל להשתמש ב-Snapshots API, המשחק שלכם צריך קודם לקבל אובייקט SnapshotsClient. אפשר לעשות את זה על ידי קריאה לשיטה Games.getSnapshotsContents() והעברת הפעילות.

הצגת משחקים שמורים

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

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

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

כדי להפעיל את ממשק המשתמש של ברירת המחדל של משחקים שמורים:

  1. מתקשרים אל SnapshotsClient.getSelectSnapshotIntent() כדי לקבל Intent להפעלת ממשק המשתמש של בחירת המשחקים השמורים שמוגדר כברירת מחדל.
  2. ‫Call startActivityForResult() and pass in that Intent. אם השיחה תצליח, ממשק המשתמש של בחירת המשחק השמור יופיע במשחק, יחד עם האפשרויות שציינתם.

דוגמה להפעלת ממשק המשתמש של בחירת המשחקים השמורים שמוגדרים כברירת מחדל:

private static final int RC_SAVED_GAMES = 9009;

private void showSavedGamesUI() {
  SnapshotsClient snapshotsClient =
      PlayGames.getSnapshotsClient(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);
    }
  });
}

אם השחקן בוחר ליצור משחק שמור חדש או לטעון משחק שמור קיים, ממשק המשתמש שולח בקשה לשירותי המשחקים של Play. אם הבקשה מצליחה, Play Games Services מחזיר מידע ליצירה או לשחזור של המשחק השמור באמצעות הקריאה החוזרת (callback) 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
      // ...
    }
  }
}

כתיבת משחקים שמורים

כדי לשמור תוכן במשחק שמור:

  1. פותחים תמונת מצב באופן אסינכרוני באמצעות SnapshotsClient.open().

  2. מאחזרים את האובייקט Snapshot מתוצאת המשימה על ידי קריאה ל-SnapshotsClient.DataOrConflict.getData().

  3. אחזור מופע של SnapshotContents באמצעות SnapshotsClient.SnapshotConflict.

  4. ‫Call SnapshotContents.writeBytes() כדי לאחסן את נתוני השחקן בפורמט בייט.

  5. אחרי שכותבים את כל השינויים, קוראים ל-SnapshotsClient.commitAndClose() כדי לשלוח את השינויים לשרתים של 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 =
      PlayGames.getSnapshotsClient(this);

  // Commit the operation
  return snapshotsClient.commitAndClose(snapshot, metadataChange);
}

אם המכשיר של השחקן לא מחובר לרשת כשהאפליקציה קוראת ל-SnapshotsClient.commitAndClose(), שירותי Play Games מאחסנים את נתוני המשחק השמור באופן מקומי במכשיר. כשמתחברים מחדש למכשיר, שירות המשחקים של Play מסנכרן את השינויים במשחק השמור שנשמרו במטמון המקומי עם השרתים של Google.

טעינת משחקים שמורים

כדי לאחזר משחקים שמורים עבור השחקן המאומת:

  1. פותחים תמונה של מצב נתון באופן אסינכרוני באמצעות SnapshotsClient.open().

  2. מאחזרים את אובייקט Snapshot מתוצאת המשימה על ידי קריאה ל-SnapshotsClient.DataOrConflict.getData(). לחלופין, אפשר גם לאחזר תמונת מצב ספציפית של המשחק באמצעות ממשק המשתמש לבחירת משחקים שמורים, כפי שמתואר במאמר בנושא הצגת משחקים שמורים.

  3. מאחזרים את מופע SnapshotContents באמצעות SnapshotsClient.SnapshotConflict.

  4. תתקשר אליי SnapshotContents.readFully() כדי שאקריא לך את התוכן של הצילום.

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

Task<byte[]> loadSnapshot() {
  // Display a progress dialog
  // ...

  // Get the SnapshotsClient from the signed in account.
  SnapshotsClient snapshotsClient =
      PlayGames.getSnapshotsClient(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 מספק מנגנון לפתרון קונפליקטים שמציג את שני סטים של משחקים שמורים שמתנגשים בזמן הקריאה, ומאפשר לכם להטמיע אסטרטגיית פתרון שמתאימה למשחק שלכם.

כש-Play Games Services מזהה התנגשות נתונים, השיטה SnapshotsClient.DataOrConflict.isConflict() מחזירה ערך של true במקרה כזה, המחלקה SnapshotsClient.SnapshotConflict מספקת שתי גרסאות של המשחק השמור:

  • גרסת השרת: הגרסה הכי עדכנית ששירות המשחקים של Play Games יודע שהיא מדויקת למכשיר של השחקן.

  • גרסה מקומית: גרסה שעברה שינוי וזוהתה באחד מהמכשירים של הנגן, שמכילה תוכן או מטא-נתונים סותרים. יכול להיות שהגרסה הזו שונה מהגרסה שניסיתם לשמור.

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

כדי לזהות ולפתור התנגשויות במשחקים שמורים:

  1. מתקשרים אל SnapshotsClient.open(). תוצאת המשימה מכילה מחלקה בשם SnapshotsClient.DataOrConflict.

  2. מבצעים קריאה ל-method‏ SnapshotsClient.DataOrConflict.isConflict(). אם התוצאה היא true, יש לכם אירוע חופף שצריך לפתור.

  3. מתקשרים אל SnapshotsClient.DataOrConflict.getConflict() כדי לאחזר מופע של SnapshotsClient.snapshotConflict.

  4. ‫Call SnapshotsClient.SnapshotConflict.getConflictId() to retrieve the conflict ID that uniquely identifies the detected conflict. המשחק צריך את הערך הזה כדי לשלוח בקשה לפתרון קונפליקט בהמשך.

  5. כדי לקבל את הגרסה המקומית, צריך להתקשר למספר SnapshotsClient.SnapshotConflict.getConflictingSnapshot().

  6. מתקשרים למספר SnapshotsClient.SnapshotConflict.getSnapshot() כדי לקבל את גרסת השרת.

  7. כדי לפתור את הבעיה של קובץ שמירה שנוצר כתוצאה מהתנגשות, בוחרים גרסה שרוצים לשמור בשרת כגרסה הסופית ומעבירים אותה לשיטה 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 PlayGames.getSnapshotsClient(theActivity)
      .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 קיים כדי לשמור אותו בשרת כגרסה הסופית, פועלים לפי השלבים הבאים:

  1. מתקשרים אל SnapshotsClient.open().

  2. מתקשרים אל SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent() כדי לקבל אובייקט חדש של SnapshotContents.

  3. ממזגים את הנתונים מ- SnapshotsClient.SnapshotConflict.getConflictingSnapshot() ומ- SnapshotsClient.SnapshotConflict.getSnapshot() לאובייקט SnapshotContents מהשלב הקודם.

  4. אופציונלי: יוצרים מופע של SnapshotMetadataChange אם יש שינויים בשדות המטא-נתונים.

  5. מתקשרים אל SnapshotsClient.resolveConflict(). בשיחה עם השיטה, מעבירים את SnapshotsClient.SnapshotConflict.getConflictId() כארגומנט הראשון, ואת האובייקטים SnapshotMetadataChange ו-SnapshotContents ששיניתם קודם לכן כארגומנטים השני והשלישי, בהתאמה.

  6. אם הקריאה SnapshotsClient.resolveConflict() מצליחה, ה-API שומר את אובייקט Snapshot בשרת ומנסה לפתוח את אובייקט התמונה במכשיר המקומי.

    • אם יש התנגשות, הפונקציה SnapshotsClient.DataOrConflict.isConflict() מחזירה true. במקרה כזה, המשחק צריך לחזור לשלב 2 ולחזור על השלבים לשינוי התמונה עד שהבעיות ייפתרו.
    • אם אין התנגשות, ‫SnapshotsClient.DataOrConflict.isConflict() מחזירה את false ואובייקט Snapshot פתוח כדי שהמשחק יוכל לשנות אותו.