คู่มือนี้จะแสดงวิธีใช้เกมที่บันทึกไว้โดยใช้ API ภาพรวมที่บริการเกมของ Google Play มีให้ API จะอยู่ในแพ็กเกจ com.google.android.gms.games.snapshot
และ com.google.android.gms.games
ก่อนเริ่มต้น
คุณอาจต้องอ่านแนวคิดเกมสำหรับฟีเจอร์เกมที่บันทึกไว้ หากยังไม่ได้ทำ
- อย่าลืมเปิดใช้การรองรับเกมที่บันทึกไว้สำหรับเกมของคุณใน Google Play Console
- ดาวน์โหลดและตรวจสอบตัวอย่างโค้ดเกมที่บันทึกไว้ในหน้าตัวอย่างของ Android
- ทำความคุ้นเคยกับคําแนะนําที่อธิบายไว้ในรายการตรวจสอบคุณภาพ
รับไคลเอ็นต์สแนปชอต
หากต้องการเริ่มใช้ 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 เกมที่บันทึกไว้เริ่มต้น
- โทรหา
SnapshotsClient.getSelectSnapshotIntent()
เพื่อรับIntent
สำหรับเปิด UI การเลือกเกมที่บันทึกไว้เริ่มต้น - เรียก
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 // ... } } }
เขียนเกมที่บันทึกไว้
วิธีจัดเก็บเนื้อหาลงในเกมที่บันทึกไว้
- เปิดภาพนิ่งแบบไม่พร้อมกันผ่าน
SnapshotsClient.open()
จากนั้นดึงข้อมูลออบเจ็กต์Snapshot
จากผลลัพธ์ของงานโดยเรียกใช้SnapshotsClient.DataOrConflict.getData()
- ดึงข้อมูลอินสแตนซ์
SnapshotContents
ผ่านSnapshotsClient.SnapshotConflict
- เรียกใช้
SnapshotContents.writeBytes()
เพื่อจัดเก็บข้อมูลของผู้เล่นในรูปแบบไบต์ - เมื่อเขียนการเปลี่ยนแปลงทั้งหมดแล้ว ให้เรียกใช้
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
โหลดเกมที่บันทึกไว้
วิธีเรียกข้อมูลเกมที่บันทึกไว้สำหรับผู้เล่นที่ลงชื่อเข้าใช้อยู่ในปัจจุบัน
- เปิดภาพนิ่งแบบไม่พร้อมกันผ่าน
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 = 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 เวอร์ชัน
วิธีตรวจหาและแก้ไขความขัดแย้งของเกมที่บันทึกไว้
- โทรหา
SnapshotsClient.open()
ผลลัพธ์ของงานมีคลาสSnapshotsClient.DataOrConflict
- เรียกใช้เมธอด
SnapshotsClient.DataOrConflict.isConflict()
หากผลลัพธ์เป็น "จริง" แสดงว่าคุณมีความขัดแย้งที่ต้องแก้ไข - โทรหา
SnapshotsClient.DataOrConflict.getConflict()
เพื่อเรียกข้อมูลอินสแตนซ์SnaphotsClient.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 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
ที่มีอยู่เพื่อบันทึกลงในเซิร์ฟเวอร์เป็นเวอร์ชันสุดท้ายที่แก้ไขแล้ว ให้ทำตามขั้นตอนต่อไปนี้
- โทรหา
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
ไว้ให้เกมของคุณแก้ไข
- หากมีความขัดแย้ง