#릴리스 노트

#게임 전용 임베드 납품 기준 — 2026-09-18

• SDK 런타임 v1.4.0 유지. 신규 API·메시지 규약 없음.
• 한·영 게임 전용 경로 가이드, 크기·입력 예제, framing 헤더, 진단 방법과 바이브 코딩 요청문 추가.
• /sdk/examples/embed.html 실행 예제 제공. 점수·보상 이벤트를 전송하지 않음.
• 제출 폼·개발자 요청서에서 SDK 연동과 임베드 화면 준비를 별도 작업으로 안내.
• 호스트 플레이어 폭 확대, 조작 영역 간소화와 라운딩 축소. 외부 게임의 반응형 화면은 해당 게임에서 구현해야 함.

#플레이어·개발자 포털 — 2026-09-17

• SDK 런타임 v1.4.0 유지. 신규 메시지 규약 없음.
• 실측 60초 자동 파밍, 기존 45초 SDK 완료 경로와 일일 보상 공유. 호스트 하트비트 15초.
• 한·영 개발자 전달 문서, 모바일·PC 가이드, 그룹형 등록 폼과 요청서 다운로드.
• 소유자가 비공개 기기·SDK·검수 정보를 관리하고 운영자가 확인. 기기별 URL은 검수 참고용이며 플레이어 자동 분기는 아님.

SDK와 플랫폼의 변경 이력입니다. v1.x 안의 모든 추가는 하위호환입니다 — 기존 필드는 삭제·변경되지 않고, 게임은 모르는 메시지와 필드를 무시하면 됩니다. 오늘 통합한 코드는 앞으로의 v1 업데이트에서 수정 없이 계속 동작합니다.

분기가 필요할 때는 버전 비교보다 기능 감지를 권장합니다:

if (typeof TokenApps.requestPurchase === "function") { /* v1.3+ */ }

#SDK v1.4 — 대전 (실시간·비동기 매칭) (2026-09-10)

게임에 TokenApps.match 하나로 대전을 붙일 수 있습니다.

• TokenApps.match.find(opts) — 상대를 찾아 Match 객체를 돌려줍니다. 기본값 kind: "auto"는 지금 같은 게임을 하는 플레이어와의 실시간 대전을 먼저 찾고, 45초 안에 상대가 없으면 같은 게임에서 레이팅이 가장 가까운 플레이어의 최고 기록과 겨루는 비동기 대전으로 바꿉니다. 매치는 ready 이벤트에서 시작하며, 양쪽은 seed로 같은 판을 만듭니다.
• match.send(data)와 message 이벤트 — 실시간 대전에서 게임 메시지를 상대에게 전달합니다. 초당 8건, 4KB까지이며 넘는 것은 ratelimited 이벤트와 함께 버려집니다.
• match.report({ score, outcome? }) — 결과를 보고합니다. 판정과 레이팅 반영은 서버가 합니다. 실시간 대전은 두 보고가 서로 맞을 때만 확정되고, 엇갈리면 disputed로 닫힙니다.
• match.leave() — 대기 취소 또는 이탈입니다. 진행 중인 실시간 대전에서 나가면 패배로 기록됩니다. 상대가 나가면 opponent_left 이벤트가 옵니다.
• 대전 결과는 TAP과 무관합니다. 적립은 세션 완주 규칙 그대로이고, 결과는 게임별 레이팅과 기록에만 남습니다.
• ready() 재전송 — 첫 session이 올 때까지 SDK가 ready를 다시 보냅니다. 게임이 플레이 페이지보다 먼저 준비되면 한 번뿐인 ready가 사라져, 로그인한 플레이어가 게스트처럼 보이던 문제가 있었습니다. 게임 쪽에서 바꿀 것은 없습니다.

사용법: SDK 가이드 §4.8 · 규격: 규격서 §6.10-6.14

#SDK v1.3 — 게임 내 재화 (2026-08-25)

아이템·테마·부스트를 TAP으로 판매할 수 있게 되었습니다.

• TokenApps.getProducts() — 플랫폼에 등록된 이 게임의 상품 목록을 받습니다. 게스트도 조회할 수 있으므로 상점 진열은 로그인과 무관하게 그릴 수 있습니다.
• TokenApps.requestPurchase(sku) — 구매를 요청합니다. 가격 표시·플레이어 확인·결제·기록은 전부 플랫폼이 처리하고 게임은 결과만 받습니다. 프로토콜의 어떤 메시지에도 금액 필드가 없습니다 — 청구되는 가격은 서버에 등록된 값이 유일합니다.
• TokenApps.getInventory() — 이 플레이어가 이 게임에서 보유한 재화 목록입니다. 재시작 시 복원은 로컬 저장이 아니라 이 응답을 기준으로 해주세요.
• 지급 철칙: purchased 또는 already_owned 응답에만 재화를 지급합니다.
• 게임 서버가 있다면 세션 토큰으로 인벤토리를 조회해 서버측 검증(영수증 검증 상당)을 할 수 있습니다 — 규격서 §6.9.

사용법: SDK 가이드 §4.7 · 규격: 규격서 §6.6-6.9

#SDK v1.2 — 이어하기 시트 (2026-08-24)

• TokenApps.requestContinue() — 게임오버에서 한 번 호출하면 플랫폼이 "TAP으로 이어하기 / 광고 보고 이어하기 / 그만하기" 3택 시트를 띄웁니다. 게임은 paid/rewarded면 부활시키고, 그 외에는 평소의 게임오버 흐름으로 진행하면 됩니다.
• 이어하기 용도라면 광고를 직접 다루는 것보다 이 시트를 권장합니다 — 플레이어의 선택지가 넓고 게임 코드는 더 짧습니다.

#SDK v1.1 — 보상형 광고 (2026-08-24)

• TokenApps.requestRewardedAd(placement) — 보상형 광고를 요청합니다. 플레이어가 플랫폼 시트에서 명시적으로 선택하고, 보상은 서버가 지급합니다. 게임 쪽 광고 SDK·광고 계정이 전혀 필요 없습니다.
• unavailable은 정상 응답입니다. 게스트, 시청 간격·일일 상한, 플레이어의 일일 TAP(토큰앱스 포인트) 상한 도달이 전부 이 응답으로 옵니다. 광고 없이 진행되는 경로를 항상 유지해주세요 — 심사 요건이기도 합니다.

#SDK v1.0 — 최초 공개 (2026-08-18)

• ready() / session — 핸드셰이크. 로그인 상태, 게임 전용 가명 플레이어 id, 세이브용 토큰을 받습니다.
• track(event) / points — 게임플레이 이벤트 보고와 서버 판정. 지급 여부· 단가·상한은 전부 서버가 결정합니다.
• save() / load() — 계정 세이브 슬롯. 기기를 넘나들며, iframe에서는 localStorage가 동작하지 않으므로 이것이 표준 저장소입니다.
• submitScore(n) — 표시용 점수 제출. TAP과 절대 연결되지 않습니다.
• openPointsPurchase() — 플랫폼 충전 시트 열기 요청.

#플랫폼 변경 (게임에 영향 있는 것)