본문 바로가기
tokenAppsPLAY & COLLECT
tokenAppsPLAY & COLLECT

tokenApps 게임 SDK — 개발자 전달 문서 v1.4

갱신일: 2026-09-18. 런타임: https://tokenapps.io/sdk/v1.js (1.4.0). 실제 구현을 기준으로 정리한 문서입니다. 전체 메시지 계약은 SDK 규격서를 확인하세요.

개발자에게 받을 것

  1. 랜딩 페이지·메뉴·FAQ 없이 게임이 바로 실행되는 공개 HTTPS 플레이 전용 URL.
  2. 모바일·PC·태블릿 지원 범위, 터치·키보드·마우스 조작, 화면 방향, 게임 지원 언어.
  3. 반응형 공통 빌드 또는 모바일·PC 검수 URL. 분리 빌드는 기본 URL에서 알맞은 빌드로 연결해야 합니다. 현재 호스트는 하나의 play_url을 사용하며 기기별 제출 URL을 자동 선택하지 않습니다.
  4. SDK 연동 상태, 테스트 기기·브라우저 버전, 알려진 문제, 빌드 버전, 담당자 이메일.
  5. 아이콘·커버·스크린샷 최대 3장.

등록 폼에서 작성한 내용을 Markdown 요청서로 다운로드할 수 있습니다. 기존 게임은 내 게임에서 같은 정보를 추가·수정합니다. 연락처·검수 메모는 제출자와 운영자만 보며 공개 리스팅에 포함되지 않습니다. 체크하지 않은 테스트는 미검증 상태입니다.

화면별 작업 기준은 모바일·PC 대응 가이드에 있습니다.

SDK와 함께 필요한 게임 전용 화면

SDK 연동만으로 홈페이지가 임베드 게임으로 바뀌지는 않습니다. SDK는 사용자·점수·저장을 연결하고, 라우팅·레이아웃·캔버스 크기·입력 좌표는 게임 개발자가 구현합니다.

  1. 기존 게임을 재사용하는 /embed 등 전용 경로를 배포합니다. 홈페이지 메뉴·히어로·FAQ·푸터를 제외하고 보드·HUD·일시정지·사운드·재시작·터치 조작을 유지합니다.
  2. 실제 iframe의 가로와 세로에 맞춥니다. HUD/버튼 공간을 먼저 확보하고 남은 보드 영역을 관찰해 contain 배율, 렌더링 해상도, 입력 좌표를 갱신합니다. resize 때 라운드는 유지합니다.
  3. SDK 리스너는 지속되게 등록하고 ready()보다 먼저 연결합니다. SDK/네트워크 성공 여부와 별개로 게스트 플레이를 시작합니다. 중첩 iframe이나 별도 로그인 흐름을 추가하지 않습니다.
  4. iframe 내부 CSS px 기준 310x360, 380x640, 558x160, 834x220, 1340x560, 1894x875에서도 확인합니다. 불필요한 스크롤뿐 아니라 잘린 조작 버튼도 없어야 합니다. overflow로 실패를 숨기지 말고 미지원 환경을 보고합니다.
  5. 구현·배포 후 정확한 게임 전용 URL을 등록합니다. /embed는 자동 생성되지 않으며 모바일/PC 검수 URL도 기본 플레이 URL을 자동 변경하지 않습니다.

Next.js/Vite 구성, HTML/CSS, 캔버스 배율, CSP, 진단 방법과 바이브 코딩 요청문은 임베드 구현 상세 가이드를 확인하세요. 실행 가능한 HTML 예제는 점수·보상 이벤트를 전송하지 않습니다.

최소 연동

게스트이거나 플랫폼 연결이 안 되어도 게임은 시작되어야 합니다. 세션 이벤트를 무기한 기다리지 마세요. 아래 게임 함수는 각 게임에서 구현하는 예시입니다.

<script>
  startGameAsGuest(); // 게임은 한 번만 시작
  function connectPlatform() {
    if (!window.TokenApps) return;
    TokenApps.on("session", function (session) {
      // 로그인·토큰 갱신 시 반복됩니다. 진행 중인 게임을 재시작하지 마세요.
      setPlayerIdentity(session.player || null);
      setGameLocale(session.locale || "en");
    });
    TokenApps.ready();
  }

  function onGameOver(score) {
    if (!window.TokenApps) return;
    TokenApps.submitScore(score);
    TokenApps.track("session_complete");
  }
</script>
<script async src="https://tokenapps.io/sdk/v1.js" onload="connectPlatform()"></script>

리스너를 먼저 등록하고 ready()를 호출합니다. SDK는 첫 세션을 받을 때까지 핸드셰이크를 재시도합니다. session.player.id는 게임별 가명 ID입니다. 프레임 안에 별도 OAuth 로그인을 구현하지 마세요. 플랫폼 로그인은 현재 Google·Privy를 제공하며 신규 TokenPost 로그인·연결은 비활성 상태입니다. 기존 player.verified는 호환 필드이며 플레이 자격 조건이 아닙니다.

자동 파밍과 SDK 이벤트

경로 현재 규칙
플레이어 자동 파밍 호스트 실측 60초 이상. 게임에서 SDK 이벤트를 보내지 않아도 동작
track("session_complete") 기존 연동 경로. 해당 UTC 날짜의 호스트 실측 플레이 45초 이상
지급 계정·게임별 UTC 하루 1회 15 TAP. 공통 일일 적립 상한 현재 150 TAP 적용
중복 방지 자동 파밍과 SDK 경로가 같은 일일 지급 키를 공유. 이중 지급 불가
점수·승패 순위 표시용. TAP 지급량에 영향 없음

호스트는 화면이 보일 때 15초 간격으로 하트비트를 보냅니다. 게임은 시간이나 지급량을 보내지 않습니다. 서버가 지급 여부와 상한을 판정합니다. 이미 보상을 받은 세션일 수 있으므로 ignored, duplicate, capped, signin_required에도 플레이를 유지하세요.

TokenApps.on("points", function (result) {
  // SDK 이벤트 응답입니다. 자동 파밍 표시는 호스트가 처리합니다.
  if (result.status === "awarded") showPoints(result.delta);
});

저장과 복원

외부 HTTPS 프레임은 allow-same-origin으로 자체 출처를 유지하며, 플랫폼의 상대경로 프레임은 그렇지 않습니다. 브라우저 개인정보 설정에 따라 쿠키·localStorage·IndexedDB가 차단될 수 있으므로 접근을 예외 처리하고 메모리 대체 경로를 두세요.

TokenApps.canSave()로 가능 여부를 확인합니다. 로그인 사용자는 load()·save(json)으로 게임당 하나의 기기 간 저장 슬롯을 사용합니다. 직렬화 기준 최대 64KB이며 guest, expired를 처리해야 합니다. 토큰 갱신으로 세션 이벤트가 반복되어도 진행 중인 게임에 오래된 저장 데이터를 덮어쓰지 마세요.

선택 기능

기능 호출 / 처리
리더보드 submitScore(number) → score_ack
보상형 광고 requestRewardedAd("revive") → rewarded일 때만 지급
이어하기 requestContinue() → paid 또는 rewarded일 때 진행
게임 내 구매 getProducts(), requestPurchase(sku), getInventory()
매칭 (v1.4) match.find() → 매치 ready 후 send() / report() / leave()

광고·구매·대전은 사용 불가 응답이 정상일 수 있습니다. 혼자 하기·다시 하기 경로를 유지하세요. 상품 가격은 플랫폼이 정하며 purchased·already_owned일 때만 해금하고 인벤토리로 복원합니다. 대전은 레이팅만 바꾸며 TAP을 지급하지 않습니다.

선택 API는 함수 존재 여부로 확인하세요. TokenApps.on()은 콜백을 등록하며 v1.4에는 off()가 없습니다. 유지되는 연동 모듈에서 한 번 등록하고 React 화면 재마운트마다 리스너를 누적하지 마세요.

임베드·출시 확인

  • 플레이 문서의 HTTP CSP frame-ancestors에서 https://tokenapps.io를 허용합니다. 충돌하는 X-Frame-Options: DENY/SAMEORIGIN을 제거합니다.
  • 모니터가 아닌 iframe 내부 크기를 기준으로 배치하고 리사이즈 시 게임 진행을 유지합니다.
  • 모바일의 모든 행동을 터치로 수행할 수 있어야 합니다. 전체화면·방향 잠금 실패 시에도 플레이를 유지합니다.
  • 게스트 시작, 저장소 차단, 오디오 활성화, 백그라운드 복귀, 재시작, 선택 SDK 기능 사용 불가를 테스트합니다.
  • 단독 탭뿐 아니라 tokenApps 플레이어 내부에서 실제 지원 브라우저로 검수합니다.
  • 자동 헤더 검사는 임베드 허용 여부의 참고 자료이며 화면·조작·SDK까지 통과했다는 뜻은 아닙니다.

기기별 체크리스트 · 기능별 가이드 · 규격서 · 게임 등록