#모바일·PC 대응 및 개발자 요청서

2026-09-18 추가: SDK 설치와 게임 전용 임베드는 별도 납품 항목입니다. 게임 전용 임베드 가이드에 따라 구현·배포한 주소를 등록하세요. SDK를 넣은 홈페이지도 플레이어 안에서는 스크롤이 생길 수 있습니다.

갱신일: 2026-09-17. SDK v1.4와 현재 tokenApps 플레이어 기준입니다.

#개발자에게 요청할 납품 항목

등록 폼의 개발자 요청서 다운로드는 로그인 전에도 사용할 수 있습니다. 작성한 내용과 체크리스트가 Markdown 파일로 저장되며 개발자에게 직접 전달하면 됩니다. 다운로드는 메시지를 발송하지 않습니다. 기존 게임은 내 게임의 모바일·PC 대응에서 업데이트하고, 운영자는 앱 상세 검수 화면에서 비공개 요청서를 확인합니다.

#기본 진입점과 기기별 빌드

가능하면 반응형 단일 플레이 URL을 제공하세요. 모바일·PC 빌드가 별도라면 검수 주소를 각각 제출하되, 기본 URL에서 기기에 맞게 연결해야 합니다. 제출한 기기별 URL이 플랫폼 플레이어에 자동 연결되지는 않습니다.

User-Agent만으로 화면을 나누지 마세요. 좁은 PC 창, 키보드를 연결한 태블릿, 회전 중인 모바일에서도 사용 가능한 프레임 크기와 입력 장치를 기준으로 대응해야 합니다. 빌드 간 저장 형식을 호환하거나 차이를 명시하세요.

현재 호스트의 화면 방향 설정은 앱당 하나입니다. 모바일 세로·PC 가로 조합이라면 기본 빌드가 선택된 컨테이너 안에서 대응해야 합니다. 기기별 방향 요구사항은 메모에 적어주세요. 실제 플레이어에 기기별 방향 설정은 아직 없습니다.

#프레임 크기에 맞추고 스크롤 제거하기

tokenApps 자체 조작 영역 때문에 iframe은 브라우저 전체보다 작습니다. screen.width나 고정 데스크톱 높이가 아니라 게임 컨테이너의 실제 크기를 사용하세요.

다음 예시는 플레이 전용 문서의 시작점입니다. FAQ·로그인·소개 페이지가 섞인 사이트 전체에 적용하지 마세요.

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<style>
  html, body { width: 100%; height: 100%; margin: 0; }
  body { overflow: hidden; overscroll-behavior: none; }
  #game-root {
    position: fixed; inset: 0; min-width: 0; min-height: 0;
    box-sizing: border-box;
    padding: env(safe-area-inset-top) env(safe-area-inset-right)
             env(safe-area-inset-bottom) env(safe-area-inset-left);
  }
  canvas { display: block; width: 100%; height: 100%; }
  .game-input { touch-action: none; }
  button { min-width: 44px; min-height: 44px; }
</style>
<div id="game-root"><canvas class="game-input"></canvas></div>

ResizeObserver로 #game-root 크기를 감지하고 엔진의 resize 메서드를 호출하세요. 캔버스 CSS 크기와 devicePixelRatio를 반영한 내부 렌더링 해상도를 구분하고, 카메라·입력 좌표를 함께 갱신합니다. 저사양 기기에서는 렌더링 해상도를 제한하세요. 캔버스 width/height 변경은 컨텍스트를 초기화하므로 게임 상태를 재생성하지 말고 다시 그려야 합니다.

고정 비율 보드는 전체가 보이는 contain 스케일을 계산하세요. 레터박스는 가능하지만 HUD·일시정지·점수·재시작·터치 버튼은 화면 안에 있어야 합니다. 큰 캔버스를 단순히 overflow:hidden으로 잘라 숨기는 것은 대응이 아닙니다. 메뉴 내부의 의도된 스크롤은 가능하나 플레이 화면에 두 번째 페이지 스크롤이 생기지 않아야 합니다.

#입력·오디오·화면 전환

• 마우스·터치는 pointer event로 대응하고 모든 모바일 행동에 터치 경로를 제공합니다.
• touch-action:none과 제스처 방지는 게임 영역에만 적용하세요. 전역 확대나 입력 폼의 기본 동작을 막지 마세요.
• 터치 버튼은 44×44 CSS px 이상, 인접 버튼과 충분한 간격을 둡니다.
• 탭·클릭 후 오디오를 활성화하고 재생 실패·AudioContext 정지에도 게임을 유지합니다.
• visibilitychange의 백그라운드 전환·복귀를 처리합니다. 게임에서 숨겨진 시간을 적립 시간으로 계산하지 마세요.
• 회전·주소창 변화·리사이즈·전체화면 거부를 테스트합니다. 전체화면은 선택 기능이며 일반 iframe에서도 플레이되어야 합니다.
• localStorage·쿠키·IndexedDB 차단에 대비합니다. 외부 프레임이 자체 출처를 유지해도 브라우저 정책이 저장소를 막을 수 있습니다.
• SDK 세션 이벤트는 로그인·토큰 갱신 때 반복됩니다. 이벤트마다 진행 중인 게임을 다시 시작하지 마세요.

#기기별 검수 표

아래는 검수 목표이며 호스트가 항상 이 크기를 제공한다는 보장은 아닙니다. 실제 iframe 크기와 더 낮은 높이에서도 확인하세요.

지원한다고 표시한 기기마다 시작 → 플레이 → 일시정지·복귀 → 종료 → 재시작을 확인하세요. 게스트, 저장소 차단, SDK 연결 실패, 플레이 중 로그인, 새로고침 후 세이브, 선택 기능 거절·사용 불가도 검수합니다. 결과에 기기·OS·브라우저·빌드 버전과 날짜를 기록하세요. 에뮬레이션은 레이아웃 확인용이며 실제 기기의 오디오·전체화면 지원까지 증명하지 않습니다.

#파밍·이미지·출시

호스트는 플레이를 측정해 60초 기준 자동 파밍을 처리합니다. 기존 SDK 완료 이벤트는 45초 기준이며 같은 일일 보상을 공유합니다. 게임에 별도 TAP 지갑을 만들거나 클라이언트 타이머로 지급을 확정하지 마세요. SDK 전달 문서를 참고하세요.

PNG/JPEG/WebP만 지원하며 개별 2MB, 전체 제출 이미지 합계 2.5MB 이하입니다. 아이콘 512×512, 커버 1600×900(16:9)를 권장합니다. 지원하는 모바일·PC의 실제 플레이 스크린샷을 포함하고 이미지에 작은 글자를 넣지 마세요.

SDK 미완료 항목도 사실대로 제출할 수 있으며 제출과 공개 승인은 별개입니다. HTTP 임베드 검사 통과가 게임의 화면·입력 검수 통과를 의미하지는 않습니다.

#바로 전달할 요청 문안

아래 항목을 준비해주세요.
- 게임만 바로 실행되는 기본 HTTPS 플레이 URL
- 모바일 / PC / 태블릿 지원 범위와 미지원 조건
- 반응형 공통 빌드 또는 기기별 주소와 기본 URL의 라우팅 처리
- 기본 화면 방향, 터치 및 키보드·마우스 조작
- SDK 1.4 연동 상태와 기능별 현황
- 게스트, 저장소 차단, 스크롤·버튼 잘림, 회전·리사이즈, 오디오 검수
- 기기·OS·브라우저·빌드 버전, 알려진 문제와 수정 일정
- 영어 게임명·소개, 지원 언어, 아이콘·커버·플레이 스크린샷
- 담당 개발자 이메일
SDK 문서: https://tokenapps.io/ko/dev/sdk
기기 체크리스트: https://tokenapps.io/ko/dev/devices
등록 및 요청서 다운로드: https://tokenapps.io/ko/submit