การรองรับเกมที่บันทึกไว้ในเกม Android

คู่มือนี้จะแสดงวิธีใช้เกมที่บันทึกไว้โดยใช้ API ภาพรวมที่บริการเกมของ Google Play มีให้ API จะอยู่ในแพ็กเกจ com.google.android.gms.games.snapshot และ com.google.android.gms.games

ก่อนเริ่มต้น

คุณอาจต้องอ่านแนวคิดเกมสำหรับฟีเจอร์เกมที่บันทึกไว้ หากยังไม่ได้ทำ

รับไคลเอ็นต์สแนปชอต

หากต้องการเริ่มใช้ Snapshots API เกมของคุณจะต้องได้รับออบเจ็กต์ SnapshotsClient ก่อน ซึ่งทำได้โดยการเรียกใช้เมธอด Games.getSnapshotsClient() และส่งกิจกรรมและ GoogleSignInAccount ของเพลเยอร์ปัจจุบัน ดูวิธีเรียกข้อมูลบัญชีผู้เล่นได้ที่การลงชื่อเข้าใช้ใน Android Games

ระบุขอบเขตไดรฟ์

Snapshots API ต้องใช้ Google Drive API สำหรับพื้นที่เก็บข้อมูลเกมที่บันทึกไว้ หากต้องการเข้าถึง Drive API แอปของคุณต้องระบุขอบเขต Drive.SCOPE_APPFOLDER เมื่อสร้างไคลเอ็นต์ Google Sign-In

ต่อไปนี้เป็นตัวอย่างวิธีดำเนินการในวิธี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
          }
        }
      });
}

แสดงเกมที่บันทึกไว้

คุณสามารถผสานรวม Snapshots API ได้ทุกที่ที่เกมของคุณให้ตัวเลือกแก่ผู้เล่นในการบันทึกหรือกู้คืนความคืบหน้า เกมของคุณอาจแสดงตัวเลือกดังกล่าวเมื่อถึงจุดบันทึก/กู้คืนที่กําหนด หรืออนุญาตให้ผู้เล่นบันทึกหรือกู้คืนความคืบหน้าได้ทุกเมื่อ

เมื่อผู้เล่นเลือกตัวเลือกบันทึก/กู้คืนในเกม เกมอาจแสดงหน้าจอที่แจ้งให้ผู้เล่นป้อนข้อมูลสำหรับเกมที่บันทึกใหม่ หรือเลือกเกมที่บันทึกไว้เพื่อกู้คืน

Snapshots API มีอินเทอร์เฟซผู้ใช้ (UI) การเลือกเกมที่บันทึกไว้เริ่มต้นที่คุณสามารถนำไปใช้ได้ทันที เพื่อลดความซับซ้อนในการพัฒนา UI การเลือกเกมที่บันทึกไว้ช่วยให้ผู้เล่นสร้างเกมที่บันทึกไว้ใหม่ ดูรายละเอียดเกี่ยวกับเกมที่บันทึกไว้ที่มีอยู่ และโหลดเกมที่บันทึกไว้ก่อนหน้านี้ได้

วิธีเปิด UI เกมที่บันทึกไว้เริ่มต้น

  1. โทรหา SnapshotsClient.getSelectSnapshotIntent() เพื่อรับ Intent สำหรับเปิด UI การเลือกเกมที่บันทึกไว้เริ่มต้น
  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 จะแสดงข้อมูลเพื่อสร้างหรือกู้คืนเกมที่บันทึกไว้ผ่าน onActivityResult() callback เกมสามารถลบล้างการเรียกกลับนี้เพื่อตรวจสอบว่ามีข้อผิดพลาดเกิดขึ้นระหว่างคำขอหรือไม่

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างการใช้งาน 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() จากนั้นดึงข้อมูลออบเจ็กต์ Snapshot จากผลลัพธ์ของงานโดยเรียกใช้ SnapshotsClient.DataOrConflict.getData()
  2. ดึงข้อมูลอินสแตนซ์ SnapshotContents ผ่าน SnapshotsClient.SnapshotConflict
  3. เรียกใช้ SnapshotContents.writeBytes() เพื่อจัดเก็บข้อมูลของผู้เล่นในรูปแบบไบต์
  4. เมื่อเขียนการเปลี่ยนแปลงทั้งหมดแล้ว ให้เรียกใช้ SnapshotsClient.commitAndClose() เพื่อส่งการเปลี่ยนแปลงไปยังเซิร์ฟเวอร์ของ Google ในการเรียกใช้เมธอด เกมของคุณอาจระบุข้อมูลเพิ่มเติมเพื่อบอกบริการ 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 จะจัดเก็บข้อมูลเกมที่บันทึกไว้ไว้ในอุปกรณ์ เมื่ออุปกรณ์เชื่อมต่ออีกครั้ง บริการ Google Play Games จะซิงค์การเปลี่ยนแปลงของเกมที่บันทึกไว้ซึ่งแคชไว้ในเครื่องกับเซิร์ฟเวอร์ของ Google

โหลดเกมที่บันทึกไว้

วิธีเรียกข้อมูลเกมที่บันทึกไว้สำหรับผู้เล่นที่ลงชื่อเข้าใช้อยู่ในปัจจุบัน

  1. เปิดภาพนิ่งแบบไม่พร้อมกันผ่าน SnapshotsClient.open() จากนั้นดึงข้อมูลออบเจ็กต์ Snapshot จากผลลัพธ์ของงานโดยเรียกใช้ SnapshotsClient.DataOrConflict.getData() หรือเกมจะเรียกข้อมูลภาพรวมที่เฉพาะเจาะจงผ่าน UI การเลือกเกมที่บันทึกไว้ก็ได้ ตามที่อธิบายไว้ในแสดงเกมที่บันทึกไว้
  2. ดึงข้อมูลอินสแตนซ์ SnapshotContents ผ่าน SnapshotsClient.SnapshotConflict
  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.
          // ...
        }
      });
}

จัดการข้อขัดแย้งของเกมที่บันทึกไว้

เมื่อใช้ Snapshots API ในเกม อุปกรณ์หลายเครื่องสามารถอ่านและเขียนในเกมที่บันทึกไว้เดียวกันได้ ในกรณีที่อุปกรณ์ขาดการเชื่อมต่อเครือข่ายชั่วคราวและเชื่อมต่ออีกครั้งในภายหลัง ปัญหานี้อาจทำให้เกิดความขัดแย้งของข้อมูล ซึ่งเกมที่บันทึกไว้ในอุปกรณ์เครื่องของผู้เล่นจะไม่ซิงค์กับเวอร์ชันระยะไกลที่จัดเก็บไว้ในเซิร์ฟเวอร์ของ Google

Snapshots API มีกลไกการแก้ไขความขัดแย้งซึ่งแสดงทั้งชุดเกมที่บันทึกไว้ซึ่งขัดแย้งกัน ณ เวลาอ่าน และให้คุณใช้กลยุทธ์การแก้ไขที่เหมาะสมกับเกมของคุณ

เมื่อบริการ Google Play Games ตรวจพบความขัดแย้งของข้อมูล เมธอด SnapshotsClient.DataOrConflict.isConflict() จะแสดงผลค่า true ในกรณีนี้ คลาส SnapshotsClient.SnapshotConflict จะมีเกมที่บันทึกไว้ 2 เวอร์ชัน ดังนี้

  • เวอร์ชันเซิร์ฟเวอร์: เวอร์ชันล่าสุดที่บริการ Google Play Games ทราบว่าถูกต้องสำหรับอุปกรณ์ของผู้เล่น และ
  • เวอร์ชันในเครื่อง: เวอร์ชันที่แก้ไขซึ่งตรวจพบในอุปกรณ์ของผู้เล่นเครื่องใดเครื่องหนึ่งซึ่งมีเนื้อหาหรือข้อมูลเมตาที่ขัดแย้งกัน ซึ่งอาจไม่ใช่เวอร์ชันที่คุณพยายามบันทึก

เกมต้องตัดสินใจว่าจะแก้ไขข้อขัดแย้งอย่างไร โดยเลือกเวอร์ชันใดเวอร์ชันหนึ่งที่มีให้ หรือผสานข้อมูลของเกมที่บันทึกไว้ 2 เวอร์ชัน

วิธีตรวจหาและแก้ไขความขัดแย้งของเกมที่บันทึกไว้

  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 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. เรียกใช้ SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent() เพื่อรับออบเจ็กต์ SnapshotContents ใหม่
  3. ผสานข้อมูลจาก SnapshotsClient.SnapshotConflict.getConflictingSnapshot() และ SnapshotsClient.SnapshotConflict.getSnapshot() เข้ากับออบเจ็กต์ SnapshotContents จากขั้นตอนก่อนหน้า
  4. คุณอาจสร้างอินสแตนซ์ SnapshotMetadataChange ก็ได้หากมีการเปลี่ยนแปลงในฟิลด์ข้อมูลเมตา
  5. โทรหา SnapshotsClient.resolveConflict() ในการเรียกใช้เมธอด ให้ส่ง SnapshotsClient.SnapshotConflict.getConflictId() เป็นอาร์กิวเมนต์แรก และส่งออบเจ็กต์ SnapshotMetadataChange และ SnapshotContents ที่คุณแก้ไขไว้ก่อนหน้านี้เป็นอาร์กิวเมนต์ที่ 2 และ 3 ตามลำดับ
  6. หากการเรียก SnapshotsClient.resolveConflict() สำเร็จ API จะจัดเก็บออบเจ็กต์ Snapshot ลงในเซิร์ฟเวอร์และพยายามเปิดออบเจ็กต์สแนปชอตในอุปกรณ์เครื่องนั้น
    • หากมีความขัดแย้ง SnapshotsClient.DataOrConflict.isConflict() จะแสดงผลเป็น true ในกรณีนี้ เกมควรกลับไปที่ขั้นตอนที่ 2 แล้วทำตามขั้นตอนเพื่อแก้ไขภาพรวมซ้ำจนกว่าข้อขัดแย้งจะได้รับการแก้ไข
    • หากไม่มีข้อขัดแย้ง SnapshotsClient.DataOrConflict.isConflict() จะแสดงผลลัพธ์เป็น false และระบบจะเปิดออบเจ็กต์ Snapshot ไว้ให้เกมของคุณแก้ไข