MAJACLOUDWeb SDK
Một file JavaScript không phụ thuộc thư viện cho game HTML5, website và máy chủ Node.js.
Chú thích trong mã và tên API được giữ nguyên tiếng Anh để khớp với SDK.
Yêu cầu#
- Phiên bản hiện hành của Chrome, Edge, Firefox và Safari (desktop và di động), hoặc Node.js 18+.
- Trang phải được phục vụ qua HTTPS (hoặc localhost): API yêu cầu HTTPS, và Web Crypto — dùng để xác minh cấu hình từ xa — chỉ có trên các trang bảo mật.
Cài đặt#
Tải SDK từ máy chủ MAJACLOUD của bạn, nơi phục vụ file kèm header CORS:
<script src="https://majacloud.majanite.com/downloads/majacloud-web-1.0.0.js"></script>
<script type="module">
const mc = Majacloud.createClient({ baseUrl: 'https://majacloud.majanite.com', projectId: '<project id>', clientKey: 'pk_live_…' });
</script>Hoặc sao chép majacloud.js vào dự án:
// Bundlers (Vite, webpack…): copy majacloud.js into your project
import Majacloud from './majacloud.js';
// Node.js 18+
const Majacloud = require('./majacloud.js');Tạo client#
Chỉ baseUrl, projectId và clientKey là bắt buộc.
const mc = Majacloud.createClient({
baseUrl: 'https://majacloud.majanite.com', // your MAJACLOUD address
projectId: '<project id>',
clientKey: 'pk_live_…', // public, safe in the browser
configPublicKey: PEM, // optional: pins Remote Config verification
storage: 'memory', // optional: 'memory' or { get, set, remove }; default localStorage
timeoutMs: 15000, // optional
maxRetries: 2, // optional
});Kết quả#
Mọi lệnh gọi đều resolve thành { ok: true, value } hoặc { ok: false, error } và không bao giờ reject. value là phần thân phản hồi REST không kèm ok, với các trường snake_case giống trong tài liệu tham khảo REST.
error có code, message, status, requestId, retryAfter, details và retryable.
Sự kiện#
Đăng ký bằng on(); hàm này trả về một hàm dùng để hủy đăng ký.
const stop = mc.auth.on('playerChanged', (player) => {
document.querySelector('#name').textContent = player ? player.display_name : '';
});
mc.auth.on('sessionExpired', () => showSignIn());
mc.remoteConfig.on('updated', () => applyBalance());
stop(); // every on() returns an unsubscribe functionBảng xếp hạng trên website của bạn#
Đọc bảng xếp hạng không cần đăng nhập, nên website có thể hiển thị những người chơi hàng đầu chỉ với khóa client công khai:
<ol id="top-players"></ol>
<script src="https://majacloud.majanite.com/downloads/majacloud-web-1.0.0.js"></script>
<script>
const mc = Majacloud.createClient({ baseUrl: 'https://majacloud.majanite.com', projectId: '<project id>', clientKey: 'pk_live_…' });
mc.leaderboards.getTop('coins', { limit: 10 }).then((top) => {
if (!top.ok) return;
document.getElementById('top-players').innerHTML = '';
for (const entry of top.value.entries) {
const li = document.createElement('li');
li.textContent = `${entry.player_name} — ${entry.score}`;
document.getElementById('top-players').append(li);
}
});
</script>Nhiều tab#
Phiên được lưu trong localStorage và dùng chung giữa mọi tab trên trang web của bạn. Refresh token được xoay vòng, nên các tab lần lượt làm mới (Web Locks) và nhận token mới của nhau: người chơi không bao giờ bị đăng xuất khi mở tab thứ hai.
Phía máy chủ với khóa bí mật#
Trên máy chủ Node.js của riêng bạn, hãy tạo client với secretKey thay vì clientKey để dùng server.getPlayer() và server.submitScore(). SDK từ chối khóa bí mật khi chạy trong trình duyệt.
// Node.js on your own server only: the secret key never goes to a browser or game build
const Majacloud = require('./majacloud.js');
const admin = Majacloud.createClient({
baseUrl: 'https://majacloud.majanite.com',
projectId: process.env.MAJACLOUD_PROJECT_ID,
secretKey: process.env.MAJACLOUD_SECRET_KEY,
});
const player = await admin.server.getPlayer('player_3f9c…');
await admin.server.submitScore('coins', 'player_3f9c…', 980);mc.request(method, path, { body, auth }) gọi bất kỳ endpoint nào mà không cần hàm hỗ trợ, ví dụ mc.request('GET', '/wallet', { auth: 'player' }).