Khái niệm cốt lõi

Dự án, khóa, phiên người chơi và cách mọi SDK trả về kết quả và lỗi.

Chú thích trong mã và tên API được giữ nguyên tiếng Anh để khớp với SDK.

Trên trang này

Dự án và khóa#

Mỗi game là một dự án. Khóa dùng để nhận diện dự án, không nhận diện người chơi.

Thông tin xác thựcDùng ở đâu
Base URLĐịa chỉ của bản cài đặt này. API nằm dưới /v1.
Project IDMọi yêu cầu, dưới dạng X-Project-ID. Công khai.
Khóa client pk_live_…Bản build game và trang web, dưới dạng X-Client-Key. Công khai: chỉ có thể thao tác thay cho người chơi đã đăng nhập.
Khóa bí mật sk_live_…Chỉ trên máy chủ của riêng bạn, dưới dạng X-Secret-Key. Chỉ hiển thị một lần và được lưu dưới dạng hash; mở quyền truy cập các endpoint chỉ dành cho máy chủ.
Tuyệt đối không đưa khóa bí mật (sk_live_…) vào bản build game hay trang web. Mọi thứ gửi đến người chơi đều có thể bị đọc.

Người chơi và phiên#

Các lệnh gọi của người chơi cần access token. Khi đăng nhập, bạn nhận được access token (hiệu lực một giờ) cùng một refresh token (hiệu lực 30 ngày).

  • SDK lưu phiên trên thiết bị và làm mới trước khi hết hạn, nên người chơi vẫn đăng nhập qua các lần mở game.
  • Refresh token được xoay vòng sau mỗi lần dùng. Dùng lại token cũ sẽ đăng xuất phiên đó ở mọi nơi (phát hiện đánh cắp).
  • Mọi người chơi đều bắt đầu là khách và sau đó có thể liên kết tài khoản email hoặc Google; tiến trình của tài khoản khách được chuyển theo. Xem Người chơi.

Kết quả thay vì ngoại lệ#

Lệnh gọi SDK không bao giờ ném ngoại lệ khi gặp lỗi mạng hay lỗi máy chủ. Chúng trả về một kết quả gồm ok, một giá trị và một lỗi có mã ổn định, thông báo và ID yêu cầu.

C#
var top = await Majacloud.Leaderboards.GetTopAsync("coins", 10);
if (top.Ok)
{
    foreach (var entry in top.Value.Entries)
        Debug.Log($"#{entry.Rank} {entry.PlayerName} {entry.Score}");
}
else if (top.Error.IsRetryable)
{
    // Network, timeout, 5xx or rate limit: try again later
    Debug.Log("Retry in " + top.Error.RetryAfterSeconds + " s");
}
else
{
    Debug.LogWarning(top.Error.Code + ": " + top.Error.Message + " (" + top.Error.RequestId + ")");
}

Thử lại và giới hạn tần suất#

SDK tự thử lại các yêu cầu an toàn khi gặp lỗi mạng và phản hồi 5xx theo cơ chế backoff lũy thừa, và chờ hết thời gian Retry-After khi nhận phản hồi 429.

  • Mỗi dự án được gửi tối đa 120 yêu cầu mỗi phút; vượt quá mức đó, API trả về rate_limited.
  • Mỗi tài khoản có hạn mức yêu cầu hằng ngày tùy theo gói (xem Giới hạn); vượt quá hạn mức, API trả về quota_exceeded cho đến 00:00 UTC.
  • Phản hồi có các header X-RateLimit-Limit, X-RateLimit-Remaining và, khi gần hết hạn mức, X-RateLimit-Daily-Remaining.

ID yêu cầu và nhật ký#

Mọi phản hồi đều có header X-Request-ID, và mọi lỗi đều kèm request_id. Tìm giá trị này trên trang Nhật ký của dự án để xem endpoint, trạng thái, độ trễ và người chơi.

Tìm theo tiêu đề trang, đề mục và nội dung.

↑↓ để di chuyển ↵ để mở Esc để đóng