คู่มือนี้จะแสดงวิธีใช้เกมที่บันทึกไว้โดยใช้ Snapshots API ที่ Google Play Games Services มีให้ โดยคุณจะดู API ได้ในแพ็กเกจ com.google.android.gms.games.snapshot และ com.google.android.gms.games
ก่อนเริ่มต้น
ดูข้อมูลเกี่ยวกับฟีเจอร์นี้ได้ที่ภาพรวมของเกมที่บันทึกไว้
- เปิดใช้การรองรับเกมที่บันทึกไว้สำหรับเกมของคุณใน Google Play Console
- ดาวน์โหลดและตรวจสอบตัวอย่างโค้ดเกมที่บันทึกไว้ในหน้าตัวอย่าง Android
- ทำความคุ้นเคยกับคําแนะนําที่อธิบายไว้ในรายการตรวจสอบคุณภาพ
รับไคลเอ็นต์สแนปชอต
หากต้องการเริ่มใช้ Snapshots API เกมของคุณจะต้องได้รับออบเจ็กต์ SnapshotsClient ก่อน ซึ่งทำได้โดยการเรียกใช้เมธอด Games.getSnapshotsContents() และส่งกิจกรรม
ระบุขอบเขตไดรฟ์
Snapshots API จะใช้ Google Drive API สำหรับพื้นที่เก็บข้อมูลเกมที่บันทึกไว้ หากต้องการเข้าถึง Drive API แอปของคุณต้องระบุขอบเขต Drive.SCOPE_APPFOLDER เมื่อสร้างไคลเอ็นต์ Google Sign-In
ต่อไปนี้คือตัวอย่างวิธีดำเนินการในเมธอด 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 } } }); }
แสดงเกมที่บันทึกไว้
คุณสามารถผสานรวม Snapshots API ได้ทุกที่ที่เกมมีตัวเลือกให้ผู้เล่นบันทึกหรือกู้คืนความคืบหน้า เกมอาจแสดงตัวเลือกดังกล่าวเมื่อบันทึกหรือกู้คืนที่จุดที่กําหนด หรืออนุญาตให้ผู้เล่นบันทึกหรือกู้คืนความคืบหน้าได้ทุกเมื่อ
เมื่อผู้เล่นเลือกตัวเลือกบันทึกหรือกู้คืนในเกม เกมอาจแสดงหน้าจอที่แจ้งให้ผู้เล่นป้อนข้อมูลสำหรับเกมที่บันทึกใหม่หรือเลือกเกมที่บันทึกไว้เพื่อกู้คืน (ไม่บังคับ)
Snapshots API มีอินเทอร์เฟซผู้ใช้ (UI) การเลือกเกมที่บันทึกไว้เริ่มต้นที่คุณสามารถนำไปใช้ได้ทันที เพื่อช่วยลดความซับซ้อนในการพัฒนา UI การเลือกเกมที่บันทึกไว้ช่วยให้ผู้เล่นสร้างเกมที่บันทึกไว้ใหม่ ดูรายละเอียดเกี่ยวกับเกมที่บันทึกไว้ที่มีอยู่ และโหลดเกมที่บันทึกไว้ก่อนหน้านี้ได้
วิธีเปิด UI เกมที่บันทึกไว้เริ่มต้น
- โทรไปที่
SnapshotsClient.getSelectSnapshotIntent()เพื่อรับIntentสำหรับเปิด UI การเลือกเกมที่บันทึกไว้เริ่มต้น - เรียกใช้
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 จะส่งคำขอไปยังบริการเกมของ Play หากคำขอสำเร็จ บริการเกมของ Play จะแสดงข้อมูลเพื่อสร้างหรือกู้คืนเกมที่บันทึกไว้ผ่าน Callback ของ 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()เรียกข้อมูล
Snapshotออกจากผลลัพธ์ของงานโดยเรียกใช้SnapshotsClient.DataOrConflict.getData()ดึงข้อมูลอินสแตนซ์
SnapshotContentsด้วยSnapshotsClient.SnapshotConflictโทรไปที่
SnapshotContents.writeBytes()เพื่อจัดเก็บข้อมูลของผู้เล่นในรูปแบบไบต์เมื่อเขียนการเปลี่ยนแปลงทั้งหมดแล้ว ให้เรียกใช้
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 = PlayGames.getSnapshotsClient(this); // Commit the operation return snapshotsClient.commitAndClose(snapshot, metadataChange); }
หากอุปกรณ์ของผู้เล่นไม่ได้เชื่อมต่อเครือข่ายเมื่อแอปของคุณเรียกใช้ SnapshotsClient.commitAndClose() บริการ Play Games จะจัดเก็บข้อมูลเกมที่บันทึกไว้ในอุปกรณ์ เมื่ออุปกรณ์เชื่อมต่ออีกครั้ง บริการ Play Games จะซิงค์การเปลี่ยนแปลงเกมที่บันทึกไว้ซึ่งแคชไว้ในเครื่องกับเซิร์ฟเวอร์ของ Google
โหลดเกมที่บันทึกไว้
วิธีเรียกข้อมูลเกมที่บันทึกไว้สำหรับผู้เล่นที่ลงชื่อเข้าใช้อยู่ในปัจจุบัน
เปิดภาพนิ่งแบบไม่พร้อมกันด้วย
SnapshotsClient.open()เรียกใช้ออบเจ็กต์
Snapshotจากผลลัพธ์ของงานโดยเรียกใช้SnapshotsClient.DataOrConflict.getData()นอกจากนี้ เกมยังสามารถเรียกข้อมูลภาพหน้าจอที่เฉพาะเจาะจงผ่าน UI การเลือกเกมที่บันทึกไว้ได้ ตามที่อธิบายไว้ในแสดงเกมที่บันทึกไว้ดึงข้อมูลอินสแตนซ์
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. // ... } }); }
จัดการข้อขัดแย้งของเกมที่บันทึกไว้
เมื่อใช้ Snapshots API ในเกม อุปกรณ์หลายเครื่องสามารถอ่านและเขียนในเกมที่บันทึกไว้เดียวกันได้ ในกรณีที่อุปกรณ์ตัดการเชื่อมต่อเครือข่ายชั่วคราวและเชื่อมต่ออีกครั้งในภายหลัง การดำเนินการนี้อาจทำให้เกิดความขัดแย้งของข้อมูล ซึ่งเกมที่บันทึกไว้ซึ่งจัดเก็บไว้ในอุปกรณ์ของผู้เล่นจะไม่ซิงค์กับเวอร์ชันระยะไกลที่จัดเก็บไว้ในเซิร์ฟเวอร์ของ Google
Snapshots API มีกลไกการแก้ไขความขัดแย้งซึ่งแสดงทั้งชุดเกมที่บันทึกไว้ซึ่งขัดแย้งกัน ณ เวลาอ่าน และให้คุณใช้กลยุทธ์การแก้ไขที่เหมาะสมกับเกมของคุณ
เมื่อบริการ Play Games ตรวจพบความขัดแย้งของข้อมูล วิธีการ SnapshotsClient.DataOrConflict.isConflict() จะแสดงผลเป็นค่า true ในกรณีนี้ คลาส SnapshotsClient.SnapshotConflict จะมีเกมที่บันทึกไว้ 2 เวอร์ชัน ดังนี้
เวอร์ชันเซิร์ฟเวอร์: เวอร์ชันล่าสุดที่บริการ Play Games ทราบว่าถูกต้องสำหรับอุปกรณ์ของผู้เล่น
เวอร์ชันในเครื่อง: เวอร์ชันที่แก้ไขแล้วซึ่งตรวจพบในอุปกรณ์ของผู้เล่นเครื่องใดเครื่องหนึ่งซึ่งมีเนื้อหาหรือข้อมูลเมตาที่ขัดแย้งกัน ซึ่งอาจไม่ใช่เวอร์ชันเดียวกับที่คุณพยายามบันทึก
เกมต้องตัดสินใจว่าจะแก้ไขข้อขัดแย้งอย่างไรโดยเลือกเวอร์ชันใดเวอร์ชันหนึ่งที่มีให้ หรือผสานข้อมูลของเกมที่บันทึกไว้ 2 เวอร์ชัน
วิธีตรวจหาและแก้ไขความขัดแย้งของเกมที่บันทึกไว้
โทรไปที่
SnapshotsClient.open()ผลลัพธ์ของงานมีคลาสSnapshotsClient.DataOrConflictเรียกใช้เมธอด
SnapshotsClient.DataOrConflict.isConflict()หากผลลัพธ์เป็น "จริง" แสดงว่าคุณมีข้อขัดแย้งที่ต้องแก้ไขโทรไปที่
SnapshotsClient.DataOrConflict.getConflict()เพื่อเรียกข้อมูลอินสแตนซ์SnapshotsClient.snapshotConflictโทรไปที่
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()เรียกใช้
SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent()เพื่อรับออบเจ็กต์SnapshotContentsใหม่ผสานข้อมูลจาก
SnapshotsClient.SnapshotConflict.getConflictingSnapshot()และSnapshotsClient.SnapshotConflict.getSnapshot()เข้ากับออบเจ็กต์SnapshotContentsจากขั้นตอนก่อนหน้าสร้างอินสแตนซ์
SnapshotMetadataChangeหรือไม่ก็ได้หากมีการเปลี่ยนแปลงในช่องข้อมูลเมตาโทรไปที่
SnapshotsClient.resolveConflict()ในการเรียกใช้เมธอด ให้ส่งSnapshotsClient.SnapshotConflict.getConflictId()เป็นอาร์กิวเมนต์แรก และส่งออบเจ็กต์SnapshotMetadataChangeและSnapshotContentsที่คุณแก้ไขไว้ก่อนหน้านี้เป็นอาร์กิวเมนต์ที่ 2 และ 3 ตามลำดับหากการเรียกใช้
SnapshotsClient.resolveConflict()สำเร็จ API จะจัดเก็บออบเจ็กต์Snapshotไว้ในเซิร์ฟเวอร์และพยายามเปิดออบเจ็กต์สแนปชอตในอุปกรณ์เครื่องนั้น- หากมีข้อขัดแย้ง
SnapshotsClient.DataOrConflict.isConflict()จะแสดงผลเป็นtrueในกรณีนี้ เกมควรกลับไปที่ขั้นตอนที่ 2 แล้วทำตามขั้นตอนเพื่อแก้ไขภาพรวมซ้ำจนกว่าข้อขัดแย้งจะได้รับการแก้ไข - หากไม่มีข้อขัดแย้ง
SnapshotsClient.DataOrConflict.isConflict()จะแสดงผลลัพธ์เป็นfalseและออบเจ็กต์Snapshotจะเปิดอยู่เพื่อให้เกมของคุณแก้ไข
- หากมีข้อขัดแย้ง