الألعاب المحفوظة لألعاب Android

يوضِّح لك هذا الدليل كيفية تنفيذ الألعاب المحفوظة باستخدام واجهة برمجة التطبيقات الخاصة بـ "لقطات الشاشة" التي توفّرها "خدمات ألعاب Google Play". يمكن العثور على واجهات برمجة التطبيقات في حِزمتَي com.google.android.gms.games.snapshot وcom.google.android.gms.games.

قبل البدء

للحصول على معلومات عن الميزة، يُرجى الاطّلاع على نظرة عامة على الألعاب المحفوظة.

• فعِّل إمكانية استخدام الألعاب المحفوظة للعبتك في Google Play Console.
• نزِّل نموذج رمز الألعاب المحفوظ وراجِعه في صفحة نماذج Android.
• ننصحك بالتعرّف على الاقتراحات الموضّحة في قائمة التحقّق من الجودة.

الحصول على عميل اللقطات

لبدء استخدام واجهة برمجة تطبيقات لقطات الشاشة، يجب أن تحصل لعبتك أولاً على عنصر SnapshotsClient. يمكنك إجراء ذلك من خلال استدعاء طريقة Games.getSnapshotsClient() وتمرير النشاط.

ملاحظة: تستخدم الصف SnapshotsClient فئة خدمات Google Play Task لعرض النتائج على نحو غير متزامن. لمزيد من المعلومات حول استخدام المهام لإدارة سلسلة المحادثات، راجِع دليل مطوّر برامج واجهة برمجة تطبيقات "مهام Google".

تحديد نطاق Drive

تعتمد واجهة برمجة تطبيقات اللقطات على Google Drive API لتخزين الألعاب المحفوظة. للوصول إلى Drive API، يجب أن يحدّد تطبيقك نطاق Drive.SCOPE_APPFOLDER عند إنشاء برنامج تسجيل الدخول بحساب Google.

إليك مثال على كيفية إجراء ذلك في طريقة 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
          }
        }
      });
}

عرض الألعاب المحفوظة

يمكنك دمج واجهة برمجة تطبيقات لقطات في المكان الذي توفّر فيه لعبتك للّاعبين خيار حفظ مستوى التقدّم أو استعادته. وقد تعرض لعبتك مثل هذا الخيار عند نقاط حفظ أو استعادة معيّنة، أو قد تسمح للّاعبين بحفظ مستوى التقدّم أو استعادته في أي وقت.

بعد أن يحدد اللاعبون خيار الحفظ/الاستعادة في لعبتك، يمكن أن تعرض لعبتك اختياريًا شاشة تطلب من اللاعبين إدخال معلومات حول لعبة جديدة محفوظة أو اختيار لعبة حالية محفوظة لاستعادتها.

لتبسيط عملية التطوير، توفّر واجهة برمجة تطبيقات لقطات الشاشة واجهة مستخدم افتراضية لاختيار الألعاب المحفوظة التي يمكن استخدامها بشكل فوري. تسمح واجهة مستخدم اختيار الألعاب المحفوظة للّاعبين بإنشاء لعبة جديدة محفوظة وعرض تفاصيل حول الألعاب المحفوظة الحالية وتحميل المباريات السابقة المحفوظة.

لتشغيل واجهة المستخدم التلقائية للألعاب المحفوظة:

1. يمكنك الاتصال بالرقم SnapshotsClient.getSelectSnapshotIntent() للحصول على Intent لتشغيل واجهة المستخدم التلقائية لاختيار الألعاب المحفوظة.
2. يمكنك الاتصال بـ 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);
    }
  });
}

إذا اختار اللاعب إنشاء لعبة جديدة محفوظة أو تحميل لعبة حالية محفوظة، سترسل واجهة المستخدم طلبًا إلى "خدمات ألعاب Play". في حال نجاح الطلب، تعرض "خدمات ألعاب 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
      // ...
    }
  }
}

كتابة الألعاب المحفوظة

لتخزين المحتوى في لعبة محفوظة:

1. افتح لقطة بشكل غير متزامن من خلال SnapshotsClient.open().

2. يمكنك استرداد الكائن Snapshot من نتيجة المهمة من خلال طلب الرمز SnapshotsClient.DataOrConflict.getData().

3. استرِد SnapshotContents نسخة افتراضية باستخدام SnapshotsClient.SnapshotConflict.

4. استدعِ 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" بيانات اللعبة المحفوظة محليًا على الجهاز. عند إعادة اتصال الجهاز، تزامن "خدمات ألعاب 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.
          // ...
        }
      });
}

التعامل مع تعارضات الألعاب المحفوظة

عند استخدام واجهة برمجة تطبيقات لقطات الشاشة في لعبتك، بإمكان أجهزة متعددة أن تقوم بالقراءة والكتابة على اللعبة نفسها المحفوظة. إذا انقطع اتصال الجهاز بالشبكة مؤقتًا وأعاد الاتصال به لاحقًا، قد يؤدي ذلك إلى حدوث تعارض في البيانات، حيث تكون اللعبة المحفوظة على الجهاز المحلي للّاعب غير متزامنة مع النسخة البعيدة المخزَّنة في خوادم Google.

توفّر واجهة برمجة تطبيقات لقطات الشاشة آلية لحل التعارضات تعرض كلاً من مجموعتَي الألعاب المحفوظة المتعارضة في وقت القراءة، وتتيح لك تنفيذ استراتيجية حل مناسبة للعبتك.

عندما تكتشف "خدمات ألعاب Play" حدوث تعارض في البيانات، تعرض الطريقة SnapshotsClient.DataOrConflict.isConflict() القيمة true. في هذا الحدث، توفّر الفئة SnapshotsClient.SnapshotConflict إصدارَين من اللعبة المحفوظة:

• إصدار الخادم: أحدث إصدار معروف من "خدمات ألعاب Play" بأنّه دقيق لجهاز اللاعب.

• الإصدار المحلي: إصدار معدَّل تم رصده على أحد أجهزة المشغّل ويتضمّن بيانات وصفية أو محتوى متعارضًا. قد لا يكون هذا هو نفس الإصدار الذي حاولت حفظه.

يجب أن تحدّد لعبتك كيفية حلّ التعارض من خلال اختيار إحدى الإصدارات المتوفّرة أو دمج بيانات إصدارَي اللعبة المحفوظَين.

لرصد تعارضات الألعاب المحفوظة وحلّها:

1. اتصل على SnapshotsClient.open(). تتضمّن نتيجة المهمة فئة SnapshotsClient.DataOrConflict.

2. عليك استدعاء الطريقة SnapshotsClient.DataOrConflict.isConflict(). إذا كانت النتيجة صحيحة، فهذا يعني أن هناك تعارضًا يجب حله.

3. اتصِل بـ SnapshotsClient.DataOrConflict.getConflict() لاسترداد SnaphotsClient.snapshotConflict مثيل.

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. عليك استدعاء 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()، تخزّن واجهة برمجة التطبيقات الكائن Snapshot على الخادم وتحاول فتح الكائن Snapshot على جهازك المحلي.

   • إذا كان هناك تعارض، فإن SnapshotsClient.DataOrConflict.isConflict() تعرض true. في هذه الحالة، يجب أن تعود لعبتك إلى الخطوة الثانية وتكرر هذه الخطوات لتعديل اللقطة إلى أن يتم حل التعارضات.
   • إذا لم يكن هناك أي تعارض، تعرض SnapshotsClient.DataOrConflict.isConflict() القيمة false ويكون الكائن Snapshot متاحًا للتعديل في اللعبة.