অ্যান্ড্রয়েড গেমগুলিতে সংরক্ষিত গেম সমর্থন

এই নির্দেশিকা আপনাকে দেখায় কিভাবে Google Play Games পরিষেবার দ্বারা প্রদত্ত স্ন্যাপশট API ব্যবহার করে সংরক্ষিত গেমস গেম বাস্তবায়ন করতে হয়। APIগুলি com.google.android.gms.games.snapshot এবং com.google.android.gms.games প্যাকেজে পাওয়া যাবে৷

আপনি শুরু করার আগে

আপনি যদি ইতিমধ্যে এটি না করে থাকেন, তাহলে সংরক্ষিত গেমস গেমের ধারণাগুলি পর্যালোচনা করা আপনার সহায়ক বলে মনে হতে পারে৷

• Google Play Console-এ আপনার গেমের জন্য সংরক্ষিত গেম সমর্থন সক্ষম করা নিশ্চিত করুন।
• অ্যান্ড্রয়েড নমুনা পৃষ্ঠায় সংরক্ষিত গেম কোড নমুনা ডাউনলোড করুন এবং পর্যালোচনা করুন।
• কোয়ালিটি চেকলিস্টে বর্ণিত সুপারিশগুলির সাথে নিজেকে পরিচিত করুন৷

স্ন্যাপশট ক্লায়েন্ট পান

স্ন্যাপশট API ব্যবহার শুরু করতে, আপনার গেমটিকে প্রথমে একটি SnapshotsClient অবজেক্ট পেতে হবে। আপনি Games.getSnapshotsClient() পদ্ধতিতে কল করে এবং বর্তমান প্লেয়ারের জন্য কার্যকলাপ এবং GoogleSignInAccount পাস করে এটি করতে পারেন। প্লেয়ার অ্যাকাউন্টের তথ্য কীভাবে পুনরুদ্ধার করবেন তা জানতে, Android গেমগুলিতে সাইন-ইন দেখুন।

ড্রাইভের সুযোগ নির্দিষ্ট করুন

সংরক্ষিত গেম স্টোরেজের জন্য স্ন্যাপশট API Google ড্রাইভ API-এর উপর নির্ভর করে। ড্রাইভ API অ্যাক্সেস করতে, Google সাইন-ইন ক্লায়েন্ট তৈরি করার সময় আপনার অ্যাপটিকে অবশ্যই Drive.SCOPE_APPFOLDER .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
          }
        }
      });
}

সংরক্ষিত গেমগুলি প্রদর্শন করুন

যেখানেই আপনার গেম খেলোয়াড়দের তাদের অগ্রগতি সংরক্ষণ বা পুনরুদ্ধার করার বিকল্প প্রদান করে সেখানে আপনি স্ন্যাপশট এপিআই সংহত করতে পারেন। আপনার গেম মনোনীত সংরক্ষণ/পুনরুদ্ধার পয়েন্টগুলিতে এই জাতীয় বিকল্প প্রদর্শন করতে পারে বা খেলোয়াড়দের যেকোন সময় অগ্রগতি সংরক্ষণ বা পুনরুদ্ধার করার অনুমতি দিতে পারে।

একবার খেলোয়াড়রা আপনার গেমে সংরক্ষণ/পুনরুদ্ধার বিকল্পটি নির্বাচন করলে, আপনার গেমটি ঐচ্ছিকভাবে একটি স্ক্রীন আনতে পারে যা খেলোয়াড়দের একটি নতুন সংরক্ষিত গেমের জন্য তথ্য প্রবেশ করতে বা পুনরুদ্ধার করার জন্য একটি বিদ্যমান সংরক্ষিত গেম নির্বাচন করতে অনুরোধ করে।

আপনার বিকাশকে সহজ করার জন্য, স্ন্যাপশট API একটি ডিফল্ট সংরক্ষিত গেম নির্বাচন ব্যবহারকারী ইন্টারফেস (UI) প্রদান করে যা আপনি বাক্সের বাইরে ব্যবহার করতে পারেন। সংরক্ষিত গেম নির্বাচন UI খেলোয়াড়দের একটি নতুন সংরক্ষিত গেম তৈরি করতে, বিদ্যমান সংরক্ষিত গেমগুলির বিবরণ দেখতে এবং আগের সংরক্ষিত গেমগুলি লোড করতে দেয়৷

ডিফল্ট সংরক্ষিত গেম UI চালু করতে:

1. ডিফল্ট সংরক্ষিত গেম নির্বাচন UI চালু করার জন্য একটি Intent পেতে SnapshotsClient.getSelectSnapshotIntent() এ কল করুন৷
2. startActivityForResult() কল করুন এবং সেই Intent পাস করুন। কলটি সফল হলে, গেমটি আপনার নির্দিষ্ট করা বিকল্পগুলির সাথে সংরক্ষিত গেম নির্বাচন UI প্রদর্শন করে।

ডিফল্ট সংরক্ষিত গেম নির্বাচন UI কীভাবে চালু করবেন তার একটি উদাহরণ এখানে রয়েছে:

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);
    }
  });
}

যদি প্লেয়ার একটি নতুন সংরক্ষিত গেম তৈরি করতে বা একটি বিদ্যমান সংরক্ষিত গেম লোড করার জন্য নির্বাচন করে, UI Google Play Games পরিষেবাগুলিতে একটি অনুরোধ পাঠায়৷ অনুরোধটি সফল হলে, 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. আপনার সমস্ত পরিবর্তন লেখা হয়ে গেলে, Google এর সার্ভারে আপনার পরিবর্তনগুলি পাঠাতে SnapshotsClient.commitAndClose() এ কল করুন৷ মেথড কলে, আপনার গেমটি ঐচ্ছিকভাবে Google Play Games পরিষেবাগুলিকে কীভাবে এই সংরক্ষিত গেমটি খেলোয়াড়দের কাছে উপস্থাপন করতে হয় তা জানাতে অতিরিক্ত তথ্য প্রদান করতে পারে। এই তথ্যটি একটি 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 এর সার্ভারগুলিতে সিঙ্ক করে৷

সংরক্ষিত গেম লোড করুন

বর্তমানে সাইন-ইন করা প্লেয়ারের জন্য সংরক্ষিত গেমগুলি পুনরুদ্ধার করতে:

1. SnapshotsClient.open() এর মাধ্যমে অ্যাসিঙ্ক্রোনাসভাবে একটি স্ন্যাপশট খুলুন। তারপর, SnapshotsClient.DataOrConflict.getData() কল করে টাস্কের ফলাফল থেকে Snapshot বস্তুটি পুনরুদ্ধার করুন। বিকল্পভাবে, আপনার গেমটি সংরক্ষিত গেম নির্বাচন UI এর মাধ্যমে একটি নির্দিষ্ট স্ন্যাপশট পুনরুদ্ধার করতে পারে, যেমনটি সংরক্ষিত গেমগুলি প্রদর্শনে বর্ণিত হয়েছে।
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.
          // ...
        }
      });
}

সংরক্ষিত গেম দ্বন্দ্ব পরিচালনা করুন

আপনার গেমে স্ন্যাপশট API ব্যবহার করার সময়, একাধিক ডিভাইসের জন্য একই সংরক্ষিত গেমে রিড এবং রাইট করা সম্ভব। কোনো ডিভাইস সাময়িকভাবে তার নেটওয়ার্ক সংযোগ হারায় এবং পরে পুনরায় সংযোগ করলে, এটি ডেটা দ্বন্দ্বের কারণ হতে পারে যার ফলে প্লেয়ারের স্থানীয় ডিভাইসে সংরক্ষিত গেমটি Google-এর সার্ভারে সংরক্ষিত দূরবর্তী সংস্করণের সাথে সিঙ্কের বাইরে থাকে।

স্ন্যাপশট এপিআই একটি দ্বন্দ্ব রেজোলিউশন মেকানিজম প্রদান করে যা রিড-টাইমে বিরোধপূর্ণ সংরক্ষিত গেমের উভয় সেট উপস্থাপন করে এবং আপনাকে একটি রেজোলিউশন কৌশল প্রয়োগ করতে দেয় যা আপনার গেমের জন্য উপযুক্ত।

যখন Google Play গেম পরিষেবাগুলি একটি ডেটা দ্বন্দ্ব শনাক্ত করে, তখন SnapshotsClient.DataOrConflict.isConflict() পদ্ধতিটি true একটি মান প্রদান করে এই ইভেন্টে, SnapshotsClient.SnapshotConflict ক্লাস সংরক্ষিত গেমের দুটি সংস্করণ প্রদান করে:

• সার্ভার সংস্করণ : প্লেয়ারের ডিভাইসের জন্য সঠিক হতে Google Play গেম পরিষেবা দ্বারা পরিচিত সবচেয়ে আপ-টু-ডেট সংস্করণ; এবং
• স্থানীয় সংস্করণ : প্লেয়ারের ডিভাইসগুলির একটিতে একটি পরিবর্তিত সংস্করণ সনাক্ত করা হয়েছে যাতে বিরোধপূর্ণ সামগ্রী বা মেটাডেটা রয়েছে৷ আপনি যে সংস্করণটি সংরক্ষণ করার চেষ্টা করেছেন সেটির মতো এটি নাও হতে পারে৷

প্রদত্ত সংস্করণগুলির মধ্যে একটি বাছাই করে বা দুটি সংরক্ষিত গেম সংস্করণের ডেটা মার্জ করে কীভাবে বিরোধ সমাধান করা যায় তা আপনার গেমটিকে অবশ্যই সিদ্ধান্ত নিতে হবে৷

সংরক্ষিত গেম দ্বন্দ্ব সনাক্ত করতে এবং সমাধান করতে:

1. SnapshotsClient.open() কল করুন। টাস্ক ফলাফলে একটি SnapshotsClient.DataOrConflict ক্লাস রয়েছে৷
2. SnapshotsClient.DataOrConflict.isConflict() পদ্ধতিতে কল করুন। ফলাফল সত্য হলে, আপনার সমাধান করার জন্য একটি দ্বন্দ্ব আছে।
3. একটি SnaphotsClient.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() এবং SnapshotContents SnapshotsClient.SnapshotConflict.getSnapshot() থেকে ডেটা একত্রিত করুন।
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 অবজেক্ট খোলা থাকে।