MAJACLOUD문제 해결
자주 발생하는 문제와 해결 방법을 정리했습니다.
코드 주석과 API 이름은 SDK와 일치하도록 영어로 유지합니다.
연결#
not_configured / NotConfigured
Unity: Tools ▸ Majacloud ▸ Setup을 열고 저장하세요. 에셋이 Assets/Resources/MajacloudSettings.asset에 있어야 합니다. Godot: Project Settings ▸ Majacloud에 값을 입력하세요. 웹: baseUrl, projectId, clientKey를 전달하세요.
https_required (HTTP 426)
http://는 localhost에서만 사용할 수 있습니다. HTTPS를 사용하거나, 개발용으로만 config.local.php에 ALLOW_INSECURE_HTTP를 설정하세요.
브라우저나 WebGL에서 모든 요청이 실패합니다
게임도 HTTPS로 제공하세요. 브라우저는 https:// 페이지에서 보내는 http:// 호출을 차단합니다. API는 CORS 헤더를 이미 보냅니다.
실패한 요청 찾기
모든 오류에는 요청 ID가 있습니다. 프로젝트의 로그 페이지에서 검색하세요.
로그인#
모든 호출에서 unauthorized 발생
API 키 페이지에서 프로젝트 ID와 클라이언트 키를 확인하세요. 클라이언트 키를 교체했다면 이전 빌드는 작동하지 않습니다.
플레이어가 예기치 않게 로그아웃됩니다
30일 동안 사용하지 않은 세션은 만료됩니다. 게임 인스턴스 두 개가 하나의 세션을 공유하며 둘 다 갱신하면, 재사용 보호 기능이 세션을 로그아웃시킵니다. 세션은 SDK 인스턴스 하나만 관리하도록 하세요.
계정 연결 페이지가 열리지 않습니다
브라우저는 클릭으로 열지 않은 탭을 차단합니다. 버튼 핸들러에서 계정 연결을 시작하세요.
원격 구성#
signature_invalid / SignatureInvalid
저장된 공개 키가 서버와 일치하지 않습니다. 보통 새 서버로 옮겼거나 storage/keys/를 잃어버린 경우입니다. Test connection을 다시 실행하고(또는 configPublicKey를 업데이트하고) 업데이트를 배포하세요.
구성 변경 사항이 반영되지 않습니다
SDK는 시작 시 구성을 가져옵니다. 세션 중에 변경 사항을 반영하려면 가져오기를 다시 호출하세요(예: 메뉴로 돌아갈 때).
한도#
plan_limit
플랜 한도에 도달했습니다. 데이터는 삭제되지 않습니다. 업그레이드하거나 대시보드에서 사용하지 않는 항목을 삭제하세요.
rate_limited / quota_exceeded
Retry-After초만큼 기다리세요. Update()나 게임 루프 안에서 가져오기를 반복하지 말고 결과를 캐시하세요.
Godot 및 웹#
Godot: Identifier "Majacloud" not declared
Project Settings ▸ Plugins에서 플러그인을 활성화하세요. 플러그인이 오토로드를 추가합니다. 폴더가 정확히 res://addons/majacloud인지 확인하세요.
Godot: TLS handshake failed
서버의 HTTPS 인증서를 신뢰할 수 없습니다(대개 자체 서명 인증서). Let's Encrypt 같은 공인 인증 기관의 인증서를 사용하세요.
웹: "Web Crypto is unavailable"
페이지가 다른 호스트에서 일반 HTTP로 제공되고 있습니다. HTTPS로 제공하세요(개발 중에는 localhost도 괜찮습니다).