--- 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**: 지표 조회, 환불 목록, 유저 조회·제재