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

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