배포하고, 베타로 확인하고, 출시하세요.

01 / RESPONSIBILITY

게임 배포와 포털 공개는 별도 단계입니다

KOISCORE에 게임을 “올린다”는 말은 두 가지 의미가 섞여 있습니다. 첫째, 개발사가 자기 서버·CDN·호스팅에 HTML5 게임 빌드를 HTTPS로 배포하는 것. 둘째, KOISCORE 개발자 콘솔에 그 HTTPS 주소를 등록하고 포털 플레이어·로그인·젬·라운지와 연결하는 것입니다. 플랫폼은 게임 소스 저장소를 가져가거나 대신 빌드하지 않습니다. Unity·Godot·Pixi·자체 엔진 어디에서 만들었든, 브라우저가 직접 열 수 있는 공개 URL을 개발사가 운영·장애 대응·롤백까지 책임져야 합니다.

아래 표는 단계별로 “누가 무엇을 소유하는지”를 정리한 것입니다. 검수 미팅에서 자주 나오는 오해 — “KOISCORE에 등록했으니 배포도 끝난 것 아닌가?” — 를 미리 풀어 두려면 이 구분을 팀 wiki에도 그대로 적어 두는 편이 좋습니다. 특히 베타 단계는 정식 포털 목록에 안 보이더라도 실제 결제·identity·광고 경로는 운영과 동일하므로, 테스트용 더미 API가 아닌 승인된 계약대로 붙여야 합니다.

02 / RUNTIME DEPLOY

게임 런타임을 먼저 배포합니다

베타·정식 출시 모두 “등록할 runtimeUrl”이 먼저 살아 있어야 시작됩니다. 로컬 localhost 주소는 KOISCORE 콘솔 등록 필드에 넣을 수 없고, 샌드박스·Quick Tunnel로만 미리볼 수 있습니다. 프로덕션 배포 시에는 HTML 진입점, JS/WASM 번들, 이미지·오디오, Service Worker(쓰는 경우)가 모두 HTTPS에서 200으로 응답하는지 새 시크릿 창에서 직접 확인하세요. KOISCORE iframe 안에서만 동작하고 단독 탭에서는 깨지는 게임은 검수에서 반려됩니다.

iframe 임베드를 지원하려면 응답 헤더와 postMessage 수신 정책을 함께 맞춰야 합니다. X-Frame-Options: DENY 또는 잘못된 CSP frame-ancestors가 걸려 있으면 포털에서 하얀 화면만 보입니다. 게임 쪽 message listener는 DOMContentLoaded보다 먼저 등록하고, https://koiscore.com origin과 event.source === window.parent를 검증한 뒤 koiscore.portal.v1 protocol만 처리하세요. 아래 예시 URL 패턴은 “릴리즈마다 내용이 바뀌지 않는 immutable URL”을 권장하는 전형적인 형태입니다.

1. 원본 게임 프로젝트에서 테스트와 프로덕션 빌드를 실행합니다.
2. HTML, JavaScript, WASM, 이미지와 사운드를 개발자 소유 HTTPS 호스트에 배포합니다.
3. 배포 주소를 새 브라우저에서 직접 열어 오류와 누락 자산이 없는지 확인합니다.
4. KOISCORE의 iframe을 허용하고 https://koiscore.com의 postMessage만 신뢰합니다.
5. 모바일과 데스크톱에서 문서 스크롤 없이 iframe의 실제 너비·높이를 채웁니다.

# 권장 예시: 릴리즈마다 내용이 바뀌지 않는 URL
https://games.example.com/studio-puzzle/releases/2026-08-13/

# KOISCORE 등록에 입력할 값
gameId: studio-puzzle
runtimeUrl: https://games.example.com/studio-puzzle/releases/2026-08-13/

위 코드 블록에서 주의할 점은 “같은 경로에 덮어쓰기 배포”입니다. https://games.example.com/studio-puzzle/ 하나만 쓰면 베타 검수 중인 빌드와 현재 라이브 빌드가 뒤섞입니다. 날짜· semver· git SHA 폴더를 새 URL로 올리고, KOISCORE에 전환 요청할 때만 runtimeUrl을 바꾸면 롤백이 한 번의 DNS/CDN 설정 변경으로 끝납니다.

03 / REGISTER

개발자 콘솔에 게임 초안을 등록합니다

HTTPS 런타임이 준비됐다면 게임 등록 콘솔에서 Google 로그인 → 개발자 가입 → 초안 등록 순으로 진행합니다. gameId는 kebab-case로 한 번 정하면 바꾸기 어렵고, identity·영수증 SKU·머천트 링크·베타 URL path가 모두 이 id에 묶입니다. 제목(ko/en/ja), 장르, 정사각형 썸네일, desktop/mobile aspect ratio는 포털 카드·SEO·가이드 페이지에 그대로 노출되므로 등록 직후부터 채워 두는 것이 좋습니다.

“등록과 동시에 베타 테스트 URL 활성화” 옵션을 켜면 draft 상태에서도 /beta/game/{gameId} 주소가 바로 열립니다. 끈 상태로 등록했다면 게임 카드에서 나중에 베타 on/off 할 수 있습니다. 어떤 경우든 등록만으로 정식 포털 타일에 노출되거나 live 전환되지는 않습니다. 퍼스트파티(KOISCORE 내부) 계정은 allowlist로 표시만 다를 뿐, 연동·검수 절차는 외부 퍼블리셔와 동일합니다.

1. 게임 등록 콘솔에서 Google 로그인 후 개발자 가입을 완료합니다.
2. 고정 게임 ID, 3개 언어 제목, 카테고리, 런타임 URL, 대표 이미지와 화면 비율을 입력합니다.
3. 바로 베타를 시작하려면 등록과 동시에 베타 테스트 URL 활성화를 선택합니다.
4. 등록 후 내 회사 게임 카드에서 베타를 켜거나 끌 수 있습니다.

게임은 로그인한 개발자 계정 소유로 draft 상태에 등록됩니다. 등록만으로 정식 포털에 공개되거나 자동 출시되지 않습니다.

04 / PRIVATE-LISTED BETA

베타 URL을 발급하고 공유합니다

베타 배포를 지원하려면 콘솔 게임 카드에서 베타 스위치를 켠 뒤 표시되는 URL을 복사해 QA·퍼블리셔·친구 테스터에게 공유하면 됩니다. 이 주소는 “비밀 토큰 URL”이 아니라 링크를 아는 사람이 누구나 열 수 있는 오픈 베타 페이지입니다. 따라서 미공개 스토리 스포일러, 관리자 API 키, staging DB 접속 정보가 들어간 빌드는 올리지 마세요. 베타는 정식 포털 홈의 게임 그리드·추천 레일·Discover에는 나타나지 않지만, KOISCORE 플레이어 셸·identity·젬·광고·라운지는 운영과 같은 코드 경로를 탑니다.

기본 공유 URL(/beta/game/{gameId})은 방문자 브라우저 언어를 보고 등록된 ko/ja/en 중 하나로 redirect 합니다. 특정 locale UI를 고정하고 싶으면 아래처럼 path 끝에 언어 코드를 붙이세요. iframe embed, postMessage, portal:init 필드는 정식 포털과 동일 계약입니다. 베타 페이지 자체는 Google 색인 대상이 아닙니다(noindex, sitemap 제외). 검색 유입용 설명글은 /games/guide/{gameId}/{locale} 가이드 페이지와 개발자 문서에 두는 것을 권장합니다.

# 기본 공유 URL: 브라우저 언어 자동 선택
https://koiscore.com/beta/game/{gameId}

# 언어 고정 URL
https://koiscore.com/beta/game/{gameId}/ko
https://koiscore.com/beta/game/{gameId}/en
https://koiscore.com/beta/game/{gameId}/ja

• 베타 게임은 정식 포털 게임 목록, 사이트맵과 검색엔진 색인에서 제외됩니다. 플레이 UI는 iframe 위주이므로 SEO·AdSense용 본문은 게임 가이드 URL에 작성하세요.
• 정식 포털과 동일한 런타임·브릿지·게임별 identity·공용 젬·광고 경로로 실제 시스템을 검수합니다.
• 베타를 끄면 해당 베타 주소는 더 이상 게임을 제공하지 않습니다.
• 등록한 지원 언어 주소만 열 수 있습니다.
• 브라우저 언어를 지원하지 않으면 등록된 언어 중 한국어, 영어, 일본어 순으로 선택합니다.

QA팀에게 URL만 던져 주기 전에, 베타 페이지가 noindex임을 알리고 “검색에 뜨는지”가 아니라 “포털 계약이 맞는지”를 보라고 안내하세요. 베타 URL을 SNS에 공개해도 크롤러가 본문 가치를 높게 평가하지 않도록 robots·meta는 플랫폼이 관리합니다. 반대로 가이드·개발자 문서 URL은 index 대상이므로, 출시 전에 description·FAQ를 채워 두면 Search Console에서 자연 유입이 붙기 시작합니다.

05 / BETA QA

정식 검수 전에 확인할 항목

베타 URL로 “한번 돌려봤다”와 “출시 검수를 통과할 수 있다”는 다릅니다. KOISCORE 검수는 재미보다 플레이어 셸·브릿지·경제·프레임 정책 준수에 가깝습니다. 아래 체크리스트는 운영팀이 실제로 여는 뷰포트와 시나리오를 그대로 옮긴 것입니다. 가능하면 Android Chrome·iOS Safari·데스크톱 Chrome 세 종류에서, 게스트와 Google 로그인 계정을 각각 한 번씩 돌리세요. 문제가 생기면 Network 탭에서 koiscore.com API와 게임 origin API를 분리해 기록해 두면 반려 사유 대응이 빨라집니다.

베타 QA를 로컬에서 더 빠르게 반복하려면 플레이어 샌드박스에서 먼저 iframe·postMessage·테스트 identity를 확인한 뒤, immutable HTTPS URL을 올리고 베타 URL로 최종 확인하는 순서를 권장합니다. 샌드박스 데이터는 운영 DB로 승격되지 않으므로, 젬·랭킹·결제 숫자는 베타에서 다시 한 번 확인해야 합니다.

1. 390×844, 360×800, 1366×768, 1920×1080에서 게임 화면이 잘리거나 내부 스크롤이 생기지 않는지 확인합니다.
2. 게임 로딩, 첫 입력, 음소거, 전체화면, 가로·세로 전환과 재진입을 확인합니다.
3. Google 로그인 사용자와 게스트가 섞이지 않고 게임별 playerId로 저장되는지 확인합니다.
4. 젬 잔액, 상품 가격, 구매 영수증, 중복 요청 방지와 실제 게임 아이템 지급을 모든 상품에서 확인합니다.
5. 게임 라운지, QA·피드백, 랭킹, 저장과 복귀가 해당 게임 ID에만 연결되는지 확인합니다.
6. 직접 런타임 오류와 KOISCORE 플레이어 오류를 구분할 수 있도록 콘솔·네트워크 기록을 남깁니다.

06 / REVIEW & LIVE

검수 요청 후 정식 공개합니다

베타 QA가 끝나면 콘솔 게임 카드에서 검수 요청을 눌러 상태를 review로 바꿉니다. 이 시점부터 KOISCORE는 등록 매니페스트, runtimeUrl 응답, 모바일·데스크톱 캡처, portal:init·identity·영수증·라운지 연동을 사람과 자동 검사로 확인합니다. 반려되면 사유에 맞춰 새 immutable URL에 수정 빌드를 올리고 다시 요청합니다. 승인되어도 개발자가 직접 “출시” 버튼을 누르는 구조가 아니며, 운영자가 live 전환 후에야 포털 타일·sitemap·공개 API 카탈로그에 노출됩니다.

현재 콘솔에서는 등록 후 runtimeUrl 수정과 live 전환을 퍼블리셔가 직접 할 수 없습니다. URL 교체·긴급 롤백·점검 모드 전환은 운영 티켓으로 요청하고, 기존 live URL은 새 URL 검증이 끝날 때까지 유지됩니다. 이 정책은 잘못된 URL 입력으로 전체 플레이어 트래픽이 깨지는 사고를 막기 위함입니다.

1. 베타 검수를 마친 뒤 게임 카드에서 검수 요청을 누릅니다.
2. 상태가 review로 바뀌면 KOISCORE가 등록 정보, 런타임, 화면, 브릿지와 경제 기능을 확인합니다.
3. 반려되면 수정한 새 불변 릴리즈를 준비하고 다시 검수합니다.
4. 승인 후 운영자가 live로 전환해야 정식 포털에 노출됩니다.

07 / UPDATE & ROLLBACK

출시 후 업데이트도 같은 순서로 진행합니다

live 이후 업데이트도 “덮어쓰기 배포 → 끝”이 아닙니다. 현재 live immutable URL은 그대로 두고, 새 폴더/버전 URL에 다음 빌드를 올린 뒤 베타 URL 또는 운영자 지정 스테이징에서 회귀 테스트 → 검수 → URL 전환 순서를 반복합니다. 문제가 생기면 직전에 정상 동작하던 URL로만 되돌립니다. CDN 캐시 purge만으로는 JS 해시가 바뀐 번들 롤백이 안 되는 경우가 많으므로, URL 단위 롤백을 기본 전략으로 두세요.

웹 runtimeUrl 변경은 Apps in Toss 미니앱, Google Play WebView 래퍼, itch.io 페이지를 자동으로 갱신하지 않습니다. 채널마다 별도 빌드·스토어 제출·롤백 기록이 필요합니다. KOISCORE 릴리즈 에셋 API로 스토어 메타데이터를 관리하더라도, 실제 스토어 review는 각 플랫폼 정책을 따릅니다.

1. 현재 라이브 릴리즈를 그대로 보존합니다.
2. 새 버전을 별도 URL에 배포하고 베타에서 회귀 테스트합니다.
3. 검수 승인 후 새 URL로 전환하고, 로그인·젬·저장·게임 시작을 라이브에서 확인합니다.
4. 문제가 있으면 같은 플랫폼의 직전 정상 릴리즈 URL로만 되돌립니다.

웹 업데이트가 Apps in Toss, 스토어 앱 또는 itch.io 산출물을 자동으로 바꾸지는 않습니다. 각 플랫폼은 별도 빌드·검수·배포 기록과 롤백 단위를 사용해야 합니다.