Android गेम में सेव किए गए गेम की सुविधा

Google Sign-In API के बंद होने के बाद, हम 2026 में Games v1 एसडीके को हटा रहे हैं. फ़रवरी 2025 के बाद, Google Play पर ऐसे गेम पब्लिश नहीं किए जा सकेंगे जो Games v1 एसडीके के साथ अभी-अभी इंटिग्रेट किए गए हैं. हमारा सुझाव है कि आप इसके बजाय, Games v2 SDK का इस्तेमाल करें.
गेम के v1 इंटिग्रेशन वाले मौजूदा टाइटल, कुछ सालों तक काम करते रहेंगे. हालांकि, हमारा सुझाव है कि आप जून 2025 से v2 पर माइग्रेट करें.
यह गाइड, Play की गेम सेवाओं के v1 एसडीके का इस्तेमाल करने के लिए है. एसडीके के नए वर्शन के बारे में जानकारी पाने के लिए, v2 का दस्तावेज़ देखें.

इस गाइड में, Google Play Games Services के स्नैपशॉट एपीआई का इस्तेमाल करके, सेव किए गए गेम की सुविधा को लागू करने का तरीका बताया गया है. ये एपीआई, com.google.android.gms.games.snapshot और com.google.android.gms.games पैकेज में उपलब्ध हैं.

शुरू करने से पहले

अगर आपने अब तक ऐसा नहीं किया है, तो सेव किए गए गेम के कॉन्सेप्ट देखें. इससे आपको मदद मिल सकती है.

• पक्का करें कि आपने Google Play Console में, अपने गेम के लिए सेव किए गए गेम की सुविधा चालू की हो.
• Android के सैंपल पेज पर जाकर, सेव किए गए गेम के कोड सैंपल को डाउनलोड करें और उसकी समीक्षा करें.
• क्वालिटी चेकलिस्ट में बताए गए सुझावों के बारे में जानें.

स्नैपशॉट क्लाइंट पाएं

स्नैपशॉट एपीआई का इस्तेमाल शुरू करने के लिए, आपके गेम को सबसे पहले SnapshotsClient ऑब्जेक्ट पाना होगा. इसके लिए, Games.getSnapshotsClient() तरीके को कॉल करें और मौजूदा प्लेयर के लिए गतिविधि और GoogleSignInAccount पास करें. खिलाड़ी के खाते की जानकारी वापस पाने का तरीका जानने के लिए, Android गेम में साइन-इन करना लेख पढ़ें.

ध्यान दें: SnapshotsClient क्लास, Google Play services Task क्लास का इस्तेमाल करके, नतीजे एसिंक्रोनस तरीके से दिखाती है. थ्रेड किए गए काम को मैनेज करने के लिए, टास्क इस्तेमाल करने के बारे में ज़्यादा जानने के लिए, Tasks API डेवलपर गाइड देखें.

Drive का स्कोप तय करना

स्नैपशॉट एपीआई, सेव किए गए गेम के स्टोरेज के लिए Google Drive API पर निर्भर करता है. Drive API को ऐक्सेस करने के लिए, आपके ऐप्लिकेशन को Google साइन-इन क्लाइंट बनाते समय Drive.SCOPE_APPFOLDER स्कोप की जानकारी देनी होगी.

साइन-इन करने की गतिविधि के लिए, 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
          }
        }
      });
}

सेव किए गए गेम दिखाना

स्नैपशॉट एपीआई को वहां इंटिग्रेट किया जा सकता है जहां आपका गेम, खिलाड़ियों को उनकी प्रोग्रेस सेव करने या वापस पाने का विकल्प देता है. आपका गेम, सेव/रीस्टोर करने के लिए तय किए गए पॉइंट पर ऐसा विकल्प दिखा सकता है. इसके अलावा, खिलाड़ियों को किसी भी समय प्रोग्रेस सेव या रीस्टोर करने की अनुमति दे सकता है.

जब खिलाड़ी आपके गेम में सेव/रीस्टोर करने का विकल्प चुनते हैं, तो आपका गेम एक स्क्रीन दिखा सकता है. इस स्क्रीन पर, खिलाड़ियों को सेव किए गए नए गेम के लिए जानकारी डालने या सेव किए गए किसी मौजूदा गेम को रीस्टोर करने का विकल्प मिलता है.

स्नैपशॉट एपीआई, डिफ़ॉल्ट रूप से सेव किए गए गेम चुनने के लिए यूज़र इंटरफ़ेस (यूआई) उपलब्ध कराता है. इसका इस्तेमाल बिना किसी बदलाव के किया जा सकता है. इससे आपको डेवलपमेंट में आसानी होती है. सेव किए गए गेम चुनने की सुविधा देने वाले यूज़र इंटरफ़ेस (यूआई) की मदद से, खिलाड़ी ये काम कर सकते हैं: नया सेव किया गया गेम बनाना, सेव किए गए मौजूदा गेम के बारे में जानकारी देखना, और सेव किए गए पिछले गेम लोड करना.

सेव किए गए गेम के डिफ़ॉल्ट यूज़र इंटरफ़ेस (यूआई) को लॉन्च करने के लिए:

1. डिफ़ॉल्ट रूप से सेव किए गए गेम चुनने के यूज़र इंटरफ़ेस (यूआई) को लॉन्च करने के लिए, SnapshotsClient.getSelectSnapshotIntent() को कॉल करके Intent पाएं.
2. 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
      // ...
    }
  }
}

सेव किए गए गेम लिखना

सेव किए गए गेम में कॉन्टेंट सेव करने के लिए:

1. SnapshotsClient.open() के ज़रिए, स्नैपशॉट को एसिंक्रोनस तरीके से खोलता है. इसके बाद, SnapshotsClient.DataOrConflict.getData() को कॉल करके, टास्क के नतीजे से Snapshot ऑब्जेक्ट वापस पाएं.
2. SnapshotsClient.SnapshotConflict के ज़रिए, SnapshotContents का इंस्टेंस पाएं.
3. खिलाड़ी के डेटा को बाइट फ़ॉर्मैट में सेव करने के लिए, SnapshotContents.writeBytes() को कॉल करें.
4. सभी बदलाव लिखने के बाद, SnapshotsClient.commitAndClose() को कॉल करें, ताकि आपके बदलाव Google के सर्वर पर भेजे जा सकें. मेथड कॉल में, आपका गेम Google Play Games Services को यह जानकारी दे सकता है कि खिलाड़ियों को सेव किया गया गेम कैसे दिखाया जाए. हालांकि, यह जानकारी देना ज़रूरी नहीं है. यह जानकारी, 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 Services, सेव किए गए गेम के डेटा को डिवाइस पर सेव करती है. डिवाइस को फिर से कनेक्ट करने पर, Google Play Games Services, स्थानीय तौर पर कैश मेमोरी में सेव किए गए गेम में हुए बदलावों को Google के सर्वर के साथ सिंक करता है.

सेव किए गए गेम लोड करना

मौजूदा समय में साइन इन किए हुए प्लेयर के लिए, सेव किए गए गेम वापस पाने के लिए:

1. SnapshotsClient.open() के ज़रिए, स्नैपशॉट को एसिंक्रोनस तरीके से खोलता है. इसके बाद, SnapshotsClient.DataOrConflict.getData() को कॉल करके, टास्क के नतीजे से Snapshot ऑब्जेक्ट वापस पाएं. इसके अलावा, आपका गेम सेव किए गए गेम चुनने वाले यूज़र इंटरफ़ेस (यूआई) के ज़रिए भी कोई स्नैपशॉट वापस पा सकता है. इसके बारे में सेव किए गए गेम दिखाना लेख में बताया गया है.
2. SnapshotsClient.SnapshotConflict के ज़रिए, SnapshotContents इंस्टेंस पाएं.
3. स्नैपशॉट के कॉन्टेंट को पढ़ने के लिए, 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.
          // ...
        }
      });
}

सेव किए गए गेम में होने वाली गड़बड़ियों को ठीक करना

अपने गेम में स्नैपशॉट एपीआई का इस्तेमाल करते समय, एक ही सेव किए गए गेम पर कई डिवाइसों से रीड और राइट किया जा सकता है. अगर किसी डिवाइस का नेटवर्क कनेक्शन कुछ समय के लिए बंद हो जाता है और बाद में फिर से कनेक्ट हो जाता है, तो डेटा में गड़बड़ियां हो सकती हैं. ऐसा इसलिए, क्योंकि किसी खिलाड़ी के डिवाइस में सेव किया गया गेम, Google के सर्वर में सेव किए गए रिमोट वर्शन के साथ सिंक नहीं होता.

स्नैपशॉट एपीआई, टकराव को हल करने का एक तरीका उपलब्ध कराता है. इससे, सेव किए गए गेम के दोनों सेट को पढ़ने के समय दिखाया जाता है. साथ ही, आपको टकराव को हल करने की ऐसी रणनीति लागू करने की सुविधा मिलती है जो आपके गेम के लिए सही हो.

जब Google Play Games Services को डेटा में कोई गड़बड़ी मिलती है, तब SnapshotsClient.DataOrConflict.isConflict() तरीके से true वैल्यू मिलती है. इस इवेंट में, SnapshotsClient.SnapshotConflict क्लास, सेव किए गए गेम के दो वर्शन उपलब्ध कराती है:

• सर्वर वर्शन: यह Google Play Games Services का सबसे नया वर्शन होता है. यह खिलाड़ी के डिवाइस के लिए सटीक होता है; और
• लोकल वर्शन: प्लेयर के किसी डिवाइस पर मिला ऐसा बदला हुआ वर्शन जिसमें विरोधाभासी कॉन्टेंट या मेटाडेटा मौजूद है. ऐसा हो सकता है कि यह उस वर्शन से अलग हो जिसे आपने सेव करने की कोशिश की थी.

आपके गेम को यह तय करना होगा कि टकराव को कैसे हल किया जाए. इसके लिए, उसे दिए गए वर्शन में से किसी एक को चुनना होगा या सेव किए गए गेम के दोनों वर्शन के डेटा को मर्ज करना होगा.

सेव किए गए गेम के कॉन्फ़्लिक्ट का पता लगाने और उन्हें ठीक करने के लिए:

1. SnapshotsClient.open() पर कॉल करें. टास्क के नतीजे में SnapshotsClient.DataOrConflict क्लास शामिल है.
2. SnapshotsClient.DataOrConflict.isConflict() तरीके को कॉल करें. अगर नतीजा सही है, तो आपको किसी समस्या को हल करना होगा.
3. SnapshotsClient.snapshotConflict इंस्टेंस को वापस पाने के लिए, SnapshotsClient.DataOrConflict.getConflict() को कॉल करें.
4. डिटेक्ट किए गए कॉन्फ़्लिक्ट की खास तौर पर पहचान करने वाले कॉन्फ़्लिक्ट आईडी को वापस पाने के लिए, SnapshotsClient.SnapshotConflict.getConflictId() को कॉल करें. आपके गेम को इस वैल्यू की ज़रूरत होती है, ताकि बाद में विवाद सुलझाने का अनुरोध भेजा जा सके.
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 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 में बदलाव करना है, ताकि इसे सर्वर पर सेव किया जा सके, तो यह तरीका अपनाएं:

1. SnapshotsClient.open() पर कॉल करें .
2. नया SnapshotContents ऑब्जेक्ट पाने के लिए, SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent() को कॉल करें.
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 दिखाता है. ऐसे में, आपके गेम को दूसरे चरण पर वापस जाना चाहिए और स्नैपशॉट में बदलाव करने के लिए, तब तक चरणों को दोहराना चाहिए, जब तक कि टकराव हल न हो जाएं.
   • अगर कोई टकराव नहीं होता है, तो SnapshotsClient.DataOrConflict.isConflict(), false दिखाता है. साथ ही, Snapshot ऑब्जेक्ट को आपके गेम में बदलाव करने के लिए खोला जाता है.