Konsep dasar

Project, key, sesi pemain, dan cara setiap SDK melaporkan hasil dan error.

Komentar kode dan nama API tetap dalam bahasa Inggris agar sesuai dengan SDK.

Di halaman ini

Project dan key
Pemain dan sesi
Hasil, bukan exception
Percobaan ulang dan rate limit
Request ID dan log

Project dan key#

Setiap game adalah satu project. Key-nya mengidentifikasi project, bukan pemain.

Kredensial	Tempat dipakai
Base URL	Alamat instalasi ini. API berada di bawah `/v1`.
Project ID	Di setiap request, sebagai `X-Project-ID`. Publik.
Client key `pk_live_…`	Build game dan halaman web, sebagai `X-Client-Key`. Publik: hanya bisa bertindak untuk pemain yang sudah login.
Secret key `sk_live_…`	Hanya di server Anda sendiri, sebagai `X-Secret-Key`. Ditampilkan sekali dan disimpan dalam bentuk hash; membuka akses ke endpoint khusus server.

Jangan pernah memasukkan secret key (sk_live_…) ke build game atau halaman web. Apa pun yang dikirim ke pemain bisa dibaca.

Pemain dan sesi#

Panggilan pemain membutuhkan access token. Login mengembalikan access token (berlaku satu jam) bersama refresh token (berlaku 30 hari).

SDK menyimpan sesi di perangkat dan memperbaruinya sebelum kedaluwarsa, sehingga pemain tetap login setiap kali game dibuka.
Refresh token berganti setiap kali dipakai. Memakai ulang token lama akan mengeluarkan sesi itu dari semua perangkat (deteksi pencurian).
Setiap pemain mulai sebagai tamu dan nanti bisa menautkan akun email atau Google; progres tamu ikut pindah. Lihat Pemain.

Hasil, bukan exception#

Panggilan SDK tidak pernah melempar exception saat terjadi error jaringan atau server. Hasilnya berisi ok, sebuah nilai, dan error dengan kode tetap, pesan, serta request ID.

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 + ")");
}

GDScript

var top := await Majacloud.leaderboards.get_top("coins", 10)
if top.ok:
	for entry in top.value.entries:
		print("#%d %s %d" % [entry.rank, entry.player_name, entry.score])
elif top.is_retryable():
	# Network, timeout, 5xx or rate limit: try again later
	print("Retry in ", top.retry_after, " s")
else:
	push_warning("%s: %s (%s)" % [top.error, top.message, top.request_id])

JavaScript

const top = await mc.leaderboards.getTop('coins', { limit: 10 });
if (top.ok) {
  for (const entry of top.value.entries) {
    console.log(`#${entry.rank} ${entry.player_name} ${entry.score}`);
  }
} else if (top.error.retryable) {
  // Network, timeout, 5xx or rate limit: try again later
  console.log('Retry in', top.error.retryAfter, 's');
} else {
  console.warn(`${top.error.code}: ${top.error.message} (${top.error.requestId})`);
}

JSON

// Success
{ "ok": true, "entries": [ … ], "total": 42 }

// Error (HTTP 4xx/5xx)
{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Project rate limit reached. Try again in a minute.",
    "request_id": "6f1c2a9e-…",
    "details": { "limit": 120, "window": "minute" }
  }
}

Percobaan ulang dan rate limit#

SDK mengulang request yang aman saat terjadi error jaringan dan respons 5xx dengan exponential backoff, dan menunggu respons 429 sesuai Retry-After.

Setiap project bisa mengirim hingga 120 request per menit; lebih dari itu API menjawab rate_limited.
Setiap akun punya kuota request harian sesuai paketnya (lihat Batas); jika terlampaui, API menjawab quota_exceeded sampai pukul 00:00 UTC.
Respons menyertakan X-RateLimit-Limit, X-RateLimit-Remaining, dan, saat mendekati kuota, X-RateLimit-Daily-Remaining.

Request ID dan log#

Setiap respons punya header X-Request-ID, dan setiap error menyertakan request_id. Cari ID itu di halaman Log project Anda untuk melihat endpoint, status, latensi, dan pemainnya.