---
url: https://developers.webzenk.kr/guide.md
---
# 개요
웹젠케이 Game API는 게임에 필요한 서버 기능을 **별도 게임 서버 없이** 쓸 수 있게 해 주는 REST API예요.
로그인·데이터 저장·랭킹·지표 수집과 함께, 결제 영수증과 보상형 광고를 **스토어·광고사 서버에서 직접 검증**해 위조와 중복 지급을 막아요.
## 무엇을 할 수 있나요
| 기능 | 설명 |
|---|---|
| [로그인·계정](./login) | 게스트, Google, Play Games, Apple, 삼성 계정. 계정을 연결하면 기기를 바꿔도 진행이 이어져요 |
| [데이터 저장](./storage) | 유저별 키-값(JSON) 저장. 여러 기기의 동시 저장 충돌을 알려 줘요 |
| [랭킹](./ranking) | 일간·주간·월간 시즌, 최고·최신·누적 점수, 지난 시즌 결과 보관 |
| [지표·이벤트](./metrics) | DAU·신규·매출·리텐션 자동 집계와 커스텀 이벤트 |
| [결제 검증](./iap) | Google Play·App Store·삼성 Instant Plays 영수증 서버 검증, 환불 반영 |
| [보상형 광고](./ads) | AppLovin MAX 서버 콜백으로 광고 시청을 확인한 뒤 보상 |
## 연동 흐름
1. **[게임 등록](./registration)** — 운영 담당자에게 요청해 App Key·App Secret·Server Secret을 받아요.
2. **[SDK 선택·설치](./choose-sdk)** — Unity, HTML5 SDK 중 고르거나 REST API를 직접 호출해요.
3. **기능 연동** — 로그인부터 시작해서 필요한 기능을 붙여요.
4. **[테스트](./testing)** — 테스트 계정으로 결제·광고 보상까지 확인해요.
5. **[출시](./launch-checklist)** — 체크리스트를 확인하고 공개해요.
## 기본 정보
| 항목 | 값 |
|---|---|
| API 주소 | `https://game-api.webzenk.kr` |
| 프로토콜 | HTTPS, JSON (UTF-8) |
| 날짜 기준 | 게임 시간대 (기본 한국 시간) — 일일 한도·일간/주간/월간 랭킹·지표 |
| SDK | Unity `com.webzenk.wk-gameapi` · HTML5 `@webzenk/wk-gameapi` |
::: tip AI 도구로 연동하나요?
이 사이트의 모든 문서는 Markdown으로도 제공돼요. Claude Code·Codex 같은 도구에 [`/llms.txt`](/llms.txt)(목차)나 [`/llms-full.txt`](/llms-full.txt)(전체)를 넣어 주면 문서를 그대로 참고해요. 각 페이지 상단의 **페이지 복사** 버튼도 쓸 수 있어요.
:::
---
---
url: https://developers.webzenk.kr/guide/registration.md
---
# 게임 등록과 키
## 게임 등록 요청
웹젠케이 운영 담당자에게 게임 등록을 요청하면 세 가지 키를 받아요.
| 키 | 어디에 쓰나요 | 넣는 곳 |
|---|---|---|
| **App Key** | 게임 식별 | 앱·웹 (공개돼도 괜찮아요) |
| **App Secret** | 앱 요청 서명 | 모바일·PC 앱 (웹에는 넣지 않아요) |
| **Server Secret** | 개발사 서버 요청 서명 | **개발사 서버에만** |
::: danger Server Secret은 절대 앱·웹에 넣지 마세요
Server Secret이 있으면 지표·결제 내역 조회와 유저 제재를 할 수 있어요. 개발사 서버에서만 쓰고, 저장소에 커밋하지 마세요.
:::
Secret은 등록할 때 한 번만 전달돼요. 비밀번호 관리 도구에 보관하세요. 잃어버렸거나 유출됐다면 운영 담당자에게 **재발급**을 요청하세요. 재발급하면 기존 값은 즉시 쓸 수 없게 되니, App Secret은 앱 업데이트 일정과 맞춰서 요청하는 게 좋아요.
## 쓰는 기능의 연동 정보 전달
쓰려는 기능에 맞춰 아래 정보를 운영 담당자에게 전달하면 서버에 등록해 드려요.
| 기능 | 전달할 정보 |
|---|---|
| Google 로그인 | OAuth 클라이언트 ID 전부 (Android·iOS·Web). Play Games를 쓰면 서버용 클라이언트 ID·Secret |
| Apple 로그인 | 번들 ID (웹 로그인은 Services ID도) |
| Google Play 결제 | 패키지명, 서비스 계정 JSON 키 — Play Console → 사용자 및 권한에서 *재무 데이터 보기·주문 관리* 권한 |
| App Store 결제 | 번들 ID, Issuer ID, Key ID, 앱 내 구입 키(.p8) |
| AppLovin MAX 보상 | MAX 대시보드의 S2S 보상 이벤트 키 |
| HTML5 (웹) | 게임이 열리는 주소(허용 도메인). 예: `https://game.example.com`, `https://*.example.com` |
| 삼성 Instant Plays | 삼성 파트너십 담당자에게 받은 로그인 서명 공개키, 결제 Seller key |
등록이 끝나면 운영 담당자가 **스토어·광고사 콘솔에 넣을 주소**를 알려 드려요.
| 넣을 곳 | 주소 |
|---|---|
| Google Play 실시간 개발자 알림 (Pub/Sub 푸시) | `https://game-api.webzenk.kr/v1/webhooks/google` |
| App Store 서버 알림 V2 (운영·샌드박스) | `https://game-api.webzenk.kr/v1/webhooks/apple` |
| AppLovin MAX Server Side Callback | 게임별 주소 — [보상형 광고](./ads#max-설정) 참고 |
---
---
url: https://developers.webzenk.kr/guide/choose-sdk.md
---
# SDK 선택
| 상황 | 사용 | 인증 |
|---|---|---|
| Unity 모바일 게임 (Android·iOS) | [Unity SDK](/sdk/unity/) — Unity 2022.3 LTS 이상 | App Key + App Secret 서명 |
| HTML5 게임 (웹사이트·삼성 Instant Plays) | [HTML5 SDK](/sdk/html5/) | App Key + 허용 도메인 |
| Unity WebGL | Unity SDK(App Secret 비움) 또는 HTML5 SDK | App Key + 허용 도메인 |
| 그 밖의 엔진 (Cocos, Unreal, 자체 엔진) | [REST API](/api/) 직접 호출 | App Key + App Secret 서명 |
| 개발사 서버 (지표·환불 회수·제재) | [개발사 서버 API](/api/server) | App Key + Server Secret 서명 |
## 두 SDK의 공통 구조
Unity와 HTML5 SDK는 같은 순서로 써요.
1. **초기화** — App Key(와 App Secret)로 SDK를 만들어요.
2. **지급 함수 등록** — 결제·광고 보상을 지급하는 함수를 **로그인 전에** 등록해요.
3. **로그인** — 저장된 세션 → (플랫폼 계정) → 게스트 순서로 자동 로그인해요.
4. **기능 호출** — 저장·랭킹·이벤트·결제·광고.
지급 함수를 먼저 등록해 두면, 로그인 직후 **지난번에 지급하지 못한 결제·광고 보상을 SDK가 자동으로 복구**해요.
::: info 이름 규칙
SDK의 공개 이름은 모두 `WK`(WEBZEN K)로 시작해요. 다른 SDK나 게임 코드와 겹치지 않아요. 예: `WKGameApi`, `WKError`, `WKSamsungPlatform`
:::
---
---
url: https://developers.webzenk.kr/guide/login.md
---
# 로그인·계정
## 로그인 수단
| 수단 | 설명 | 필요한 연동 |
|---|---|---|
| 게스트 | 기기 ID로 바로 시작. **기기 단위**라 앱을 지우면 사라져요 | 없음 |
| Google | Google Sign-In / Credential Manager의 ID 토큰 | Google 클라이언트 ID |
| Play Games | Play Games Services v2 서버 인증 코드 | Play Games 서버 클라이언트 ID·Secret |
| Apple | Sign in with Apple의 identity token | 번들 ID (웹은 Services ID) |
| 삼성 계정 | 삼성 Instant Plays에서만 — [삼성 Instant Plays](./samsung) | 삼성 로그인 서명 공개키 |
로그인 플러그인(Google Sign-In, Sign in with Apple 등)은 게임에서 골라 쓰고, SDK·API에는 **받은 토큰만** 넘겨요.
## 계정 연결
게스트로 시작한 유저에게 Google·Apple 계정을 **연결**하면, 다른 기기에서 그 계정으로 로그인해도 같은 유저로 이어져요.
진행이 어느 정도 쌓이면 계정 연결을 안내하세요.
* 이미 다른 유저에 연결된 계정이면 연결할 수 없어요 (`ALREADY_LINKED`). 그 계정으로 로그인하면 그 유저로 들어가요.
* 같은 종류 계정을 두 개 연결할 수는 없어요 (`PROVIDER_ALREADY_LINKED`).
## 세션
* 로그인하면 **Access Token**(기본 1시간)과 **Refresh Token**(기본 30일)을 받아요. SDK는 만료되면 자동으로 갱신해요.
* Refresh Token은 쓸 때마다 새것으로 바뀌어요. 이미 쓴 토큰을 다시 쓰면 탈취로 보고 **그 유저의 모든 세션을 끊어요**.
* 제재된 유저는 로그인·토큰 갱신이 막혀요 (`PLAYER_BANNED`). 이미 받은 Access Token은 만료(최대 1시간)까지 쓸 수 있어요.
## 탈퇴
게임 안에 **탈퇴 메뉴**를 꼭 넣어 주세요. Apple App Store와 Google Play 모두 계정을 만드는 앱에 계정 삭제 기능을 요구해요.
탈퇴를 요청하면 모든 세션이 끝나고, 유예 기간(기본 30일) 안에는 철회할 수 있어요. 자세한 내용은 [개인정보·탈퇴](./privacy)를 보세요.
**관련 문서** · [로그인 API](/api/auth) · [Unity](/sdk/unity/features#로그인) · [HTML5](/sdk/html5/features#로그인)
---
---
url: https://developers.webzenk.kr/guide/storage.md
---
# 데이터 저장
유저별 **키-값 저장소**예요. 값은 JSON이면 무엇이든 돼요(객체·배열·숫자·문자열). 진행 상황, 설정, 인벤토리 등을 저장해요.
| 항목 | 기본 한도 |
|---|---|
| 키 이름 | 1~64자 `[A-Za-z0-9_.-]` |
| 유저당 키 개수 | 100개 |
| 값 하나 크기 | 64KB |
| 한 번에 여러 키 저장 | 20개 (전부 성공하거나 전부 실패) |
## version — 동시 저장 충돌 막기
같은 계정으로 두 기기에서 플레이하면, 한쪽이 저장한 내용을 다른 쪽이 덮어쓸 수 있어요. 그래서 저장할 때마다 **version**을 함께 보내요.
1. 새 키는 `version: 0`으로 써요.
2. 그다음부터는 **마지막으로 읽거나 쓴 version**을 보내요. 저장할 때마다 1씩 올라가요.
3. 다른 기기가 먼저 저장해서 version이 다르면 `409 VERSION_CONFLICT`가 와요. 다시 읽어서 합친 뒤 저장하세요.
SDK는 읽고 쓴 version을 기억하므로 보통은 신경 쓰지 않아도 되고, **update** 함수는 충돌이 나면 다시 읽어서 자동으로 재시도해요.
## 공개 데이터
`is_public`으로 저장한 키는 다른 유저가 읽을 수 있어요. 닉네임·프로필처럼 남에게 보여 줄 데이터에 써요.
::: warning 재화는 클라이언트 저장만 믿지 마세요
클라이언트가 저장하는 값은 조작될 수 있어요. 결제·광고 보상은 반드시 [결제 검증](./iap)·[보상형 광고](./ads) 흐름으로 지급하세요.
:::
**관련 문서** · [저장 API](/api/storage) · [Unity](/sdk/unity/features#저장) · [HTML5](/sdk/html5/features#저장)
---
---
url: https://developers.webzenk.kr/guide/ranking.md
---
# 랭킹
리더보드는 운영 담당자가 만들어요. 아래 항목을 정해서 요청하세요. **코드는 API에서 쓰는 이름이라 나중에 바꿀 수 없어요.**
| 설정 | 선택 |
|---|---|
| 코드 | 영문 소문자·숫자·`_` 32자 (예: `weekly_score`) |
| 정렬 | 높을수록 위(점수) / 낮을수록 위(기록 경기) |
| 점수 정책 | 최고 기록 / 마지막 기록 / 누적 |
| 시즌 주기 | 계속 / 매일 / 매주(월요일 시작) / 매월 / 수동(대회) — 게임 시간대 기준 |
| 어뷰징 방지 | 최소·최대 점수, 제출 간격(초) |
## 규칙
* **동점**은 그 점수를 먼저 달성한 유저가 위예요. 순위는 겹치지 않아요(1, 2, 3…).
* **시즌 번호**: 일간 `20261119`(YYYYMMDD), 주간 `202647`(ISO 연도+주), 월간 `202611`, 수동·계속은 1부터 오르는 번호.
* 끝난 시즌은 상위 순위가 보관돼요(기본 1,000위). **시즌 보상은 끝난 시즌 결과**로 지급하세요.
* 점수 범위 밖이면 `SCORE_OUT_OF_RANGE`, 너무 자주 제출하면 `SUBMIT_TOO_FAST`예요.
* 어뷰징 유저의 점수는 운영 담당자가 지울 수 있어요.
**관련 문서** · [랭킹 API](/api/leaderboards) · [Unity](/sdk/unity/features#랭킹) · [HTML5](/sdk/html5/features#랭킹)
---
---
url: https://developers.webzenk.kr/guide/metrics.md
---
# 지표·이벤트
## 자동으로 집계되는 지표
게임이 따로 보내지 않아도 서버가 집계해요.
| 지표 | 기준 |
|---|---|
| DAU | 그날 로그인 또는 API 호출이 있었던 유저 |
| 신규 | 그날 가입한 유저 |
| 결제·결제자 | 검증일 기준, 테스트 결제 제외 |
| 매출 | **통화별로 따로** (환산 안 함). Google Play는 앱이 보낸 표시 가격 기준 |
| 광고 | 보상 확정 건수와 시청 유저 수 |
| 리텐션 | 가입일 코호트의 D1·D3·D7·D14·D30 재접속률 |
날짜는 게임 시간대 기준이고, 매시간 오늘·어제를 다시 계산하므로 최대 1시간 늦어요.
조회는 [개발사 서버 API](/api/server)로 해요.
## 커스텀 이벤트
게임 고유의 행동(스테이지 클리어, 튜토리얼 완료 등)은 **이벤트**로 보내면 이름별로 건수·유저 수가 집계돼요.
| 항목 | 규칙 |
|---|---|
| 이름 | 소문자로 시작하는 `[a-z0-9_]` 64자 — 예: `stage_clear`, `tutorial_done` |
| 속성 (props) | 4KB 이내 객체 |
| 한도 | 요청당 100건, 유저당 하루 5,000건 |
| 원본 보관 | 90일 (집계 결과는 계속 남아요) |
SDK는 이벤트를 모아서 보내고, 오프라인이면 기기에 보관했다가 다시 보내요.
**관련 문서** · [이벤트 API](/api/events) · [개발사 서버 API](/api/server)
---
---
url: https://developers.webzenk.kr/guide/iap.md
---
# 결제 검증
앱에서 받은 영수증을 서버가 **스토어 서버에 직접 조회**해서 확인해요. 영수증 위조, 다른 유저 영수증 재사용, 중복 지급을 막아요.
| 스토어 | 검증 방식 |
|---|---|
| Google Play | Google Play Developer API로 구매 조회 + 승인(acknowledge) |
| App Store | App Store Server API로 거래 조회 (운영 → 샌드박스 순) |
| 삼성 Instant Plays | 영수증 서명 검증 + 삼성 receipt API — [삼성 Instant Plays](./samsung) |
## 흐름
1. 앱에서 스토어 결제창으로 결제해요. 스토어 쪽 완료 처리(consume·finish)는 **아직 하지 않아요**.
2. 영수증을 서버로 보내 **검증**해요.
3. 상태가 `verified`면 아이템을 **지급**해요.
4. 지급이 끝나면 **지급 완료를 보고**해요 → `consumed`
5. 스토어에 **완료 처리**해요. 완료 처리하지 않은 결제는 다음 실행 때 스토어가 다시 넘겨줘요.
SDK를 쓰면 2~5단계를 자동으로 해요. 게임은 **지급 함수**만 만들면 돼요.
## 결제 상태
| 상태 | 뜻 | 게임이 할 일 |
|---|---|---|
| `verified` | 검증됨, 지급 보고 전 | 지급 → 지급 완료 보고 |
| `consumed` | 지급 완료 보고됨 | 없음 (스토어 완료 처리만) |
| `pending` | Google 보류 결제 (결제 미완료) | 지급하지 말고 나중에 다시 |
| `refunded` | 환불됨 | — [환불 처리](./refunds) |
## 꼭 알아 둘 것
* **같은 영수증은 한 번만 지급돼요.** 다시 보내면 같은 결제 기록과 `already_processed: true`가 와요. 지급 여부는 상태로 판단하세요.
* **지급 도중 앱이 꺼져도 괜찮아요.** 로그인 직후 `verified`로 남은 결제를 다시 지급하면 돼요(SDK는 자동).
* **테스트 결제**(Google 라이선스 테스터, Apple 샌드박스, 삼성 TEST 모드)도 검증되고 `is_sandbox: true`로 표시돼요. 매출 지표에서 빠져요.
* 다른 유저가 등록한 영수증은 `PURCHASE_OWNED_BY_OTHER`, 위조·취소된 영수증은 `RECEIPT_INVALID`예요. 지급하지 마세요.
* 스토어 장애(`503 STORE_UNAVAILABLE`)면 스토어 완료 처리를 하지 말고 나중에 다시 시도하세요.
* 정기결제(구독)와 ONE store는 아직 지원하지 않아요.
**관련 문서** · [결제 API](/api/iap) · [Unity IAP 연동](/sdk/unity/iap) · [HTML5 결제](/sdk/html5/iap-ads) · [환불 처리](./refunds)
---
---
url: https://developers.webzenk.kr/guide/ads.md
---
# 보상형 광고
AppLovin MAX의 \*\*서버 콜백(S2S)\*\*으로 광고를 끝까지 봤는지 확인한 뒤 보상해요. 앱의 "보상 받음" 이벤트만 믿지 않으므로, 조작으로 보상을 받을 수 없어요.
## MAX 설정
1. 운영 담당자에게 MAX 대시보드의 **S2S 이벤트 키**를 전달하면, 게임 전용 콜백 주소를 받아요.
2. MAX 대시보드에서 **보상형 광고 단위마다** Server Side Callback URL에 그 주소를 넣어요.
3. 앱에서 광고 SDK의 User ID를 유저의 `player_id`로 설정해요. SDK는 로그인할 때 자동으로 설정해요.
콜백 주소 형식 (게임 코드만 다름):
```text
https://game-api.webzenk.kr/v1/ads/callback/applovin/{게임코드}?user_id={USER_ID}&event_id={EVENT_ID}&token={EVENT_TOKEN}&custom_data={CUSTOM_DATA}&placement={PLACEMENT}&ad_unit={AD_UNIT_ID}&network={NETWORK_NAME}&amount={AMOUNT}¤cy={CURRENCY}
```
## 흐름
1. 광고를 보여 주기 전에 **보상 세션**을 만들어요. 하루 한도를 넘었으면 여기서 알려 줘요(`AD_DAILY_CAP`) — 광고를 띄우지 마세요.
2. 세션의 `custom_data`를 넣어서 광고를 재생해요.
3. 광고가 끝나면 세션 상태를 확인해요. 콜백은 보통 몇 초 안에 와요. `rewarded`가 되면 **보상을 지급**해요.
4. **지급 완료를 보고**해요 → `claimed`
콜백이 늦게 와서 앱이 기다리다 끝냈더라도, 다음 로그인 때 "콜백은 왔지만 지급 안 된 보상"을 받아서 지급하면 돼요. SDK는 이 과정을 자동으로 해요.
## 보상 상태
| 상태 | 뜻 |
|---|---|
| `pending` | 광고사 확인(콜백) 대기 |
| `rewarded` | 확인됨, 지급 전 |
| `claimed` | 지급 완료 |
| `rejected` | 거부 (한도 초과, 다른 유저 세션 등) |
| `expired` | 콜백 없이 세션 만료 (기본 1시간) |
하루 보상 횟수는 게임별 설정이에요(기본 placement별 20회).
::: info HTML5 플랫폼 광고
삼성 Instant Plays 등 HTML5 플랫폼 광고는 서버 콜백이 없어서, SDK가 알려 주는 결과(`rewarded`)로 게임이 판단해요.
:::
**관련 문서** · [광고 API](/api/ads) · [Unity + MAX](/sdk/unity/ads) · [HTML5 광고](/sdk/html5/iap-ads)
---
---
url: https://developers.webzenk.kr/guide/html5.md
---
# 웹 (HTML5)
브라우저에는 Secret을 둘 수 없어서, HTML5 게임은 **App Key + 허용 도메인**으로 접속해요. 로그인한 뒤에는 앱과 같은 유저 토큰을 써요.
## 준비
1. 게임이 열리는 주소를 운영 담당자에게 전달해 **허용 도메인**으로 등록해요.
* `https://game.example.com` — 이 주소만
* `https://*.example.com` — 하위 도메인 전체 (상위 도메인 자체는 아님)
* `http://localhost:8080` — 개발용 (http는 localhost만)
2. [HTML5 SDK](/sdk/html5/)를 넣고 App Key만으로 초기화해요.
## 웹에서 다른 점
| 항목 | 웹 |
|---|---|
| 인증 | App Key + 브라우저가 붙이는 `Origin`. App Secret 서명 없음 |
| 로그인 | 게스트, Google·Apple(직접 받은 ID 토큰), 플랫폼 계정 |
| 결제 | 플랫폼 결제만 (삼성 Instant Plays). Google Play·App Store 검증은 막혀 있어요 |
| 광고 | 플랫폼 광고 SDK (서버 콜백 없음) |
| 저장·랭킹·이벤트 | 앱과 같아요 |
자주 보는 오류:
* `403 ORIGIN_NOT_ALLOWED` — 지금 주소가 허용 도메인에 없어요.
* `403 WEB_NOT_ENABLED` — 게임에 웹이 아직 켜지지 않았어요.
* `403 WEB_NOT_SUPPORTED` — 웹에서 쓸 수 없는 API예요 (스토어 결제·MAX 광고).
::: tip Unity WebGL
Unity WebGL 빌드도 브라우저라서 같은 규칙이에요. Unity SDK에서 `AppSecret`을 비우면 웹 모드로 동작해요.
:::
---
---
url: https://developers.webzenk.kr/guide/samsung.md
---
# 삼성 Instant Plays
Galaxy Store Instant Plays(게임 런처)에 올리는 HTML5 게임이에요. HTML5 SDK의 `WKSamsungPlatform`이 삼성 SDK와 Game API를 이어 줘요.
| 기능 | 지원 |
|---|---|
| 로그인 | 삼성 계정 (없으면 게스트, 나중에 연결) |
| 결제 | 삼성 IAP → 서버 영수증 검증 → 지급 → 삼성 소진(consume) |
| 광고 | Samsung Ads + AdMob (advertisement2) |
| 저장·랭킹·이벤트 | Game API |
## 준비
1. 삼성 파트너십 담당자에게 **로그인 서명 공개키**와 **결제 Seller key**를 받아 운영 담당자에게 전달해요.
2. 게임이 열리는 실제 주소(`location.origin`)를 허용 도메인으로 등록해요. 삼성 Debug APK를 설치하고 PC의 `chrome://inspect`로 확인할 수 있어요.
3. `index.html`에 삼성 SDK를 **스크립트 태그로 직접** 넣어요. 다른 방식으로 로드하면 삼성 검수를 통과하지 못해요.
```html
```
## 동작 방식
* **로그인**: 삼성 `getSignatureAsync()` 서명을 서버가 삼성 공개키로 검증해요. 삼성 계정이 로그인돼 있지 않으면 게스트로 시작하고, 버튼을 눌렀을 때 삼성 로그인 창을 띄워 연결할 수 있어요.
* **결제**: SDK가 결제 요청에 `wk:`를 넣고, 서버는 영수증 서명과 삼성 결제 조회로 확인해요. 다른 유저의 영수증은 거부돼요.
* **계정 변경**: 게임 중에 삼성 계정이 바뀌면 삼성 규격에 따라 게임을 재시작해야 해요(SDK의 `onAccountChange` → `restart`).
* **SDK 0.46**: `setDataAsync`/`getDataAsync`에 삼성 계정 인증이 적용됐고 `adStart`/`adEnd`는 폐기됐어요. Game API 저장소를 쓰면 영향이 없어요.
::: warning 결제 방식 확인 중
삼성 결제는 Instant Games IAP SDK(`iapinstant.1.0.js`) 기준이에요. 최신 GSInstant SDK 0.46에는 결제 API가 없어, 현재 결제 방식은 삼성과 확인 중이에요.
:::
**관련 문서** · [HTML5 플랫폼 SDK](/sdk/html5/platforms) · [시작 템플릿](/sdk/html5/platforms#삼성-시작-템플릿)
---
---
url: https://developers.webzenk.kr/guide/testing.md
---
# 테스트하기
## 순서
1. **로그인** — 게스트로 로그인해서 `player_id`를 받는지 확인해요. 운영 담당자에게 그 ID를 알려 주면 서버에서도 확인할 수 있어요.
2. **저장·랭킹** — 저장 → 다시 읽기, 점수 제출 → 순위 조회.
3. **결제** — 테스트 계정으로 결제해요. 서버 결제 기록이 `consumed`까지 가면 지급 완료 보고까지 연동된 거예요.
4. **광고** — 보상형 광고를 끝까지 보고 `claimed`가 되는지 확인해요.
5. **복구** — 결제 직후 앱을 강제 종료하고 다시 열어, 아이템이 한 번만 지급되는지 확인해요.
## 테스트 결제
| 스토어 | 방법 |
|---|---|
| Google Play | Play Console → 설정 → 라이선스 테스트에 계정 추가, 내부 테스트 트랙으로 설치 |
| App Store | App Store Connect 샌드박스 테스터 계정, TestFlight 빌드 |
| 삼성 Instant Plays | 삼성 IAP TEST 모드 (삼성 담당자 안내) |
테스트 결제는 실제로 검증되고 `is_sandbox: true`로 기록돼요. 매출 지표에서는 빠져요.
::: warning 에디터에서는 결제를 확인할 수 없어요
Unity 에디터의 FakeStore 영수증은 스토어 서버에서 조회되지 않아요. 결제는 실제 기기 빌드로 확인하세요.
:::
## 서명 확인 (REST 직접 호출)
서명이 맞는지 헷갈리면 [인증과 서명](/api/#서명-만들기)의 예제 코드로 게스트 로그인을 먼저 성공시켜 보세요.
`INVALID_SIGNATURE`가 나오면 대부분 아래 중 하나예요.
* 쿼리가 없는데 경로 끝에 `?`를 붙였어요.
* 본문을 서명할 때와 보낼 때 다르게 직렬화했어요 (공백·키 순서).
* App Secret 대신 다른 값(App Key, Server Secret)을 썼어요.
---
---
url: https://developers.webzenk.kr/guide/launch-checklist.md
---
# 출시 체크리스트
오픈 전에 아래 항목을 확인하세요. 웹젠케이 운영 담당자도 같은 목록으로 확인해요.
## 계정·기본
* \[ ] 게스트 로그인 후 **계정 연결**(Google·Apple 등)을 안내하는 화면이 있어요
* \[ ] 게임 안에 **탈퇴 메뉴**가 있어요 (Apple·Google 심사 필수)
* \[ ] 세션이 끊겼을 때(제재·탈퇴) 로그인 화면으로 돌아가요
* \[ ] 문의 대응을 위해 게임 안에서 **유저 ID**를 확인할 수 있어요
## 결제
* \[ ] 테스트 결제가 `consumed`까지 처리돼요 (지급 완료 보고까지)
* \[ ] 결제 직후 앱을 종료했다가 다시 열면 **한 번만** 지급돼요
* \[ ] 스토어 서버 알림 주소를 등록했어요 (Google RTDN, App Store 서버 알림 V2)
* \[ ] 개발사 서버가 **환불 목록**을 주기적으로 조회해 재화를 회수해요 — [환불 처리](./refunds)
## 광고
* \[ ] MAX 보상형 광고 단위마다 Server Side Callback URL을 등록했어요
* \[ ] 보상형 광고 시청 후 `claimed`가 되고, 하루 한도를 넘으면 광고 버튼이 숨겨져요
## 운영
* \[ ] 리더보드 코드·주기, 게임 시간대, 광고 일일 한도를 확정했어요 (시간대는 오픈 후 바꾸지 않아요)
* \[ ] App Secret·Server Secret이 저장소·로그에 남지 않아요
* \[ ] 예상 동시 접속이 크면 운영 담당자와 요청 한도를 상의했어요
---
---
url: https://developers.webzenk.kr/guide/refunds.md
---
# 환불 처리
환불은 각 스토어에서 처리되고, 서버가 자동으로 결제 상태를 `refunded`로 바꿔요.
| 스토어 | 반영 |
|---|---|
| App Store | App Store 서버 알림 V2로 즉시 |
| Google Play | 실시간 개발자 알림(RTDN)으로 즉시, 놓쳐도 1시간마다 환불 목록을 조회해 반영 |
## 지급한 재화 회수
이미 지급한 재화를 회수하는 건 **개발사 서버**가 해요.
1. [개발사 서버 API](/api/server)의 `GET /v1/server/purchases?status=refunded`를 처음에는 `since` 없이 호출하고, 응답의 `next_since`를 저장해요.
2. 이후 주기적으로(예: 1시간) `since=next_since`로 호출해요. 경계에 있는 건이 다시 올 수 있으니 `purchase_id`로 중복을 걸러요.
3. 환불된 결제의 `player_id`·`product_id`로 재화를 회수하거나, 반복 환불 유저를 제재해요(`/v1/server/players/{id}/ban`).
::: tip 이미 써 버린 재화
회수할 재화가 부족하면 마이너스 잔액·이용 제한 등 게임 정책을 미리 정해 두세요.
:::
---
---
url: https://developers.webzenk.kr/guide/privacy.md
---
# 개인정보·탈퇴
* 개인정보 처리방침:
## 저장되는 정보
로그인 수단 식별자(기기 ID, Google·Apple·플랫폼 계정 ID), 게임이 저장한 데이터, 랭킹 점수, 이벤트, 결제·광고 보상 기록, 접속 일자가 저장돼요.
**이메일·이름 같은 정보는 받지 않아요.** 저장 데이터에 개인정보를 넣지 않도록 주의하세요.
## 탈퇴 흐름
1. 유저가 게임 안 탈퇴 메뉴에서 탈퇴를 요청해요 → 모든 세션이 바로 끝나요.
2. **유예 기간**(기본 30일) 안에는 탈퇴를 철회할 수 있어요. 로그인 응답의 `deletion_requested_at`이 있으면 "탈퇴 철회" 화면을 보여 주세요.
3. 유예 기간이 지나면 파기돼요.
| 파기 | 보관 (개인을 알아볼 수 없는 번호로만) |
|---|---|
| 로그인 수단 식별자, 세션, 저장 데이터, 진행 중 랭킹 점수, 이벤트 | 결제·광고 보상 기록, 접속 일자, 끝난 시즌 순위 — 환불·정산·지표용 |
파기 후 같은 계정으로 다시 로그인하면 **새 유저**가 돼요.
**관련 문서** · [탈퇴 API](/api/auth#탈퇴)
---
---
url: https://developers.webzenk.kr/guide/faq.md
---
# 자주 묻는 질문
## 연동
**App Secret이 앱에 들어가도 괜찮나요?**
App Secret은 요청 위변조·재전송을 막는 용도예요. 앱에서 추출될 수 있다는 전제로 설계돼 있어서, 결제·광고 보상 같은 중요한 판단은 항상 스토어·광고사 서버 검증으로 해요. **Server Secret은 절대 앱에 넣지 마세요.**
**`INVALID_SIGNATURE`가 계속 나와요.**
쿼리가 없는데 끝에 `?`를 붙였거나, 서명한 본문과 보낸 본문이 다른 경우가 대부분이에요. [테스트하기](./testing#서명-확인-rest-직접-호출)를 보세요.
**`TIMESTAMP_SKEW`가 나와요.**
기기 시각이 서버와 5분 넘게 차이 나요. 오류 응답의 `server_time`으로 보정해 다시 보내세요(SDK는 자동).
## 계정
**기기를 바꾸면 게스트 데이터가 사라지나요?**
네. 게스트는 기기 단위예요. 진행이 쌓이면 Google·Apple 계정 연결을 안내하세요.
**탈퇴한 유저가 다시 들어오면요?**
유예 기간 안이면 철회해서 이어서 할 수 있어요. 지나면 새 유저로 시작해요.
## 결제·광고
**결제했는데 아이템이 안 들어왔다는 문의가 와요.**
게임을 다시 열면 SDK가 로그인 직후 `verified`로 남은 결제를 자동으로 지급해요. 그래도 안 되면 유저 ID와 주문번호를 웹젠케이 운영 담당자에게 전달하세요.
**광고를 봤는데 보상이 안 들어왔어요.**
광고사 콜백이 늦게 오면 다음 로그인 때 지급돼요. 광고를 끝까지 보지 않았거나 하루 한도를 넘었으면 보상 대상이 아니에요.
**테스트 결제도 매출에 잡히나요?**
아니요. `is_sandbox: true`로 기록되고 매출 지표에서 빠져요.
## 문의
오류를 문의할 때는 응답의 \*\*`trace_id`\*\*와 **오류 코드**, 시각, 유저 ID를 함께 보내 주세요.
---
---
url: https://developers.webzenk.kr/sdk.md
---
# API & SDK 한눈에 보기
기능별로 SDK 사용법과 REST API 문서를 모았어요. SDK를 쓰면 서명·토큰 갱신·결제 복구를 SDK가 처리해요.
| 기능 | 설명 | Unity | HTML5 | REST API |
|---|---|---|---|---|
| 초기화 | App Key(·Secret)로 SDK 시작 | [설치·시작](./unity/) | [설치·시작](./html5/) | [인증과 서명](/api/) |
| 로그인 | 게스트·Google·Play Games·Apple·삼성 계정, 계정 연결 | [로그인](./unity/features#로그인) | [로그인](./html5/features#로그인) | [로그인·계정](/api/auth) |
| 저장 | 유저별 JSON 저장, 충돌 시 재시도 | [저장](./unity/features#저장) | [저장](./html5/features#저장) | [데이터 저장](/api/storage) |
| 랭킹 | 점수 제출·순위·지난 시즌 | [랭킹](./unity/features#랭킹) | [랭킹](./html5/features#랭킹) | [랭킹](/api/leaderboards) |
| 이벤트 | 커스텀 이벤트 (모아서 전송) | [이벤트](./unity/features#이벤트) | [이벤트](./html5/features#이벤트) | [이벤트](/api/events) |
| 결제 | 스토어 결제 → 서버 검증 → 지급 → 완료 | [Unity IAP](./unity/iap) | [플랫폼 결제](./html5/iap-ads#결제) | [결제](/api/iap) |
| 보상형 광고 | 광고 시청 → 서버 확인 → 지급 | [AppLovin MAX](./unity/ads) | [플랫폼 광고](./html5/iap-ads#광고) | [보상형 광고](/api/ads) |
| 플랫폼 | 웹·삼성 Instant Plays | — | [플랫폼](./html5/platforms) | — |
| 지표 조회·환불 회수·제재 | 개발사 서버에서 | — | — | [개발사 서버 API](/api/server) |
## SDK 비교
| | Unity SDK | HTML5 SDK |
|---|---|---|
| 패키지 | `com.webzenk.wk-gameapi` (UPM) | `@webzenk/wk-gameapi` (npm) / `wk-gameapi.min.js` |
| 대상 | Unity 2022.3 LTS 이상, Android·iOS (WebGL은 웹 모드) | 웹사이트, 삼성 Instant Plays |
| 인증 | App Key + App Secret 서명 | App Key + 허용 도메인 |
| 결제 | Unity IAP 4.8+ (설치했을 때만 연결) | 플랫폼 결제 (삼성 IAP) |
| 광고 | AppLovin MAX (샘플 어댑터) | 플랫폼 광고 (Samsung Ads + AdMob) |
| 외부 의존 | 없음 (자체 JSON) | 없음 |
| 비동기 | `async`/`await` (Task) | `async`/`await` (Promise) |
[다운로드 →](./download)
---
---
url: https://developers.webzenk.kr/sdk/download.md
---
# 다운로드
## Unity SDK
| 버전 | 파일 | 요구 사항 |
|---|---|---|
| 0.1.0 | [com.webzenk.wk-gameapi-0.1.0.tgz](/downloads/com.webzenk.wk-gameapi-0.1.0.tgz) | Unity 2022.3 LTS 이상 |
**설치**: Unity → Window → Package Manager → `+` → **Add package from tarball…** → 받은 `.tgz` 선택.
결제는 In-App Purchasing(4.8 이상), 광고는 AppLovin MAX Unity Plugin을 함께 설치해요. → [설치·시작](./unity/)
## HTML5 SDK
| 버전 | 파일 | 용도 |
|---|---|---|
| 0.1.0 | [wk-gameapi.min.js](/downloads/wk-gameapi.min.js) | `
```
```ts [npm·번들러]
// dist/esm 을 프로젝트에 두고 (다운로드의 ESM zip)
import { WKGameApi, WKSamsungPlatform } from '@webzenk/wk-gameapi'
```
:::
파일은 [다운로드](../download)에서 받아요.
## 시작
```js
const { WKSamsungPlatform, WKError } = WKGameApi // 필요한 클래스만 꺼내 쓰기
const api = await WKGameApi.init({ appKey: '…', appVersion: '1.0.0' }) // Secret 없음
api.setLoadingProgress(50) // 플랫폼 로딩 화면 (삼성)
await api.auth.login() // 플랫폼 계정 → 저장된 세션 → 게스트
if (api.iap.supported) await api.iap.restore(grantItem) // 결제 복구
await api.start() // 로딩 화면 제거, 게임 시작
```
* `platform`을 생략하면 자동으로 골라요. 페이지에 삼성 SDK(`GSInstant`)가 있으면 `WKSamsungPlatform`, 없으면 `WKWebPlatform`.
* 삼성은 `window.onload` 이후에 `init`을 호출하세요.
* 게임 주소가 [허용 도메인](/guide/html5#준비)에 등록돼 있어야 해요.
::: warning 같은 이름으로 다시 선언하지 마세요
`const { WKGameApi } = WKGameApi` 처럼 쓰면 전역 이름이 가려져 오류가 나요. 다른 클래스만 꺼내 쓰세요.
:::
## 옵션
| 옵션 | 기본 | 설명 |
|---|---|---|
| `appKey` | — | 필수 |
| `baseUrl` | `https://game-api.webzenk.kr` | |
| `platform` | 자동 | `new WKWebPlatform()` / `new WKSamsungPlatform({...})` |
| `appVersion` | — | 이벤트에 함께 기록 |
| `timeoutMs` | 10000 | 요청 타임아웃 |
| `debug` | false | `[wk-gameapi]` 로그 |
## 이름 규칙
| 항목 | 이름 |
|---|---|
| 전역 (스크립트 태그) | `WKGameApi` 하나 — 다른 클래스는 `WKGameApi.WKSamsungPlatform`처럼 그 속성 |
| 클래스·타입 | `WKGameApi`, `WKError`, `WKWebPlatform`, `WKSamsungPlatform`, `WKPurchase` … |
| 브라우저 저장소 키 | `wk.ga:`로 시작 |
---
---
url: https://developers.webzenk.kr/sdk/html5/features.md
---
# 로그인·저장·랭킹·이벤트
## 로그인
```js
await api.auth.login() // 자동
await api.auth.login({ interactive: true }) // 삼성 계정이 없으면 삼성 로그인 창 (버튼에서)
await api.auth.loginGoogle(credential) // Google Identity Services 의 ID 토큰
await api.auth.loginApple(idToken, nonce) // Sign in with Apple JS
await api.auth.linkPlatform() // 지금 게스트 계정에 삼성 계정 연결
await api.auth.linkGoogle(credential)
api.auth.playerId // 서버 유저 ID
api.auth.onSessionLost = (e) => showLogin() // 제재·탈퇴·토큰 폐기
await api.auth.logout()
await api.auth.deleteAccount() // 탈퇴 요청
```
* 토큰 만료는 SDK가 갱신해요. 세션은 브라우저 저장소에 보관돼 새로고침해도 같은 유저예요.
* 게스트는 브라우저 단위예요. 브라우저 데이터를 지우면 새 게스트가 돼요.
## 저장
```js
const save = await api.storage.get('save') // 없으면 null — save.value, save.version
await api.storage.set('save', { stage: 3, gold: 120 })
await api.storage.update('save', (cur) => ({ ...cur, gold: (cur?.gold ?? 0) + 10 })) // 충돌 시 재시도
await api.storage.setMany([{ key: 'a', value: 1 }, { key: 'b', value: 2 }])
await api.storage.delete('a')
await api.storage.set('profile', { nick: 'wk' }, { isPublic: true })
const others = await api.storage.publicOf(playerId)
```
## 랭킹
```js
const r = await api.leaderboard.submit('weekly', 1530) // { score, rank, total, updated }
const top = await api.leaderboard.top('weekly', 50)
const around = await api.leaderboard.me('weekly', 5)
const last = await api.leaderboard.season('weekly', 202646)
```
## 이벤트
```js
api.events.track('stage_clear', { stage: 3, time_sec: 72 })
```
5초마다 또는 20건이 쌓이면 보내고, 페이지가 숨겨질 때도 보내요. 실패하면 브라우저에 보관했다가 다시 보내요.
## 서버 시각
```js
api.serverTime() // epoch 초
```
---
---
url: https://developers.webzenk.kr/sdk/html5/platforms.md
---
# 플랫폼 (웹·삼성)
HTML5 SDK는 **플랫폼 어댑터** 구조예요. 공통 API(로그인·저장·랭킹·결제·광고)는 같고, 플랫폼마다 다른 부분을 어댑터가 맞춰 줘요.
| 어댑터 | 플랫폼 | 로그인 | 결제 | 광고 |
|---|---|---|---|---|
| `WKWebPlatform` | 일반 웹사이트 | 게스트, Google·Apple | — | 직접 연결 (선택) |
| `WKSamsungPlatform` | 삼성 Instant Plays | 삼성 계정 / 게스트 | 삼성 IAP | Samsung Ads + AdMob |
지원 플랫폼은 계속 늘어나요.
## 웹
```js
const api = await WKGameApi.init({
appKey: '…',
platform: new WKGameApi.WKWebPlatform({
// 포털 광고 SDK 를 쓰면 연결 (선택)
showAd: (format) => portal.showAd(format).then((ok) => ({ shown: true, rewarded: ok })),
}),
})
```
## 삼성 Instant Plays
```js
const api = await WKGameApi.init({
appKey: '…',
platform: new WKGameApi.WKSamsungPlatform({
ads: { // 광고를 쓰지 않으면 생략
gameTitle: 'My Game', // 영문
samsungRewardedAdPlacementId: '…',
samsungInterstitialAdPlacementId: '…',
admobRewardedAdUnitId: '…',
admobInterstitialAdUnitId: '…',
},
}),
})
api.platform.onAccountChange(() => api.platform.restart()) // 삼성 규격: 계정이 바뀌면 재시작
api.platform.onPause(() => pauseGame())
api.platform.onResume(() => resumeGame())
```
| 멤버 | 설명 |
|---|---|
| `setLoadingProgress(n)` | 삼성 로딩 화면 진행률 |
| `start()` | `startGameAsync` — 로딩 화면 제거 |
| `platform.loginStatus()` | `LOGIN` / `NO_LOGIN` / `IN_PROGRESS` |
| `platform.restart()` | 게임 재시작 |
### 삼성 시작 템플릿
```html
```
## 새 플랫폼 어댑터
`WKBasePlatform`을 상속해 `getLoginProof`·`purchase`·`consume`·`showAd` 등을 구현해요. 서버에도 같은 id의 어댑터가 필요하니 웹젠케이 운영 담당자와 상의하세요.
---
---
url: https://developers.webzenk.kr/sdk/html5/iap-ads.md
---
# 결제·광고
## 결제
플랫폼 결제(현재 삼성 IAP)를 서버에서 검증해요.
```js
const products = await api.iap.products(['gem_100']) // priceString: 표시 가격
try {
const p = await api.iap.purchase('gem_100', grantItem) // 검증 → grantItem → 완료 보고 → 플랫폼 소진
} catch (e) {
if (e.code === 'CANCELED') return // 유저 취소
throw e
}
async function grantItem(purchase) { // 같은 결제로 두 번 호출되지 않아요
addGems(100)
await api.storage.update('save', (s) => ({ ...s, gems: s.gems + 100 }))
}
await api.iap.restore(grantItem) // 게임 시작마다 — 지난번 미지급분 복구
```
* `grantItem`이 예외를 던지거나 지급 중 페이지가 닫히면 소진하지 않고 남겨 둬요. 다음 실행의 `restore()`가 다시 지급해요.
* 결제 요청에는 `wk:`가 들어가서, 다른 유저의 영수증은 서버가 거부해요.
## 광고
```js
const r = await api.ads.showRewarded()
if (r.rewarded) giveReward() // 끝까지 본 경우만
await api.ads.showInterstitial()
api.ads.preload('rewarded') // 미리 로드하면 바로 재생
```
| 결과 | 설명 |
|---|---|
| `shown` | 광고가 재생됐는지 |
| `rewarded` | 보상형을 끝까지 봤는지 (스킵·오류면 false) |
| `reason` | `no_fill` · `show_error` · `busy` · `not_supported` · `timeout` |
HTML5 플랫폼 광고는 서버 콜백이 없어서 `rewarded`로 게임이 판단해요. 하루 횟수 같은 제한은 게임에서 관리하세요.
---
---
url: https://developers.webzenk.kr/sdk/html5/errors.md
---
# 오류 처리 (HTML5)
모든 API는 실패하면 `WKError`를 던져요.
```js
try {
await api.storage.set('save', data)
} catch (e) {
if (e.code === 'VERSION_CONFLICT') { /* 다시 읽어서 합치기 */ }
else if (e.retryable) { /* 잠시 후 다시 */ }
else console.error(e.code, e.message, e.traceId)
}
```
| 속성 | 설명 |
|---|---|
| `code` | 서버 오류 코드 또는 SDK 코드 |
| `status` | HTTP 상태 (네트워크 오류는 0) |
| `retryable` | 네트워크·5xx·429 |
| `traceId` | 문의할 때 함께 전달 |
| `details` | 추가 정보 |
## SDK 코드
| code | 뜻 |
|---|---|
| `NETWORK_ERROR` | 오프라인, 타임아웃, CORS 차단(주소가 잘못됨) |
| `NOT_LOGGED_IN` | 로그인 전 호출 |
| `NOT_SUPPORTED` | 현재 플랫폼에 없는 기능 |
| `PLATFORM_ERROR` | 플랫폼 SDK 오류 (`details.platformError`에 원문) |
| `CANCELED` | 유저가 결제·로그인 취소 |
웹에서 자주 보는 서버 오류: `ORIGIN_NOT_ALLOWED`(허용 도메인 아님), `WEB_NOT_ENABLED`(웹 꺼짐). 전체 목록은 [오류 코드](/api/errors).
---
---
url: https://developers.webzenk.kr/api.md
---
# 인증과 서명
모든 요청은 `https://game-api.webzenk.kr`로 보내요. 요청은 세 가지 방식으로 인증하고, 로그인한 뒤에는 유저 토큰(`Authorization: Bearer`)을 더해요.
| 구분 | 누가 | 헤더 |
|---|---|---|
| **앱 서명** | 모바일·PC 클라이언트 | `X-App-Key`, `X-Timestamp`, `X-Nonce`, `X-Signature` (App Secret) |
| **웹** | HTML5·WebGL (브라우저) | `X-App-Key` (+ 브라우저의 `Origin`이 허용 도메인이어야 함) |
| **서버 서명** | 개발사 서버 | 앱 서명과 같은 방식, 키만 **Server Secret** |
API 문서의 인증 표시: **앱** = 로그인 전 · **유저** = Access Token 필요 · **서버** = Server Secret 서명
## 서명 만들기
```text
string_to_sign = METHOD + "\n"
+ REQUEST_URI + "\n" // 경로 + 쿼리 (보내는 그대로). 예: /v1/leaderboards/weekly/top?limit=50
+ X-Timestamp + "\n" // epoch 초
+ X-Nonce + "\n" // 요청마다 새 무작위 값 8~64자 [A-Za-z0-9_-]
+ SHA256_HEX(body) // 본문이 없으면 빈 문자열의 SHA-256
X-Signature = Base64( HMAC-SHA256(key = Secret, message = string_to_sign) )
```
* **쿼리가 없으면 `?`를 붙이지 마세요.** 끝에 빈 `?`가 있으면 빼고 서명해요.
* 쿼리스트링은 **보내는 문자열 그대로** 서명해요 (정렬·재인코딩하지 않음).
* 서버 시각과 ±300초 넘게 차이 나면 `TIMESTAMP_SKEW`예요. 오류 응답의 `server_time`으로 보정해 다시 보내세요.
* 같은 Nonce는 10분 안에 다시 쓸 수 없어요 (`REPLAYED_REQUEST`).
::: code-group
```csharp [C#]
static string Sign(string secret, string method, string uri, string ts, string nonce, string body)
{
using var sha = SHA256.Create();
var bodyHash = Convert.ToHexString(sha.ComputeHash(Encoding.UTF8.GetBytes(body))).ToLowerInvariant();
var msg = $"{method}\n{uri}\n{ts}\n{nonce}\n{bodyHash}";
using var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
return Convert.ToBase64String(h.ComputeHash(Encoding.UTF8.GetBytes(msg)));
}
```
```js [JavaScript (Node)]
import crypto from 'node:crypto'
function sign(secret, method, uri, ts, nonce, body = '') {
const bodyHash = crypto.createHash('sha256').update(body).digest('hex')
const msg = `${method}\n${uri}\n${ts}\n${nonce}\n${bodyHash}`
return crypto.createHmac('sha256', secret).update(msg).digest('base64')
}
const body = JSON.stringify({ device_id: 'device-1234' })
const ts = String(Math.floor(Date.now() / 1000))
const nonce = crypto.randomBytes(12).toString('hex')
await fetch('https://game-api.webzenk.kr/v1/auth/guest', {
method: 'POST',
headers: {
'Content-Type': 'application/json', 'X-App-Key': APP_KEY, 'X-Timestamp': ts, 'X-Nonce': nonce,
'X-Signature': sign(APP_SECRET, 'POST', '/v1/auth/guest', ts, nonce, body),
},
body,
})
```
```php [PHP]
function sign(string $secret, string $method, string $uri, string $ts, string $nonce, string $body = ''): string
{
$msg = $method . "\n" . $uri . "\n" . $ts . "\n" . $nonce . "\n" . hash('sha256', $body);
return base64_encode(hash_hmac('sha256', $msg, $secret, true));
}
```
:::
## 유저 토큰
* 로그인하면 `access_token`(기본 1시간)과 `refresh_token`(기본 30일)을 받아요. 유저 API에는 `Authorization: Bearer `을 붙여요.
* Access Token이 만료되면 `401 AUTH_TOKEN_INVALID`예요. [`POST /v1/auth/refresh`](./auth#토큰-갱신)로 새 토큰을 받고 다시 호출하세요.
* Refresh Token은 쓸 때마다 바뀌어요. **이미 쓴 Refresh Token을 다시 쓰면** 그 유저의 모든 세션을 끊어요 (`REFRESH_TOKEN_REUSED`). 새 토큰을 꼭 저장하세요.
## 웹 규칙
* `X-App-Key`만 보내고 서명 헤더는 보내지 않아요. 게임 주소가 허용 도메인이어야 해요 (`ORIGIN_NOT_ALLOWED`, `WEB_NOT_ENABLED`).
* Google Play·App Store 결제 검증과 AppLovin 광고 세션은 웹에서 쓸 수 없어요 (`WEB_NOT_SUPPORTED`).
* CORS는 클라이언트 API에만 열려 있어요. 개발사 서버 API는 브라우저에서 호출할 수 없어요.
---
---
url: https://developers.webzenk.kr/api/format.md
---
# 요청·응답 형식
요청 본문은 JSON(`Content-Type: application/json`, UTF-8)이에요. 응답은 항상 같은 모양이에요.
::: code-group
```json [성공]
{ "ok": true, "data": { }, "server_time": 1795055466 }
```
```json [실패]
{
"ok": false,
"error": { "code": "VERSION_CONFLICT", "message": "version mismatch for 'save'", "details": { "current_version": 3 } },
"trace_id": "08ff8730afadaf78",
"server_time": 1795055466
}
```
:::
* 오류는 HTTP 상태와 \*\*`error.code`\*\*로 판단하세요. `message`는 바뀔 수 있어요. → [오류 코드](./errors)
* `server_time`은 서버 시각(epoch 초)이에요. 일일 보상처럼 기기 시계를 믿으면 안 되는 판단에 쓰세요.
* 문의할 때는 `trace_id`를 함께 보내 주세요. 응답 헤더 `X-Trace-Id`에도 있어요.
* 시각 값은 모두 \*\*epoch 초(UTC)\*\*예요.
* ID 값(`player_id`, `purchase_id`, `reward_id` 등)은 **문자열**로 다루세요.
* 요청에 `X-Request-Id`(8~64자 영숫자·`-`)를 보내면 그 값이 `trace_id`가 돼요.
---
---
url: https://developers.webzenk.kr/api/errors.md
---
# 오류 코드
오류 응답은 `{ "ok": false, "error": { "code", "message", "details"? }, "trace_id" }` 형식이에요. **`code`로 판단**하세요.
## 공통
| HTTP | code | 뜻 |
|---|---|---|
| 400 | `INVALID_PARAM` | 요청 형식이 잘못됨 (`message`에 어느 필드인지) |
| 404 | `NOT_FOUND` | 없는 리소스·경로 |
| 405 | `METHOD_NOT_ALLOWED` | HTTP 메서드가 틀림 |
| 500 | `INTERNAL` | 서버 내부 오류 — `trace_id`와 함께 문의 |
## 인증
| HTTP | code | 뜻 | 대응 |
|---|---|---|---|
| 401 | `MISSING_SIGNATURE` | 서명 헤더 없음 | X-App-Key·X-Timestamp·X-Nonce·X-Signature (웹은 Origin) |
| 401 | `INVALID_APP_KEY` | 모르는 App Key | 키 확인 |
| 401 | `INVALID_SIGNATURE` | 서명 불일치 | Secret·서명 문자열 확인 — [테스트하기](/guide/testing#서명-확인-rest-직접-호출) |
| 401 | `TIMESTAMP_SKEW` | 기기 시각이 ±300초 넘게 차이 | 응답 `server_time`으로 보정 후 재시도 |
| 401 | `REPLAYED_REQUEST` | 이미 쓴 Nonce | 요청마다 새 Nonce |
| 401 | `AUTH_REQUIRED` | 유저 토큰 없음 | 로그인 후 호출 |
| 401 | `AUTH_TOKEN_INVALID` | Access Token 만료·잘못됨 | 토큰 갱신 후 재시도 |
| 401 | `REFRESH_TOKEN_EXPIRED` · `_INVALID` · `_REVOKED` | Refresh Token 사용 불가 | 다시 로그인 |
| 401 | `REFRESH_TOKEN_REUSED` | 이미 쓴 Refresh Token — 모든 세션 종료 | 다시 로그인, 새 토큰 저장 확인 |
| 401 | `INVALID_PROVIDER_TOKEN` | Google·Apple·플랫폼 토큰 검증 실패 | 토큰 만료·클라이언트 ID 등록 확인 |
| 403 | `GAME_SUSPENDED` | 게임이 정지 상태 | 운영 담당자 문의 |
| 403 | `PLAYER_BANNED` | 제재된 유저 | 제재 안내 화면 |
| 403 | `PLAYER_DELETED` | 파기된 유저 | 새로 시작 안내 |
| 403 | `WEB_NOT_ENABLED` | 웹 접속이 꺼짐 | 허용 도메인 등록 요청 |
| 403 | `ORIGIN_NOT_ALLOWED` | 허용 도메인이 아닌 주소 | 게임 주소 등록 요청 |
| 403 | `WEB_NOT_SUPPORTED` | 웹에서 쓸 수 없는 API | 앱 전용 (스토어 결제·MAX 광고) |
## 기능
| HTTP | code | 뜻 | 대응 |
|---|---|---|---|
| 400 | `PROVIDER_NOT_CONFIGURED` | 해당 로그인·결제 연동이 설정되지 않음 | 운영 담당자에게 연동 요청 |
| 409 | `VERSION_CONFLICT` | 저장 version 불일치 | 다시 읽어 합친 뒤 저장 |
| 409 | `ALREADY_LINKED` | 다른 유저에 연결된 계정 | 그 계정으로 로그인 |
| 409 | `PROVIDER_ALREADY_LINKED` | 같은 종류 계정이 이미 연결됨 | — |
| 409 | `PURCHASE_OWNED_BY_OTHER` | 다른 유저가 등록한 영수증 | 지급하지 않음 |
| 409 | `AD_NOT_REWARDED` | 보상 확정 전 광고 세션 | 상태 확인 후 다시 |
| 413 | `VALUE_TOO_LARGE` | 저장 값 크기 초과 | 값 나누기 |
| 422 | `RECEIPT_INVALID` | 위조·취소·상품 불일치 영수증 | 지급하지 않음 |
| 422 | `RECEIPT_REVOKED` | 환불·취소된 결제 | 지급하지 않음 |
| 422 | `SCORE_OUT_OF_RANGE` | 허용 범위 밖 점수 | — |
| 422 | `STORAGE_KEY_LIMIT` | 키 개수 초과 | 키 합치기 |
| 429 | `RATE_LIMITED` | 요청 한도 초과 | `Retry-After`초 후 재시도 |
| 429 | `SUBMIT_TOO_FAST` | 점수 제출 간격 제한 | 잠시 후 제출 |
| 429 | `AD_DAILY_CAP` | 오늘 광고 보상 한도 | 광고 버튼 숨김 |
| 429 | `EVENT_QUOTA_EXCEEDED` | 오늘 이벤트 한도 초과 | 이벤트 줄이기 |
| 500 | `STORE_CONFIG_INVALID` | 스토어 연동 설정 오류 | 운영 담당자 문의 |
| 503 | `STORE_UNAVAILABLE` · `UPSTREAM_UNAVAILABLE` | 스토어·외부 서버 장애 | 스토어 완료 처리 없이 나중에 재시도 |
## SDK 전용 코드
| code | 뜻 |
|---|---|
| `NETWORK_ERROR` | 네트워크 끊김·타임아웃 (웹은 CORS 차단 포함) |
| `NOT_LOGGED_IN` | 로그인 전 호출 |
| `NOT_SUPPORTED` | 설치·설정되지 않은 기능 |
| `CANCELED` | 유저가 결제·로그인 취소 |
| `STORE_ERROR` (Unity) · `PLATFORM_ERROR` (HTML5) | 스토어·플랫폼 SDK 오류 |
---
---
url: https://developers.webzenk.kr/api/limits.md
---
# 요청 한도
| 기준 | 기본 한도 | 초과 시 |
|---|---|---|
| 로그인한 유저 1명 | 분당 300회 | `429 RATE_LIMITED` |
| 로그인 전 (같은 IP) | 분당 1,200회 (통신사 NAT 고려) | `429 RATE_LIMITED` |
| 게임 전체 | 분당 30,000회 | `429 RATE_LIMITED` |
| 이벤트 | 요청당 100건, 유저당 하루 5,000건 | `429 EVENT_QUOTA_EXCEEDED` |
| 저장 | 유저당 키 100개, 값 하나 64KB, 일괄 저장 20개 | `422 STORAGE_KEY_LIMIT` / `413 VALUE_TOO_LARGE` |
| 광고 보상 | placement별 하루 20회 | `429 AD_DAILY_CAP` |
| 랭킹 제출 | 리더보드별 제출 간격 설정 | `429 SUBMIT_TOO_FAST` |
`RATE_LIMITED`이면 응답 헤더 `Retry-After`(초)만큼 기다렸다가 다시 보내세요.
한도는 게임별로 조정할 수 있어요. 대규모 이벤트나 출시를 앞두고 있다면 웹젠케이 운영 담당자와 미리 상의하세요.
---
---
url: https://developers.webzenk.kr/api/auth.md
---
# 로그인·계정
| | 경로 | 인증 | 설명 |
|---|---|---|---|
| POST | `/v1/auth/guest` | 앱 | 게스트 로그인 |
| POST | `/v1/auth/google` | 앱 | Google / Play Games |
| POST | `/v1/auth/apple` | 앱 | Sign in with Apple |
| POST | `/v1/auth/platform/{platform}` | 앱 | HTML5 플랫폼 계정 (`samsung`) |
| POST | `/v1/auth/refresh` | 앱 | 토큰 갱신 |
| POST | `/v1/auth/link` | 유저 | 로그인 수단 연결 |
| GET | `/v1/players/me` | 유저 | 내 정보 |
| POST | `/v1/auth/logout` | 유저 | 로그아웃 |
| DELETE | `/v1/account` | 유저 | 탈퇴 요청 |
| POST | `/v1/account/restore` | 유저 | 탈퇴 철회 |
## 로그인
모든 로그인 API는 같은 응답을 돌려줘요. `device_id`는 8~128자 `[A-Za-z0-9._:-]`.
| API | 본문 |
|---|---|
| `/v1/auth/guest` | `{ "device_id": "…" }` — 같은 ID면 같은 유저 |
| `/v1/auth/google` | `{ "id_token": "…", "device_id": "…"? }` 또는 Play Games `{ "server_auth_code": "…" }` |
| `/v1/auth/apple` | `{ "identity_token": "…", "nonce": "원문"?, "device_id": "…"? }` |
| `/v1/auth/platform/samsung` | `{ "signature": "GSInstant.player.getSignatureAsync() 결과" }` |
```json
{
"player_id": "1024",
"token_type": "Bearer",
"access_token": "eyJhbGciOi…",
"expires_in": 3600,
"refresh_token": "…",
"refresh_expires_in": 2592000,
"is_new": true,
"deletion_requested_at": null
}
```
`deletion_requested_at`이 있으면 탈퇴 유예 중이에요. "탈퇴 철회" 화면을 보여 주세요.
| 오류 | 뜻 |
|---|---|
| `401 INVALID_PROVIDER_TOKEN` | 토큰 검증 실패 (만료·클라이언트 ID 미등록) |
| `400 PROVIDER_NOT_CONFIGURED` | 이 게임에 해당 로그인 연동이 없음 |
| `403 PLAYER_BANNED` / `PLAYER_DELETED` | 제재 / 파기된 유저 |
## 토큰 갱신
POST `/v1/auth/refresh` — `{ "refresh_token": "…", "device_id": "…"? }` → 로그인과 같은 응답 (새 토큰 쌍)
Refresh Token은 한 번만 쓸 수 있어요. 응답의 새 `refresh_token`을 꼭 저장하세요.
| 오류 | 대응 |
|---|---|
| `REFRESH_TOKEN_EXPIRED` · `INVALID` · `REVOKED` | 다시 로그인 |
| `REFRESH_TOKEN_REUSED` | 이미 쓴 토큰 재사용 — 탈취 의심으로 모든 세션 종료. 다시 로그인 |
## 계정 연결
POST `/v1/auth/link` — `{ "provider": "google" | "apple" | "samsung", …해당 로그인 API와 같은 필드 }` → 내 정보
`409 ALREADY_LINKED` 다른 유저에 연결된 계정 · `409 PROVIDER_ALREADY_LINKED` 같은 종류 계정이 이미 연결됨
## 내 정보
GET `/v1/players/me`
```json
{ "player_id": "1024", "status": "active", "providers": ["guest", "google"],
"created_at": 1795000000, "last_login_at": 1795055000, "deletion_requested_at": null }
```
`status`: `active` · `banned` · `delete_requested` · `deleted`
## 로그아웃
POST `/v1/auth/logout` — `{ "refresh_token": "…" }` 이 기기 세션만 종료
## 탈퇴
DELETE `/v1/account` — 모든 세션 종료, 유예 기간 후 파기
```json
{ "deletion_requested_at": 1795055466, "purge_after": 1797647466 }
```
POST `/v1/account/restore` — 유예 기간 중 철회 → 내 정보. 자세한 내용은 [개인정보·탈퇴](/guide/privacy).
---
---
url: https://developers.webzenk.kr/api/storage.md
---
# 데이터 저장
| | 경로 | 인증 | 설명 |
|---|---|---|---|
| GET | `/v1/storage` | 유저 | 내 키 전체 |
| GET | `/v1/storage/{key}` | 유저 | 값 하나 |
| PUT | `/v1/storage/{key}` | 유저 | 저장 |
| POST | `/v1/storage/batch` | 유저 | 여러 키 저장 (최대 20개, 전부 성공 또는 전부 실패) |
| DELETE | `/v1/storage/{key}` | 유저 | 삭제 |
| GET | `/v1/players/{id}/public` | 유저 | 다른 유저의 공개 키 |
키: 1~64자 `[A-Za-z0-9_.-]` · 값: JSON (기본 64KB) · 유저당 키 100개
## 읽기
GET `/v1/storage/{key}` — 없으면 `404 NOT_FOUND`
```json
{ "key": "save", "value": { "stage": 3, "items": [] }, "is_public": false, "version": 4, "updated_at": 1795055466 }
```
GET `/v1/storage` → `{ "items": [ 위와 같은 항목 … ] }`
## 저장
PUT `/v1/storage/{key}`
```json
{ "value": { "stage": 4 }, "version": 4, "is_public": false }
```
→ `{ "key": "save", "version": 5 }`
* `version`: 새 키는 `0`, 그다음은 마지막으로 읽거나 쓴 값. 다르면 `409 VERSION_CONFLICT` + `details.current_version`
* `is_public: true`면 다른 유저가 `/v1/players/{id}/public`으로 읽을 수 있어요.
POST `/v1/storage/batch` — `{ "items": [ { "key", "value", "version", "is_public"? }, … ] }` → `{ "items": [ { "key", "version" }, … ] }`
## 삭제
DELETE `/v1/storage/{key}?version=5` — `version`을 생략하면 무조건 삭제
## 오류
| 오류 | 뜻 |
|---|---|
| `409 VERSION_CONFLICT` | 다른 기기가 먼저 저장함 — 다시 읽어 합친 뒤 저장 |
| `413 VALUE_TOO_LARGE` | 값 크기 초과 |
| `422 STORAGE_KEY_LIMIT` | 키 개수 초과 |
---
---
url: https://developers.webzenk.kr/api/leaderboards.md
---
# 랭킹
| | 경로 | 인증 | 설명 |
|---|---|---|---|
| GET | `/v1/leaderboards` | 유저 | 리더보드 목록 |
| POST | `/v1/leaderboards/{code}/scores` | 유저 | 점수 제출 |
| GET | `/v1/leaderboards/{code}/top` | 유저 | 상위 순위 `?limit=100` |
| GET | `/v1/leaderboards/{code}/me` | 유저 | 내 순위와 위아래 `?around=5` |
| GET | `/v1/leaderboards/{code}/seasons/{season}` | 유저 | 끝난 시즌 결과 `?limit=&offset=` |
| GET | `/v1/leaderboards/{code}/seasons/{season}/me` | 유저 | 끝난 시즌 내 순위 |
## 목록
GET `/v1/leaderboards` → `{ "items": [ … ] }`
```json
{ "leaderboard": "weekly", "name": "주간 랭킹", "sort": "desc", "policy": "best",
"reset_cycle": "weekly", "season": 202647, "season_ends_at": 1795359600 }
```
## 점수 제출
POST `/v1/leaderboards/{code}/scores` — `{ "score": 1530, "meta": { "stage": 3 }? }`
```json
{ "leaderboard": "weekly", "season": 202647, "score": 1530, "submitted": 1530, "updated": true, "rank": 12, "total": 840 }
```
`score`는 저장된 점수예요(최고 기록 정책이면 더 낮은 점수를 내도 그대로). `updated`는 기록이 바뀌었는지예요.
## 순위 조회
GET `/v1/leaderboards/{code}/top?limit=50`
```json
{
"leaderboard": "weekly", "season": 202647, "total": 840,
"entries": [
{ "rank": 1, "player_id": "2048", "score": 98200, "achieved_at": 1795040000, "profile": { "nick": "wk" } }
]
}
```
`profile`은 그 유저가 `profile` 키로 공개 저장한 값이에요(없으면 `null`).
GET `/v1/leaderboards/{code}/me?around=5` → 목록 정보 + `me`(내 항목, 기록이 없으면 `null`) + `entries`(위아래)
## 끝난 시즌
GET `/v1/leaderboards/{code}/seasons/{season}` → `{ "total_ranked", "entries": [ … ] }` — 진행 중인 시즌이면 `404`
GET `/v1/leaderboards/{code}/seasons/{season}/me` → `{ "me": { … } | null }`
시즌 번호: 일간 `YYYYMMDD` · 주간 `YYYYWW`(ISO) · 월간 `YYYYMM` · 수동·계속은 1부터
## 오류
| 오류 | 뜻 |
|---|---|
| `404 NOT_FOUND` | 없는 리더보드 / 진행 중 시즌 조회 |
| `422 SCORE_OUT_OF_RANGE` | 허용 범위 밖 점수 |
| `429 SUBMIT_TOO_FAST` | 제출 간격 제한 |
---
---
url: https://developers.webzenk.kr/api/events.md
---
# 이벤트
| | 경로 | 인증 | 설명 |
|---|---|---|---|
| POST | `/v1/events` | 유저 | 이벤트 전송 (최대 100건) |
```json
{
"platform": "android",
"app_version": "1.2.0",
"events": [
{ "name": "stage_clear", "ts": 1795055466123, "props": { "stage": 12 } },
{ "name": "tutorial_done" }
]
}
```
| 필드 | 규칙 |
|---|---|
| `platform` | 선택. 소문자 2~16자 (`android`, `ios`, `web`, `samsung` …) |
| `app_version` | 선택. 32자 이내 |
| `events[].name` | 소문자로 시작하는 `[a-z0-9_]` 64자 |
| `events[].ts` | 선택. epoch 초 또는 밀리초. 생략하거나 7일보다 오래됐거나 미래면 받은 시각 |
| `events[].props` | 선택. 4KB 이내 객체 |
* 하나라도 형식이 틀리면 전체가 `400`이에요(일부만 저장되지 않아요). 오프라인 큐에서 그대로 재전송하면 돼요.
* 유저당 하루 5,000건을 넘으면 `429 EVENT_QUOTA_EXCEEDED`예요.
* 집계 결과는 [개발사 서버 API](./server#지표)의 `/v1/server/metrics/events`로 조회해요.
---
---
url: https://developers.webzenk.kr/api/iap.md
---
# 결제
| | 경로 | 인증 | 설명 |
|---|---|---|---|
| POST | `/v1/iap/verify` | 유저 | 영수증 검증 → 결제 기록 |
| POST | `/v1/iap/consume` | 유저 | 지급 완료 보고 |
| GET | `/v1/iap/unconsumed` | 유저 | 검증됐지만 지급 보고가 없는 결제 — **로그인 직후 호출** |
| GET | `/v1/iap/history` | 유저 | 결제 내역 `?limit=50&before_id=` |
흐름과 상태는 [결제 검증 가이드](/guide/iap)를 먼저 보세요.
## 영수증 검증
POST `/v1/iap/verify`
::: code-group
```json [Google Play]
{ "store": "googleplay", "product_id": "gem_100", "purchase_token": "…",
"price_micros": 1200000000, "currency": "KRW" }
```
```json [App Store]
{ "store": "appstore", "product_id": "gem_100", "transaction_id": "2000000812345678" }
```
```json [삼성 Instant Plays]
{ "store": "samsung", "product_id": "gem_100", "signed_receipt": "PurchaseItem.signedPurchaseReceipt" }
```
:::
Google Play는 스토어 응답에 가격이 없어서 앱의 표시 가격(`price_micros` = 가격 × 1,000,000, `currency`)을 매출 지표용으로 함께 보내요.
```json
{
"purchase_id": "5012", "store": "googleplay", "product_id": "gem_100", "quantity": 1,
"status": "verified", "is_sandbox": false, "order_id": "GPA.3312-…",
"platform_purchase_id": null,
"purchased_at": 1795055000, "verified_at": 1795055003, "consumed_at": null, "refunded_at": null,
"already_processed": false
}
```
| `status` | 할 일 |
|---|---|
| `verified` | 지급 → `/v1/iap/consume` |
| `consumed` | 이미 지급 완료 — 스토어 완료 처리만 |
| `pending` | Google 보류 결제 — 지급하지 말고 나중에 다시 verify |
* 같은 영수증을 다시 보내면 같은 `purchase_id`와 `already_processed: true`가 와요.
* `platform_purchase_id`: 플랫폼 결제(삼성)에서 지급 후 플랫폼 소진에 쓰는 ID.
## 지급 완료 보고
POST `/v1/iap/consume` — `{ "purchase_ids": ["5012"] }` (최대 50건, 다시 보내도 안전)
```json
{ "items": [ { "purchase_id": "5012", "status": "consumed" } ] }
```
## 미지급 결제
GET `/v1/iap/unconsumed` → `{ "items": [ 결제 기록 … ] }` — `verified`인 건을 지급하고 consume 하세요.
## 오류
| 오류 | 뜻 | 대응 |
|---|---|---|
| `409 PURCHASE_OWNED_BY_OTHER` | 다른 유저가 등록한 영수증 | 지급하지 않음 |
| `422 RECEIPT_INVALID` | 위조·취소·상품 불일치 | 지급하지 않음 |
| `422 RECEIPT_REVOKED` | 환불·취소된 결제 | 지급하지 않음 |
| `503 STORE_UNAVAILABLE` | 스토어 장애 | 스토어 완료 처리 없이 나중에 재시도 |
| `400 PROVIDER_NOT_CONFIGURED` | 이 게임에 스토어 연동 없음 | 운영 담당자 문의 |
| `403 WEB_NOT_SUPPORTED` | 웹에서 Google Play·App Store 검증 | 앱에서만 |
---
---
url: https://developers.webzenk.kr/api/ads.md
---
# 보상형 광고
| | 경로 | 인증 | 설명 |
|---|---|---|---|
| POST | `/v1/ads/sessions` | 유저 | 보상 세션 발급 |
| GET | `/v1/ads/sessions/{id}` | 유저 | 세션 상태 |
| POST | `/v1/ads/sessions/{id}/claim` | 유저 | 지급 완료 보고 |
| GET | `/v1/ads/unclaimed` | 유저 | 콜백은 왔지만 지급 보고가 없는 보상 — **로그인 직후 호출** |
| POST | `/v1/ads/claim` | 유저 | 위 목록의 지급 완료 보고 |
흐름과 MAX 설정은 [보상형 광고 가이드](/guide/ads)를 먼저 보세요. 웹에서는 쓸 수 없어요(`WEB_NOT_SUPPORTED`).
## 세션 발급
POST `/v1/ads/sessions` — `{ "placement": "daily_chest" }` (생략 시 `default`, 1~64자 `[A-Za-z0-9_.-]`)
```json
{ "session_id": "9f1c…", "placement": "daily_chest", "custom_data": "9f1c…", "expires_in": 3600, "remaining_today": 19 }
```
`custom_data`를 그대로 `MaxSdk.ShowRewardedAd(adUnitId, placement, customData)`에 넣어요.
하루 한도를 넘었으면 `429 AD_DAILY_CAP` — 광고를 띄우지 마세요.
## 상태 확인
GET `/v1/ads/sessions/{id}`
```json
{ "reward_id": "771", "session_id": "9f1c…", "placement": "daily_chest", "status": "rewarded",
"reject_reason": null, "amount": "10", "currency": "gold", "rewarded_at": 1795055500, "claimed_at": null }
```
`status`: `pending` · `rewarded` · `claimed` · `rejected` · `expired`
## 지급 완료 보고
POST `/v1/ads/sessions/{id}/claim` → 세션 상태 (`claimed`). `rewarded`가 아니면 `409 AD_NOT_REWARDED`.
GET `/v1/ads/unclaimed` → `{ "items": [ 보상 … ] }`
POST `/v1/ads/claim` — `{ "reward_ids": ["771"] }` → `{ "items": [ { "reward_id": "771", "status": "claimed" } ] }`
---
---
url: https://developers.webzenk.kr/api/server.md
---
# 개발사 서버 API
개발사 서버에서 **Server Secret**으로 서명해 호출해요. 서명 방식은 [앱 서명](./#서명-만들기)과 같고 키만 달라요. App Secret으로는 호출할 수 없고, 브라우저(CORS)에서도 호출할 수 없어요.
| | 경로 | 설명 |
|---|---|---|
| GET | `/v1/server/metrics/daily` | 일별 KPI |
| GET | `/v1/server/metrics/retention` | 리텐션 |
| GET | `/v1/server/metrics/events` | 이벤트 일 집계 |
| GET | `/v1/server/purchases` | 상태별 결제 목록 (환불 회수) |
| GET | `/v1/server/players/{id}` | 유저 조회 |
| POST | `/v1/server/players/{id}/ban` | 제재 |
| POST | `/v1/server/players/{id}/unban` | 제재 해제 |
## 지표
모든 지표 API는 `?from=YYYY-MM-DD&to=YYYY-MM-DD` (기본 최근 7일, 최대 92일, 게임 시간대 날짜)를 받고 `{ "from", "to", "items": [ … ] }`를 돌려줘요.
GET `/v1/server/metrics/daily`
```json
{
"date": "2026-11-18", "dau": 1520, "nru": 210, "purchases": 48, "payers": 41, "pur": 0.027,
"refunds": 1, "ad_rewards": 930, "ad_viewers": 402, "events": 18820,
"revenue": [ { "currency": "KRW", "gross": 612000, "refund": 12000, "net": 600000, "purchases": 47, "arpdau": 394.7368 } ],
"updated_at": 1795055466
}
```
* `pur` 결제율(결제자/DAU), `revenue`는 **통화별** (환산 안 함), 테스트 결제 제외. Google Play 금액은 앱이 보낸 표시 가격 기준.
* 매시간 오늘·어제를 다시 계산해요(최대 1시간 지연).
GET `/v1/server/metrics/retention` → `{ "cohort": "2026-11-01", "cohort_size": 210, "d1": 0.41, "d3": 0.27, "d7": 0.18, … }`
GET `/v1/server/metrics/events?name=stage_clear` → `{ "date", "name", "count", "users" }` (`name` 생략 시 전체)
## 결제 목록 (환불 회수)
GET `/v1/server/purchases?status=refunded&since=&limit=100`
```json
{ "items": [ { "purchase_id": "5012", "player_id": "1024", "product_id": "gem_100", "status": "refunded",
"refunded_at": 1795059000, "refund_reason": "…", "…": "결제 기록 필드" } ],
"next_since": 1795059000 }
```
* `status`: `refunded`(기본) · `verified` · `consumed` · `pending`
* 다음 호출은 `since=next_since`. 경계 건이 다시 올 수 있으니 `purchase_id`로 중복을 거르세요. → [환불 처리](/guide/refunds)
## 유저
GET `/v1/server/players/{id}` → [내 정보](./auth#내-정보)와 같은 형식
POST `/v1/server/players/{id}/ban` — `{ "reason": "결제 어뷰징" }` → 로그인·토큰 갱신 차단 + 세션 종료 (이미 받은 Access Token은 최대 1시간 유효)
POST `/v1/server/players/{id}/unban` → 제재 해제
---
---
url: https://developers.webzenk.kr/release-notes.md
---
# 릴리즈 노트
서버 API·SDK·문서의 변경 사항이에요.
가이드·SDK·API·릴리즈 노트를 한곳에서 볼 수 있어요.
* 모든 문서를 Markdown으로 제공해요. AI 도구에는 [`/llms.txt`](/llms.txt) · [`/llms-full.txt`](/llms-full.txt)를 넣어 주세요.
* 페이지마다 **페이지 복사** 버튼으로 내용을 바로 가져갈 수 있어요.
`com.webzenk.wk-gameapi` — Unity 2022.3 LTS 이상, Android·iOS
* 로그인(게스트·Google·Play Games·Apple), 저장, 랭킹, 이벤트
* **결제**: Unity IAP 4.8+ 설치 시 자동 연결. 서버 검증 → 지급 → 완료 보고 → 스토어 완료, 재시작 시 자동 복구
* **보상형 광고**: AppLovin MAX 샘플 어댑터, 서버 콜백 확인 후 지급, 늦게 온 콜백 자동 지급
* 외부 의존 없음 (자체 JSON), 기기 시계 오차 자동 보정
* WebGL은 App Secret 없이 웹 모드
[시작하기](/sdk/unity/) · [다운로드](/sdk/download)
`@webzenk/wk-gameapi` — TypeScript / JavaScript
* 웹사이트(`WKWebPlatform`)와 **삼성 Galaxy Store Instant Plays**(`WKSamsungPlatform`) 지원
* 삼성 계정 로그인, 삼성 IAP 결제 서버 검증, Samsung Ads + AdMob 광고
* 공개 이름은 모두 `WK`로 시작해요 — 전역 `WKGameApi` 하나
[시작하기](/sdk/html5/) · [다운로드](/sdk/download)
### 웹 클라이언트
브라우저에서는 App Secret 없이 **App Key + 허용 도메인**으로 접속해요. 운영 담당자에게 게임 주소를 등록해 달라고 요청하세요.
* 새 오류 코드: `WEB_NOT_ENABLED`, `ORIGIN_NOT_ALLOWED`, `WEB_NOT_SUPPORTED`
### 삼성 Instant Plays
* `POST /v1/auth/platform/samsung` — 삼성 계정 로그인
* `POST /v1/iap/verify` `store: "samsung"` — 삼성 결제 영수증 검증
### 저장
* 빈 객체 `{}`가 빈 배열 `[]`로 바뀌어 돌아오던 문제를 고쳤어요.
### 탈퇴
* 유예 기간(기본 30일)이 지난 탈퇴 계정을 자동으로 파기해요. → [개인정보·탈퇴](/guide/privacy)
- **로그인**: 게스트, Google, Play Games, Apple, 계정 연결, 탈퇴·철회
- **저장**: 유저별 JSON 키-값, version 충돌 감지, 일괄 저장, 공개 데이터
- **랭킹**: 일간·주간·월간·수동 시즌, 최고·최신·누적, 지난 시즌 결과
- **지표**: DAU·신규·결제·통화별 매출·리텐션, 커스텀 이벤트
- **결제 검증**: Google Play·App Store, 환불 알림 반영
- **보상형 광고**: AppLovin MAX 서버 콜백
- **개발사 서버 API**: 지표 조회, 환불 목록, 유저 조회·제재