Bảng xếp hạng

Bạn có thể hiển thị bảng xếp hạng tùy chỉnh theo cá nhân trên trang trò chơi hiển thị kết quả của những người chơi hàng đầu và vị trí của người dùng trong bảng xếp hạng.

Để các yêu cầu bên dưới hoạt động, hãy đảm bảo rằng:

Chú ý

Khi ứng dụng của bạn yêu cầu bảng xếp hạng, hãy đảm bảo rằng tên bảng xếp hạng trong yêu cầu khớp với tên bảng xếp hạng trong Technical leaderboard name trong Bảng điều khiển trò chơi. Nếu không, yêu cầu sẽ trả về lỗi 404.

Khởi tạo

Để gọi các phương thức bảng xếp hạng trực tiếp, hãy truy cập ysdk.leaderboards.

Hạn chế

Việc khởi tạo đối tượng lb bằng phương thức ysdk.getLeaderboards() đã lỗi thời.

Các phương thức cũ
var lb;

ysdk.getLeaderboards()
  .then(_lb => lb = _lb);

  // Các phương thức bảng xếp hạng khi gọi qua cách cũ:
  // lb.getLeaderboardDescription() → ysdk.leaderboards.getDescription()
  // lb.setLeaderboardScore() → ysdk.leaderboards.setScore()
  // lb.getLeaderboardPlayerEntry() → ysdk.leaderboards.getPlayerEntry()
  // lb.getLeaderboardEntries() → ysdk.leaderboards.getEntries()

Mô tả bảng xếp hạng

Để nhận mô tả về bảng xếp hạng theo tên, hãy sử dụng phương thức ysdk.leaderboards.getDescription():

getDescription(
  leaderboardName: string
)

Tham số

Mô tả

leaderboardName

Tên bảng xếp hạng.

 
ysdk.leaderboards.getDescription('leaderboard2021')
  .then(res => console.log(res));

const work = async () => {
  const res = await ysdk.leaderboards.getDescription('leaderboard2021');
  console.log(res);
}

work();

Định dạng phản hồi

{
  appID: string,
  default: boolean,
  description: {
    invert_sort_order: boolean,
    score_format: {
      options: {
        decimal_offset: integer
      },
      type: string
    }
  },
  name: string,
  title: {
    en: string,
    ru: string
  }
}

Tham số

Mô tả

appID

ID ứng dụng.

default

Nếu là true, thì đó là bảng xếp hạng chính.

invert_sort_order

Thứ tự sắp xếp:

  • false: Các vị trí được sắp xếp theo thứ tự giảm dần.
  • true: Các vị trí được sắp xếp theo thứ tự tăng dần.

decimal_offset

Độ dịch chuyển điểm. Ví dụ: với decimal_offset: 2, số 1234 sẽ được hiển thị là 12,34.

type

Loại kết quả trên bảng xếp hạng. Các tham số được chấp nhận: numeric (số), time (tính bằng giây).

name

Tên bảng xếp hạng.

title

Tên bản địa hóa. Các tham số mảng có thể: ru, en, be, uk, kk, uz, tr.

Điểm số mới

Chú ý

Yêu cầu chỉ dành cho người dùng được cho phép. Nếu cần, hãy yêu cầu sự cho phép.

Để kiểm tra xem phương thức này có dùng được cho người dùng hay không, bạn có thể sử dụng phương thức ysdk.isAvailableMethod('leaderboards.setScore'). Phương thức này trả về Promise<Boolean>, trong đó giá trị boolean cho biết liệu phương thức có dùng được hay không.

Nếu bạn muốn lưu kết quả cho tất cả người dùng bất kể trạng thái đăng nhập của họ, bạn nên thêm bảng xếp hạng tùy chỉnh theo cách thủ công trong mã nguồn ứng dụng của mình. Bạn có thể tự do lựa chọn bất kỳ công nghệ nào cho mục đích này.

Để thiết lập điểm số mới cho người chơi, hãy sử dụng phương thức ysdk.leaderboards.setScore().

setScore(
  leaderboardName: string,
  score: number,
  extraData?: string
)

Tham số

Mô tả

leaderboardName

Tên bảng xếp hạng.

score

Điểm số. Chỉ chấp nhận loại dữ liệu integer. Giá trị không âm, có giá trị tối đa chỉ bị giới hạn bởi logic JavaScript. Nếu loại bảng xếp hạng là time, các giá trị phải được truyền vào theo đơn vị mili giây.

extraData

Mô tả người dùng. Tham số tùy chọn.

Ghi chú

Giới hạn số lượng yêu cầu là 60 lần mỗi phút. Nếu không, yêu cầu sẽ bị từ chối cùng với lỗi.

// Không có extraData.
ysdk.leaderboards.setScore('leaderboard2021', 120);
// Có extraData.
ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');

const work = async () => {
  // Không có extraData.
  await ysdk.leaderboards.setScore('leaderboard2021', 120);
  // Có extraData.
  await ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');
}

work();

Nhận xếp hạng

Chú ý

Yêu cầu chỉ dành cho người dùng được cho phép. Nếu cần, hãy yêu cầu sự cho phép.

Để kiểm tra xem phương thức có dùng được cho người dùng hay không, bạn có thể sử dụng phương thức ysdk.isAvailableMethod('leaderboards.getPlayerEntry'). Phương thức này trả về Promise<Boolean>, trong đó giá trị boolean cho biết liệu phương thức có dùng được hay không.

Nếu bạn muốn lưu kết quả cho tất cả người dùng bất kể trạng thái đăng nhập của họ, bạn nên thêm bảng xếp hạng tùy chỉnh theo cách thủ công trong mã nguồn ứng dụng của mình. Bạn có thể tự do lựa chọn bất kỳ công nghệ nào cho mục đích này.

Để nhận xếp hạng của người dùng, hãy sử dụng phương thức ysdk.leaderboards.getPlayerEntry():

getPlayerEntry(
  leaderboardName: string
)

Tham số

Mô tả

leaderboardName

Tên bảng xếp hạng.

Ghi chú

Giới hạn số lượng yêu cầu là 60 lần trong năm phút. Nếu không, yêu cầu sẽ bị từ chối cùng với lỗi.

ysdk.leaderboards.getPlayerEntry('leaderboard2021')
  .then(res => console.log(res))
  .catch(err => {
    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
      // Lỗi này được trả về nếu bảng xếp hạng không có mục nhập cho người chơi.
    }
  });

const work = async () => {
  try {
    const res = await ysdk.leaderboards.getPlayerEntry('leaderboard2021');
    console.log(res);
  } catch (err) {
    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
      // Lỗi này được trả về nếu bảng xếp hạng không có mục nhập cho người chơi.
    }
  }
}

work();

Định dạng phản hồi

{
  score: integer,
  extraData: string,
  rank: integer,
  player: {
    getAvatarSrc: (size: string) => string,
    getAvatarSrcSet: (size: string) => string,
    lang: string,
    publicName: string,
    scopePermissions: {
      avatar: string,
      public_name: string
    },
    uniqueID: string,
  },
  formattedScore: string
}

Tham số

Mô tả

score

Điểm số. Chỉ chấp nhận loại dữ liệu integer. Giá trị không âm, có giá trị tối đa chỉ bị giới hạn bởi logic JavaScript. Nếu loại bảng xếp hạng là time, các giá trị phải được truyền vào theo đơn vị mili giây.

extraData

Mô tả người dùng. Tham số tùy chọn.

getAvatarSrc

Trả về URL của ảnh người dùng. Các giá trị size được chấp nhận: small, medium và large.

getAvatarSrcSet

Trả về srcset ảnh của người dùng phù hợp với màn hình Retina. Các giá trị size được chấp nhận: small, medium và large.

Mục nhập bảng xếp hạng

Để hiển thị xếp hạng của người dùng, hãy sử dụng phương thức ysdk.leaderboards.getEntries():

getEntries(
  leaderboardName: string,
  {
    includeUser: boolean,
    quantityAround: integer,
    quantityTop: integer
  }
)

Tham số

Mô tả

leaderboardName

Tên bảng xếp hạng.

includeUser

Xác định xem có bao gồm người dùng đã đăng nhập trong phản hồi hay không:

  • true: Bao gồm trong phản hồi.
  • false (giá trị mặc định): Không bao gồm.

quantityAround

Số lượng mục nhập cần trả về bên dưới và bên trên người dùng trong bảng xếp hạng. Giá trị tối thiểu là 1. Giá trị tối đa là 10. Giá trị trả về mặc định là 5.

quantityTop

Số lượng mục nhập từ đầu bảng xếp hạng. Giá trị tối thiểu là 1. Giá trị tối đa là 20. Giá trị trả về mặc định là 5.

Ghi chú

Giới hạn số lượng yêu cầu là 20 lần trong năm phút. Nếu không, yêu cầu sẽ bị từ chối cùng với lỗi.

// Sử dụng tất cả các giá trị mặc định.
ysdk.leaderboards.getEntries('leaderboard2021')
  .then(res => console.log(res));
// Yêu cầu 10 mục nhập hàng đầu.
ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10 })
  .then(res => console.log(res));
// Yêu cầu 10 mục nhập hàng đầu và 3 mục nhập bên trên và bên dưới mục nhập của người dùng.
ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 })
  .then(res => console.log(res));

const work = async () => {
  let res;
  // Sử dụng tất cả các giá trị mặc định.
  res = await ysdk.leaderboards.getEntries('leaderboard2021');
  console.log(res);
  // Yêu cầu 10 mục nhập hàng đầu.
  res = await ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10 });
  console.log(res);
  // Yêu cầu 10 mục nhập hàng đầu và 3 mục nhập bên trên và bên dưới mục nhập của người dùng.
  res = await ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 });
  console.log(res);
}

work();

Định dạng phản hồi

{
  leaderboard: {
    ...
  },
  ranges: [
    {
      start: integer,
      size: integer
    }
  ],
  userRank: integer,
  entries: [
    {
      score: integer,
      extraData: string,
      rank: integer,
      player: {
        getAvatarSrc: (size: string) => string,
        getAvatarSrcSet: (size: string) => string,
        lang: string,
        publicName: string,
        scopePermissions: {
          avatar: string,
          public_name: string
        },
        uniqueID: string,
      },
    formattedScore: string
    },
    ...
  ]
}

Tham số

Mô tả

leaderboard

Mô tả bảng xếp hạng.

ranges

Khoảng xếp hạng trong phản hồi.

start

Vị trí trong bảng xếp hạng. Đánh số bắt đầu từ số không, vì vậy phần tử thứ 0 là vị trí đầu tiên.

size

Số lượng mục nhập được yêu cầu. Nếu không có đủ dữ liệu, số được trả về có thể không phải là số được yêu cầu.

userRank

Xếp hạng của người dùng. Trả về 0 nếu điểm số của người dùng không có trong bảng xếp hạng hoặc nếu yêu cầu dành cho các xếp hạng hàng đầu trong đó không có người dùng.

entries

Các mục nhập được yêu cầu.

score

Điểm số. Chỉ chấp nhận loại dữ liệu integer. Giá trị không âm, có giá trị tối đa chỉ bị giới hạn bởi logic JavaScript. Nếu loại bảng xếp hạng là time, các giá trị phải được truyền vào theo đơn vị mili giây.

extraData

Mô tả người dùng. Tham số tùy chọn.

getAvatarSrc

Trả về URL của ảnh người dùng. Các giá trị size được chấp nhận: small, medium và large.

getAvatarSrcSet

Trả về srcset ảnh của người dùng phù hợp với màn hình Retina. Các giá trị size được chấp nhận: small, medium và large.

Giới hạn yêu cầu phương thức

Phương thức

Mô tả

Giới hạn

Đăng nhập của người dùng

ysdk.leaderboards.setScore()

Thiết lập điểm số mới cho người chơi

60 yêu cầu mỗi phút

Bắt buộc

ysdk.leaderboards.getPlayerEntry()

Trả về vị trí xếp hạng trên bảng xếp hạng cho một người dùng

60 yêu cầu trong năm phút

Bắt buộc

ysdk.leaderboards.getEntries()

Trả về các vị trí xếp hạng trên bảng xếp hạng cho nhiều người dùng

20 yêu cầu trong năm phút

Tùy chọn

Giới hạn cho các yêu cầu khác là 20 yêu cầu trong năm phút.

Các vấn đề đã biết

Lời khuyên

Khi sử dụng các phương thức ysdk.isAvailableMethod() và ysdk.leaderboards.setScore() cùng nhau, người dùng đã đăng xuất không xuất hiện trên bảng xếp hạng và không thể thấy tiến trình của họ. Bạn có thể tạo một bảng xếp hạng khác có điểm số của tất cả người dùng và hiển thị bảng xếp hạng này cho mọi người. Bạn có thể tạo bảng xếp hạng tùy chỉnh trong mã nguồn ứng dụng bằng bất kỳ công nghệ nào bạn thích.

Đối tượng đã tồn tại

Xảy ra lỗi khi tìm cách tạo bảng xếp hạng mới có tên của một bảng xếp hạng cũ. Để tránh vấn đề này, hãy nhập tên bạn chưa sử dụng trước đây.

Người dùng bị ẩn

Dòng chữ "Người dùng ẩn danh" hiển thị khi người chơi không cho phép sử dụng avatar và tên của họ. Quyền truy cập vào dữ liệu người dùng phụ thuộc vào cài đặt trong hồ sơ của họ. Xem thêm chi tiết trong phần Dữ liệu người chơi.

Lỗi 404

Nếu gặp lỗi 404 khi cố gắng gọi các phương thức SDK cho bảng xếp hạng, hãy kiểm tra xem đã tạo bảng xếp hạng với tên tương ứng trong trường Technical leaderboard name trong console của nhà phát triển.

Ghi chú

Nhân viên hỗ trợ sẽ giúp bạn đăng bài trò chơi đã hoàn thiện lên nền tảng trò chơi của Yandex. Để đặt các câu hỏi về việc phát triển và kiểm thử, các nhà phát triển khác sẽ trả lời chuyên sâu trong Kênh Discord.

Nếu bạn đang gặp phải vấn đề hoặc có câu hỏi liên quan đến việc sử dụng Yandex Games SDK, vui lòng liên hệ với bộ phận hỗ trợ:

Viết trong mục trò chuyện

Tên bảng xếp hạng.

ID ứng dụng.

Nếu là true, thì đó là bảng xếp hạng chính.

Thứ tự sắp xếp:

  • false: Điểm số được sắp xếp theo thứ tự giảm dần.
  • true: Điểm số được sắp xếp theo thứ tự tăng dần.

Độ dịch chuyển điểm. Ví dụ: với decimal_offset: 2, số 1234 sẽ được hiển thị là 12,34.

Loại kết quả trên bảng xếp hạng. Các tham số được chấp nhận: numeric (số), time (tính bằng giây).

Tên bản địa hóa. Các tham số mảng có thể: ru, en, be, uk, kk, uz, tr.

Điểm số. Chỉ chấp nhận loại dữ liệu integer. Số nguyên không được phép là số âm. Nếu loại bảng xếp hạng là time, các giá trị phải được truyền vào theo đơn vị mili giây.

Loại kết quả trên bảng xếp hạng. Các tham số được chấp nhận: numeric (số), time (tính bằng giây).

Mô tả người dùng. Tham số tùy chọn.

Trả về URL của ảnh người dùng. Các giá trị size được chấp nhận: small, medium và large.

Trả về srcset ảnh của người dùng phù hợp với màn hình Retina. Các giá trị size được chấp nhận: small, medium và large.

Xác định xem có bao gồm người dùng đã đăng nhập trong phản hồi hay không:

  • true: Bao gồm trong phản hồi.
  • false (giá trị mặc định): Không bao gồm.

Số lượng mục nhập cần trả về bên dưới và bên trên người dùng trong bảng xếp hạng. Giá trị tối thiểu là 1. Giá trị tối đa là 10. Giá trị trả về mặc định là 5.

Số lượng mục nhập từ đầu bảng xếp hạng. Giá trị tối thiểu là 1. Giá trị tối đa là 20. Giá trị trả về mặc định là 5.

Mô tả bảng xếp hạng.

Khoảng xếp hạng trong phản hồi.

Vị trí trong bảng xếp hạng. Đánh số bắt đầu từ số không, vì vậy phần tử thứ 0 là vị trí đầu tiên.

Số lượng mục nhập được yêu cầu. Nếu không có đủ dữ liệu, số được trả về có thể không phải là số được yêu cầu.

Xếp hạng của người dùng. Trả về 0 nếu điểm số của người dùng không có trong bảng xếp hạng hoặc nếu yêu cầu dành cho các xếp hạng hàng đầu trong đó không có người dùng.

Các mục nhập được yêu cầu.

Previous
Mua trong game
Next
Chế độ đa người chơi không đồng bộ