MAJACLOUDWeb SDK
HTML5 게임, 웹사이트, Node.js 서버를 위한 의존성 없는 단일 JavaScript 파일입니다.
코드 주석과 API 이름은 SDK와 일치하도록 영어로 유지합니다.
요구 사항#
- 최신 버전의 Chrome, Edge, Firefox, Safari(데스크톱 및 모바일) 또는 Node.js 18 이상.
- 페이지는 HTTPS(또는 localhost)로 제공해야 합니다. API가 HTTPS를 요구하며, 원격 구성 검증에 쓰이는 Web Crypto는 보안 페이지에서만 사용할 수 있습니다.
설치#
CORS 헤더와 함께 파일을 제공하는 MAJACLOUD 서버에서 불러옵니다:
<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>또는 majacloud.js를 프로젝트에 복사합니다:
// Bundlers (Vite, webpack…): copy majacloud.js into your project
import Majacloud from './majacloud.js';
// Node.js 18+
const Majacloud = require('./majacloud.js');클라이언트 만들기#
baseUrl, projectId, clientKey만 필수입니다.
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
});결과#
모든 호출은 { ok: true, value } 또는 { ok: false, error }로 resolve되며 reject되지 않습니다. value는 ok를 제외한 REST 응답 본문이며, REST 레퍼런스와 같은 snake_case 필드를 사용합니다.
error에는 code, message, status, requestId, retryAfter, details, retryable이 있습니다.
이벤트#
on()으로 구독합니다. 반환된 함수를 호출하면 구독이 해제됩니다.
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 function웹사이트에 리더보드 표시하기#
리더보드 조회에는 로그인이 필요 없으므로, 웹사이트에서 공개 클라이언트 키만으로 상위 플레이어를 표시할 수 있습니다:
<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>여러 탭#
세션은 localStorage에 보관되며 사이트의 모든 탭이 공유합니다. 리프레시 토큰은 교체되므로 탭들이 차례로 갱신하고(Web Locks) 서로의 새 토큰을 가져갑니다. 따라서 두 번째 탭을 열어도 플레이어가 로그아웃되지 않습니다.
시크릿 키를 사용하는 서버 측 코드#
자체 Node.js 서버에서는 clientKey 대신 secretKey로 클라이언트를 만들어 server.getPlayer()와 server.submitScore()를 사용합니다. SDK는 브라우저에서 시크릿 키 사용을 거부합니다.
// 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 })로 헬퍼가 없는 엔드포인트도 호출할 수 있습니다. 예: mc.request('GET', '/wallet', { auth: 'player' }).