알립니다

PlayNANOO REST API 사용 시 반드시 알아야 할 중요 사항들을 안내합니다.

예제 코드 안내

본 문서에 포함된 예제 코드는 PlayNANOO API 연동의 이해를 돕기 위한 참고용입니다. 실제 프로젝트에 적용하실 때는 프로젝트의 아키텍처와 코딩 컨벤션에 맞게 자유롭게 수정하여 사용하시기 바랍니다.

필수 요청 헤더

모든 API 호출 시 다음 헤더를 반드시 포함해야 합니다.

헤더	설명	필수
X-Playnanoo-Key	콘솔에서 발급받은 Service Key	O
X-Playnanoo-Id	콘솔에서 발급받은 Game ID	O
Authorization	Bearer {access_token} 형식 (인증 필요 API)	△
Content-Type	application/json	O

인증 정보 발급

콘솔 > 채널 > 설정 > API & 플랫폼 관리에서 Game ID, Service Key, Secret Key를 발급받으세요.

공통 요청 파라미터

대부분의 API에서 아래 기기 정보가 필수로 요구됩니다. 매 요청마다 직접 입력하지 않아도 되도록, 기본 환경설정에서 제공하는 DeviceInfo 클래스를 상속하여 사용하시면 편리합니다.

파라미터	타입	설명
uuid	string	플레이어 고유 ID (로그인 후 발급)
nickname	string	플레이어 닉네임
device_id	string	기기 고유 ID
version	string	앱 버전
platform	string	플랫폼 (aos, ios)
device_model	string	기기 모델명
device_os	string	기기 OS 버전
device_language	string	기기 언어 (KO, EN 등)
device_country	string	국가 코드 (KR, US 등)
device_timeoffset	string	UTC 시간 오프셋 (초 단위)

인증 토큰 관리

Access Token

• 로그인 성공 시 발급
• API 요청 시 Authorization 헤더에 포함
• 만료 시 Refresh Token으로 갱신

Refresh Token

• Access Token 갱신용
• Access Token보다 긴 유효기간
• 만료 시 재로그인 필요

토큰 갱신 흐름

1. API 호출 → 401 Unauthorized 응답
2. Refresh Token으로 /token/refresh 호출
3. 새 Access Token 발급
4. 원래 API 재호출

에러 응답 형식

API 호출 실패 시 다음 형식으로 응답합니다.

{
  "ErrorCode": "에러 코드",
  "Message": "에러 메시지"
}

주요 HTTP 상태 코드:

• 400 - 잘못된 요청 (파라미터 오류)
• 401 - 인증 실패 (토큰 만료/무효)
• 403 - 권한 없음
• 404 - 리소스 없음
• 500 - 서버 오류

주의사항

Secret Key 보안

Secret Key는 절대 클라이언트 코드에 하드코딩하지 마세요. 서버 사이드에서만 사용하거나, 환경변수로 관리하세요.

Rate Limit

과도한 API 호출 시 일시적으로 차단될 수 있습니다. 적절한 호출 간격을 유지하세요.

다음 단계

• Unity 기본 환경설정 - Unity 프로젝트 설정 방법
• Unreal 기본 환경설정 - Unreal 프로젝트 설정 방법