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

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

শুরু করার আগে

এই ফিচারটি সম্পর্কে জানতে, সেভড গেমস ওভারভিউ দেখুন।

• গুগল প্লে কনসোলে আপনার গেমের জন্য সেভ করা গেম সমর্থন সক্রিয় করুন ।
• অ্যান্ড্রয়েড স্যাম্পল পেজ থেকে সেভ করা গেমের কোড স্যাম্পলটি ডাউনলোড করে পর্যালোচনা করুন।
• গুণমান চেকলিস্টে বর্ণিত সুপারিশগুলো ভালোভাবে জেনে নিন।

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

স্ন্যাপশট এপিআই ব্যবহার শুরু করতে, আপনার গেমকে প্রথমে একটি SnapshotsClient অবজেক্ট পেতে হবে। আপনি Games.getSnapshotsContents() মেথডটি কল করে এবং অ্যাক্টিভিটিটি পাস করে এটি করতে পারেন।

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

আপনার গেমে যেখানেই খেলোয়াড়দের তাদের অগ্রগতি সংরক্ষণ বা পুনরুদ্ধার করার বিকল্প দেওয়া হয়, সেখানেই আপনি স্ন্যাপশট এপিআই (snapshots 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 =
      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);
    }
  });
}

প্লেয়ার যদি নতুন সেভ করা গেম তৈরি করতে বা বিদ্যমান সেভ করা গেম লোড করতে চায়, তাহলে UI প্লে গেমস সার্ভিসেস-এর কাছে একটি অনুরোধ পাঠায়। অনুরোধটি সফল হলে, প্লে গেমস সার্ভিসেস 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. টাস্কের ফলাফল থেকে SnapshotsClient.DataOrConflict.getData() কল করে Snapshot অবজেক্টটি পুনরুদ্ধার করুন।

3. SnapshotsClient.SnapshotConflict ব্যবহার করে একটি SnapshotContents ইনস্ট্যান্স পুনরুদ্ধার করুন।

4. প্লেয়ারের ডেটা বাইট ফরম্যাটে সংরক্ষণ করতে SnapshotContents.writeBytes() কল করুন।

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

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

প্রমাণীকৃত খেলোয়াড়ের জন্য সংরক্ষিত গেম পুনরুদ্ধার করতে:

1. SnapshotsClient.open() ব্যবহার করে অ্যাসিঙ্ক্রোনাসভাবে একটি স্ন্যাপশট খুলুন।

2. টাস্কের ফলাফল থেকে Snapshot অবজেক্টটি পেতে SnapshotsClient.DataOrConflict.getData() কল করুন। বিকল্পভাবে, আপনার গেমটি সেভ করা গেম নির্বাচনের UI-এর মাধ্যমেও একটি নির্দিষ্ট স্ন্যাপশট পেতে পারে, যেমনটি "সেভ করা গেম প্রদর্শন করুন" অংশে বর্ণনা করা হয়েছে।

3. SnapshotsClient.SnapshotConflict ব্যবহার করে SnapshotContents ইনস্ট্যান্সটি পুনরুদ্ধার করুন।

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

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

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

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

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

• সার্ভার সংস্করণ : প্লে গেমস সার্ভিসেস কর্তৃক খেলোয়াড়ের ডিভাইসের জন্য সঠিক ও সর্বাধুনিক সংস্করণ।

• স্থানীয় সংস্করণ : প্লেয়ারের কোনো একটি ডিভাইসে শনাক্ত হওয়া একটি পরিবর্তিত সংস্করণ, যাতে সাংঘর্ষিক বিষয়বস্তু বা মেটাডেটা রয়েছে। এটি আপনার সংরক্ষণ করার চেষ্টা করা সংস্করণটির মতো নাও হতে পারে।

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

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

1. SnapshotsClient.open() কল করুন। টাস্কের ফলাফলে একটি SnapshotsClient.DataOrConflict ক্লাস থাকে।

2. SnapshotsClient.DataOrConflict.isConflict() মেথডটি কল করুন। যদি ফলাফল true হয়, তাহলে সমাধান করার জন্য একটি কনফ্লিক্ট রয়েছে।

3. SnapshotsClient.snapshotConflict ইনস্ট্যান্সটি পেতে 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 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. একটি নতুন SnapshotContents অবজেক্ট পেতে SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent() কল করুন।

3. পূর্ববর্তী ধাপের SnapshotContents অবজেক্টে SnapshotsClient.SnapshotConflict.getConflictingSnapshot() এবং SnapshotsClient.SnapshotConflict.getSnapshot() থেকে প্রাপ্ত ডেটা মার্জ করুন।

4. ঐচ্ছিকভাবে, মেটাডেটা ফিল্ডগুলিতে কোনো পরিবর্তন হলে একটি SnapshotMetadataChange ইনস্ট্যান্স তৈরি করুন।

5. SnapshotsClient.resolveConflict() মেথডটি কল করুন। আপনার মেথড কলে, প্রথম আর্গুমেন্ট হিসেবে SnapshotsClient.SnapshotConflict.getConflictId() এবং যথাক্রমে দ্বিতীয় ও তৃতীয় আর্গুমেন্ট হিসেবে পূর্বে পরিবর্তন করা SnapshotMetadataChange ও SnapshotContents অবজেক্টগুলো পাস করুন।

6. যদি SnapshotsClient.resolveConflict() কলটি সফল হয়, তাহলে API-টি Snapshot অবজেক্টটি সার্ভারে সংরক্ষণ করে এবং আপনার স্থানীয় ডিভাইসে সেটি খোলার চেষ্টা করে।

   • যদি কোনো দ্বন্দ্ব থাকে, তাহলে SnapshotsClient.DataOrConflict.isConflict() true রিটার্ন করে। এক্ষেত্রে, আপনার গেমটিকে ধাপ ২-এ ফিরে যেতে হবে এবং দ্বন্দ্বগুলো সমাধান না হওয়া পর্যন্ত স্ন্যাপশটটি পরিবর্তন করার ধাপগুলো পুনরাবৃত্তি করতে হবে।
   • যদি কোনো দ্বন্দ্ব না থাকে, তাহলে SnapshotsClient.DataOrConflict.isConflict() ফলস false ) রিটার্ন করে এবং Snapshot অবজেক্টটি আপনার গেমের পরিবর্তনের জন্য উন্মুক্ত থাকে।