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

시작하기 — 게임 SDK 통합 킷

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

2026-09-17 갱신: 개발자 전달 문서 · 모바일·PC 대응. 자동 파밍은 60초, 기존 SDK 완료 경로는 45초 기준이며 같은 일일 보상을 공유합니다. 호스트 하트비트는 15초입니다. 등록 폼에서 개발자 요청서를 내려받을 수 있습니다.

각 게임 저장소에 직접 넣을 수 있게 쓴 실전 지침입니다. 규격 전문은 SDK 규격서, 동작하는 전체 예제는 레퍼런스 게임 Tower Drift(tokenapps.io/embed/demo-game/index.html — 실제로 카탈로그에 올라가 있습니다)입니다. 이 문서만 따라 해도 통합은 끝납니다.

0. 먼저 알 것 세 가지

  1. 측정은 이미 되고 있습니다. 플레이 시간·재방문율은 플랫폼이 게임 바깥에서 측정합니다. 아래 통합을 하나도 하지 않아도 게임은 지금처럼 동작하고 지표도 쌓입니다. 통합이 여는 것은 TAP(토큰앱스 포인트) 적립 연동, 계정 세이브, 광고 보상입니다.
  2. 게임은 요청만 합니다. 지급·상한·광고 여부는 전부 서버가 판정합니다. 잘못 보내도 부정이 되지 않고, 조작해도 이득이 없습니다.
  3. 게스트가 기본값입니다. 로그인하지 않은 방문자도 게임을 모두 즐길 수 있어야 합니다. 로그인 유도는 플랫폼이 (플레이 후 초대 카드로) 담당합니다 — 게임 안에서 로그인을 강제하면 심사에서 반려됩니다.

1. 필수 통합 — 5분

이 단계만 마치면 TAP 연동이 동작합니다.

게임 HTML <head> 또는 <body> 끝에:

<script src="https://tokenapps.io/sdk/v1.js"></script>
<script>
  TokenApps.ready();   // 게임이 플레이 가능해진 시점에 1번
</script>

그리고 한 판이 자연스럽게 끝나는 지점에 한 줄:

TokenApps.track("session_complete");
게임 "한 판의 끝" 권장 지점
차트런 매매 시뮬레이션 1회차 결과 화면 진입 시
코인푸셔 데일리 세션 종료(코인 소진·결과 집계) 시
배달 고양이 배달 라운드 종료(성공/실패 무관) 시

이게 전부입니다. 주의할 것 하나: 당일 실측 플레이 45초 미만이면 서버가 ignored로 답합니다 (부정 방지 게이트). 로드 직후 쏘면 무시되지만, 지급이 멱등이라 실제 플레이 뒤 다음 판 종료 때 다시 보내지면 그때 정상 지급됩니다 — 게임이 따로 처리할 것은 없습니다.

TokenApps 밖(자체 사이트 직접 접속)에서 열리면 SDK는 조용히 아무 일도 하지 않습니다 — 분기 코드는 필요 없습니다.

2. 권장 — 적립 결과 표시

TokenApps.on("points", function (p) {
  if (p.status === "awarded")         showToast("+" + p.delta + "P 적립!");
  else if (p.status === "duplicate")  {} // 오늘 몫은 이미 받음 — 조용히
  else if (p.status === "signin_required") {} // 게스트 — 플랫폼이 알아서 초대함
});

플랫폼도 자체 토스트를 띄우므로 생략해도 되지만, 게임 안 연출(이펙트·사운드)을 얹으면 체감이 훨씬 좋습니다.

3. 선택 — 계정 세이브

외부 프레임이 자체 출처를 유지해도 브라우저 정책으로 localStorage가 차단될 수 있습니다. 접근을 예외 처리하고 기기 간 저장에는 SDK 세이브를 사용하세요. 게임당·유저당 1슬롯, 64KB입니다.

TokenApps.on("session", function (s) {
  if (TokenApps.canSave()) {
    TokenApps.load().then(function (save) { applySave(save); /* null = 첫 플레이 */ });
  }
});
// 저장할 때:
TokenApps.save({ level: 7, bestScore: 1200 });

차트런이면 연습 이력 요약, 코인푸셔면 누적 기록, 배달 고양이면 스테이지 진행이 후보입니다. 게스트는 canSave() === false — 그냥 건너뛰면 됩니다.

4. 선택 — 보상형 광고

게임이 원하는 지점에서 요청하면, 플랫폼이 선택 화면과 광고를 자기 UI로 띄우고 결과만 알려줍니다. 게임 쪽 광고 SDK·계정은 일절 필요 없습니다.

TokenApps.requestRewardedAd("revive").then(function (r) {
  if (r.status === "rewarded") revivePlayer();  // 포인트는 서버가 이미 지급
  else showNormalGameOver();                     // dismissed/unavailable/failed 전부 이쪽
});
  • 허용 placement: "revive"(이어하기), "bonus_points"(보너스 지점).
  • 철칙: unavailable은 정상 응답입니다. 게스트·빈도 상한·일일 TAP 상한이면 광고가 안 나옵니다. 광고 없이도 진행되는 경로를 반드시 유지해주세요 — "광고 봐야 계속"은 심사 반려 사유입니다. 레퍼런스 구현(Tower Drift)의 이어하기 버튼 처리를 그대로 참고하면 됩니다.

4.5 선택 — 게임 내 재화 판매

아이템·테마를 TAP으로 팔고 싶으면: 내 게임의 "상품 관리"에서 상품(SKU·이름·가격·종류)을 직접 등록합니다. 게임 쪽 코드는 세 줄입니다 — getProducts()로 진열, requestPurchase(sku)로 구매(확인·결제는 플랫폼 시트), getInventory()로 재시작 시 복원. 지급은 purchased/already_owned 응답에만, 복원은 인벤토리로 — 자세한 내용은 SDK 가이드 §4.7을 참고하세요.

5. 통합 확인 체크리스트

TokenApps에서 게임을 열고 (tokenapps.io/ko/app/<slug>/play):

  • 게스트로 한 판 완주 → 게임이 정상 동작하고, 완주 직후 플랫폼 초대 카드가 뜹니다
  • 로그인 후 45초 이상 플레이하고 한 판 완주 → +15 TAP 토스트
  • 같은 날 두 번째 완주 → 지급 없음(duplicate), 게임은 정상
  • (세이브 통합 시) 저장 → 다른 브라우저에서 로그인 → 이어짐
  • (광고 통합 시) 이어하기 → 선택 화면 → 시청 → 부활 + TAP; "괜찮아요" → 일반 게임오버로 자연스럽게
  • 자체 도메인에서 직접 열어도 아무 오류 없음

6. 남은 일 배분

게임 코드 위치 통합 주체 이 저장소에서 할 일
Tower Drift /embed/demo-game/ 완료 (레퍼런스) —
차트런 cgame.tokenpost.kr 차트런 개발팀 이 문서 전달 + 아래 선결 이슈
코인푸셔 pusher.tokenpost.kr 해당 팀 이 문서 전달
배달 고양이 (자체 저장소) 해당 팀 이 문서 전달

차트런 선결 이슈 (2026-08-28 실측): 인트로 모달의 "게스트로 바로 체험하기" 버튼이 iframe 안에서만 동작하지 않습니다. 최상위 탭(cgame.tokenpost.kr 직접 접속)에서는 누르는 즉시 튜토리얼(1/5)로 진입하지만, 프레임 안에서는 아무 반응이 없고 네트워크 요청도 발생하지 않습니다(핸들러가 fetch 이전에 예외로 죽는 것으로 보입니다).

샌드박스 문제가 아님을 A/B로 확인했습니다 — sandbox 속성이 아예 없는 iframe에서도 똑같이 실패했습니다. 번들에 프레임 감지 코드는 없으므로, 서드파티 컨텍스트에서의 스토리지 접근(localStorage/sessionStorage/쿠키)이 예외를 던지는 경우로 추정합니다. 게스트 부트스트랩 경로의 스토리지 접근을 try/catch로 감싸거나 메모리 상태로 대체하면 해결될 가능성이 높습니다. 초기 로딩이 약 20초로 긴 점도 함께 봐주시면 좋겠습니다.

규격 요건: 게임은 파티션된 서드파티 프레임에서 실행됩니다. 스토리지 접근은 반드시 예외를 흡수해야 하며, 스토리지 없이도 최소 플레이 경로가 살아 있어야 합니다.

코인푸셔 렌더 이슈 — 해소됨 (2026-08-28 실측): 2026-08-24에는 프레임 차단 헤더가 없는데도 샌드박스 iframe 안에서 아무것도 그리지 않아 외부 링크 전용으로 내려놓았습니다. 같은 샌드박스 속성으로 다시 확인한 결과 정상 렌더되어(점수판·시세 티커·3D 푸셔 모두 동작) 임베드 플레이를 복원했습니다. 측정과 TAP 적립도 함께 열렸습니다.

질문은 SDK 규격서 기준으로 해주세요. 규격과 이 문서가 다르면 규격서가 맞습니다.