इस गाइड में Google Play की गेम सेवाओं से उपलब्ध, स्नैपशॉट वाले एपीआई का इस्तेमाल करके, सेव किए गए गेम को इस्तेमाल करने का तरीका बताया गया है. एपीआई
com.google.android.gms.games.snapshot
और com.google.android.gms.games
पैकेज में मिल सकते हैं.
शुरू करने से पहले
अगर आपने पहले से ऐसा नहीं किया है, तो सेव किए गए गेम के सिद्धांतों को पढ़ना आपके लिए मददगार हो सकता है.
- Google Play Console में अपने गेम के लिए सेव किए गए गेम से जुड़ी सहायता चालू करना पक्का करें.
- Android सैंपल पेज पर जाकर, सेव किए गए गेम कोड का नमूना डाउनलोड करें और उनकी समीक्षा करें.
- क्वालिटी चेकलिस्ट में बताए गए सुझावों के बारे में जानें.
स्नैपशॉट क्लाइंट पाना
स्नैपशॉट एपीआई का इस्तेमाल शुरू करने के लिए, यह ज़रूरी है कि आपका गेम
SnapshotsClient
ऑब्जेक्ट हासिल करे. ऐसा करने के लिए,
Games.getSnapshotsClient()
तरीके को कॉल करें और गतिविधि
को पास करें.
डिस्क के दायरे की जानकारी
गेम को सेव करने के लिए, स्नैपशॉट एपीआई, Google Drive API पर निर्भर करती है. Drive
एपीआई ऐक्सेस करने के लिए, आपके ऐप्लिकेशन को Google साइन-इन क्लाइंट बनाते समय
Drive.SCOPE_APPFOLDER
दायरा तय करना होगा.
यहां, साइन इन करने से जुड़ी गतिविधि के लिए, onResume()
वाले तरीके में ऐसा करने का एक उदाहरण दिया गया है:
@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 } } }); }
सेव किए गए गेम दिखाए जा रहे हैं
जहां भी आपका गेम, खिलाड़ियों को उनकी प्रगति को सेव करने या उसे बहाल करने का विकल्प देता है, वहां आप स्नैपशॉट API को इंटिग्रेट कर सकते हैं. आपका गेम इस तरह का विकल्प तय किए गए सेव करें/पहले जैसा करें या खिलाड़ियों को किसी भी समय प्रगति को सेव या बहाल करने की अनुमति दे सकता है.
जब प्लेयर आपके गेम में सेव करें/वापस लाएं विकल्प चुनें, तब आपका गेम वैकल्पिक रूप से एक स्क्रीन ला सकता है जो खिलाड़ियों को नए सेव किए गए गेम की जानकारी डालने या किसी मौजूदा सेव किए गए गेम को बहाल करने के लिए कहता है.
आपके डेवलपमेंट को आसान बनाने के लिए, स्नैपशॉट एपीआई, डिफ़ॉल्ट रूप से सेव किया गया गेम चुनने का यूज़र इंटरफ़ेस (यूआई) देता है. इसका इस्तेमाल किया जा सकता है. सेव किए गए गेम चुनने के यूज़र इंटरफ़ेस (यूआई) के ज़रिए, खिलाड़ी नया सेव किया गया गेम बना सकते हैं, सेव किए गए मौजूदा गेम का ब्यौरा देख सकते हैं, और सेव किए गए पिछले गेम लोड कर सकते हैं.
डिफ़ॉल्ट रूप से सेव किए गए गेम का यूज़र इंटरफ़ेस (यूआई) लॉन्च करने के लिए:
- डिफ़ॉल्ट रूप से सेव किए गए गेम चुनने के यूज़र इंटरफ़ेस (यूआई) को लॉन्च करने के लिए,
Intent
परSnapshotsClient.getSelectSnapshotIntent()
को कॉल करें. startActivityForResult()
को कॉल करें और उस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); } }); }
अगर प्लेयर सेव किया गया नया गेम बनाने या पहले से सेव किए गए किसी गेम को लोड करने का विकल्प चुनता है, तो यूज़र इंटरफ़ेस (यूआई) Google Play की गेम सेवाओं को एक अनुरोध भेजता है. अनुरोध पूरा होने पर,
Google Play की गेम सेवाएं, 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()
की मदद से, अपने-आप खोलें. इसके बाद,SnapshotsClient.DataOrConflict.getData()
पर कॉल करके, टास्क के नतीजे सेSnapshot
ऑब्जेक्ट को वापस लाएं. 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 = PlayGames.getSnapshotsClient(this); // Commit the operation return snapshotsClient.commitAndClose(snapshot, metadataChange); }
अगर आपका ऐप्लिकेशन कॉल करता है, तो प्लेयर का डिवाइस किसी नेटवर्क से कनेक्ट नहीं होने पर, SnapshotsClient.commitAndClose()
, Google Play की गेम सेवाएं, सेव किए गए गेम के डेटा को डिवाइस में सेव करती हैं. डिवाइस के फिर से कनेक्शन पर, Google Play की गेम सेवाएं, डिवाइस पर कैश मेमोरी में सेव किए गए गेम के बदलावों को Google के सर्वर के साथ सिंक करती हैं.
सेव किए गए गेम लोड हो रहे हैं
अभी साइन इन किए हुए प्लेयर के लिए, सेव किए गए गेम वापस पाने का तरीका:
- स्नैपशॉट को
SnapshotsClient.open()
की मदद से, अपने-आप खोलें. इसके बाद,SnapshotsClient.DataOrConflict.getData()
पर कॉल करके, टास्क के नतीजे सेSnapshot
ऑब्जेक्ट को वापस लाएं. इसके अलावा, आपका गेम, सेव किए गए गेम चुनने के यूज़र इंटरफ़ेस (यूआई) की मदद से किसी खास स्नैपशॉट को वापस ला सकता है. इसके लिए, सेव किए गए गेम दिखाए जाने से जुड़ी जानकारी दी गई है. SnapshotContents
इंस्टेंस कोSnapshotsClient.SnapshotConflict
की मदद से फिर से पाएं.- स्नैपशॉट का कॉन्टेंट पढ़ने के लिए,
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. // ... } }); }
सेव किए गए गेम से जुड़े विवादों को हल करना
अपने गेम में स्नैपशॉट एपीआई का इस्तेमाल करते समय, एक से ज़्यादा डिवाइस पर, सेव किए गए एक ही गेम में कई लेख पढ़े और लिखे जा सकते हैं. डिवाइस का अस्थायी रूप से नेटवर्क कनेक्शन खो जाने और बाद में फिर से कनेक्ट होने की स्थिति में, इसके कारण डेटा विवाद हो सकता है जहां किसी खिलाड़ी के स्थानीय डिवाइस पर संग्रहित गेम उसके दूरस्थ वर्शन के साथ समन्वयित नहीं होता है.
स्नैपशॉट एपीआई, समस्याओं को हल करने का एक ऐसा तरीका देता है जो आपस में जुड़े होने के दौरान, सेव किए गए गेम के दोनों सेट को रीड-टाइम में दिखाता है. इसकी मदद से, आप अपने गेम के लिए सही समाधान की रणनीति लागू कर सकते हैं.
जब Google Play की गेम सेवाओं में डेटा के टकराव का पता चलता है, तो SnapshotsClient.DataOrConflict.isConflict()
वाला तरीका true
की वैल्यू दिखाता है. इस इवेंट में,
SnapshotsClient.SnapshotConflict
क्लास, सेव किए गए गेम के दो वर्शन उपलब्ध कराती है:
- सर्वर वर्शन: Google Play की गेम सेवाओं के बारे में अप-टू-डेट वर्शन, जिसे प्लेयर के डिवाइस के हिसाब से सटीक माना जाता है; और
- स्थानीय वर्शन: खिलाड़ी के किसी ऐसे डिवाइस पर बदलाव किए गए वर्शन का पता चला है जिसमें विरोधी कॉन्टेंट या मेटाडेटा है. हो सकता है कि यह वही वर्शन न हो जिसे आपने सेव करने की कोशिश की थी.
आपके गेम को दिए गए वर्शन में से किसी एक को चुनकर या दो सेव किए गए गेम के वर्शन के डेटा को मर्ज करके टकराव को ठीक करने का तरीका तय करना होगा.
सेव किए गए गेम की गड़बड़ियों का पता लगाने और उन्हें ठीक करने के लिए:
SnapshotsClient.open()
को कॉल करें. टास्क के नतीजे मेंSnapshotsClient.DataOrConflict
क्लास है.SnapshotsClient.DataOrConflict.isConflict()
वाले तरीके को कॉल करें. अगर नतीजा सही है, तो आपको इस समस्या को हल करने में दिक्कत होगी.SnaphotsClient.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 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
को बदलना चाहते हैं, तो इन चरणों का पालन करें:
SnapshotsClient.open()
पर कॉल करें .- नया
SnapshotContents
ऑब्जेक्ट पाने के लिए,SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent()
को कॉल करें. SnapshotsClient.SnapshotConflict.getConflictingSnapshot()
औरSnapshotsClient.SnapshotConflict.getSnapshot()
का डेटा पिछले चरण में मौजूदSnapshotContents
ऑब्जेक्ट में मर्ज करें.- इसके अलावा, अगर मेटाडेटा फ़ील्ड में कोई बदलाव किया जाता है, तो
SnapshotMetadataChange
इंस्टेंस बनाएं. SnapshotsClient.resolveConflict()
को कॉल करें. अपने मेथड कॉल में,SnapshotsClient.SnapshotConflict.getConflictId()
को पहले आर्ग्युमेंट के तौर पर पास करें. साथ ही, उनSnapshotMetadataChange
औरSnapshotContents
ऑब्जेक्ट को पास करें जिन्हें आपने पहले क्रम से दूसरे और तीसरे आर्ग्युमेंट के तौर पर बदला था.SnapshotsClient.resolveConflict()
कॉल पूरा होने पर, एपीआईSnapshot
ऑब्जेक्ट को सर्वर पर स्टोर करता है और आपके लोकल डिवाइस पर स्नैपशॉट ऑब्जेक्ट को खोलने की कोशिश करता है.- अगर कोई टकराव होता है, तो
SnapshotsClient.DataOrConflict.isConflict()
,true
दिखाता है. ऐसे मामले में, आपके गेम को दूसरे चरण पर वापस ले जाना चाहिए. साथ ही, स्नैपशॉट को बदलने के लिए उन कदमों को दोहराएं जब तक कि विवाद सुलझ न जाएं. - अगर कोई विवाद न हो, तो
SnapshotsClient.DataOrConflict.isConflict()
false
दिखाता है और आपके गेम में बदलाव करने के लिएSnapshot
ऑब्जेक्ट खुला होता है.
- अगर कोई टकराव होता है, तो