ลีดเดอร์บอร์ดในเกม Android

หลังจากเลิกใช้งาน API ของ Google Sign-In แล้ว เราจะนำ SDK v1 ของเกมออกในปี 2026 หลังจากเดือนกุมภาพันธ์ 2025 คุณจะเผยแพร่ เกมที่เพิ่งผสานรวมกับ SDK v1 ของ Games ใน Google Play ไม่ได้ เราขอแนะนำให้ใช้ SDK v2 ของ Games แทน
แม้ว่าเกมที่มีอยู่ซึ่งผสานรวมกับเกมเวอร์ชัน 1 ก่อนหน้าจะยังคงทำงานได้อีก 2-3 ปี แต่เราขอแนะนำให้คุณย้ายข้อมูลไปยัง v2 ตั้งแต่เดือนมิถุนายน 2025 เป็นต้นไป
คู่มือนี้มีไว้สำหรับการใช้ SDK บริการเกมของ Play เวอร์ชัน 1 ดูข้อมูล เกี่ยวกับ SDK เวอร์ชันล่าสุดได้ที่ เอกสารประกอบ v2

คู่มือนี้แสดงวิธีใช้ API ลีดเดอร์บอร์ดในแอปพลิเคชัน Android เพื่อสร้างลีดเดอร์บอร์ดแบบภาพ บันทึกคะแนนของผู้เล่น และเปรียบเทียบคะแนน กับคะแนนของผู้เล่นจากเซสชันเกมก่อนหน้า คุณดู API ได้ ในแพ็กเกจ com.google.android.gms.games และ com.google.android.gms.games.leaderboards

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

หากยังไม่ได้ดำเนินการ คุณอาจดูแนวคิดเกมลีดเดอร์บอร์ดเพื่อเป็นข้อมูลเพิ่มเติมได้

ก่อนที่จะเริ่มเขียนโค้ดโดยใช้ API ของลีดเดอร์บอร์ด ให้ทำดังนี้

รับไคลเอ็นต์ลีดเดอร์บอร์ด

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

อัปเดตคะแนนของผู้เล่น

เมื่อคะแนนของผู้เล่นเปลี่ยนแปลง (เช่น เมื่อผู้เล่นเล่นเกมจบ) เกมของคุณจะอัปเดตคะแนนของผู้เล่นในลีดเดอร์บอร์ดได้โดยการเรียกใช้ LeaderboardsClient.submitScore() และส่งรหัสลีดเดอร์บอร์ดและค่าคะแนนดิบ

ข้อมูลโค้ดต่อไปนี้แสดงวิธีที่แอปของคุณอัปเดตคะแนนของผู้เล่น

Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .submitScore(getString(R.string.leaderboard_id), 1337);

แนวทางปฏิบัติแนะนำคือการกำหนดรหัสลีดเดอร์บอร์ดในไฟล์ strings.xml เพื่อให้เกมอ้างอิงลีดเดอร์บอร์ดตามรหัสทรัพยากรได้ เมื่อโทรเพื่อ อัปเดตและโหลดคะแนนของผู้เล่น โปรดทำตามแนวทางปฏิบัติแนะนำเหล่านี้ด้วยเพื่อหลีกเลี่ยงการใช้โควต้า API เกิน

แสดงลีดเดอร์บอร์ด

หากต้องการแสดงลีดเดอร์บอร์ด ให้เรียกใช้ LeaderboardsClient.getLeaderboardIntent() เพื่อรับ Intent เพื่อ สร้างอินเทอร์เฟซผู้ใช้ลีดเดอร์บอร์ดเริ่มต้น จากนั้นเกมจะแสดง UI โดยการเรียกใช้ startActivityForResult

ข้อมูลโค้ดต่อไปนี้แสดงวิธีที่แอปอัปเดตคะแนนของผู้เล่น ใน ข้อมูลโค้ด RC_LEADERBOARD_UI คือจำนวนเต็มโดยพลการสำหรับรหัสคำขอ

private static final int RC_LEADERBOARD_UI = 9004;

private void showLeaderboard() {
  Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

โปรดทราบว่าแม้จะไม่มีผลลัพธ์แสดง แต่เราก็ต้องใช้ startActivityForResult เพื่อให้ API รับข้อมูลระบุตัวตนของแพ็กเกจที่เรียกใช้ได้ ตัวอย่าง UI ของลีดเดอร์บอร์ดเริ่มต้น แสดงอยู่ด้านล่าง