REPLAY HOST / SHARE & EMBED

한 번 등록하면 모든 게임이 같은 URL 규칙을 씁니다.

replay.koiscore.com은 포털과 분리된 공유·embed 전용 호스트입니다. 게임 등록 후 리플레이 호스트만 켜면 catalog lookup → runtime/API proxy가 자동으로 연결됩니다.

OVERVIEW

플랫폼이 제공하는 것

replay.koiscore.com DNS·TLS·gateway (게임 EC2 IP 직결 ❌)
GET /{gameId} + static → catalog runtimeUrl reverse proxy
GET|POST /api/replays/* → 게임 replay API origin proxy
Content-Security-Policy: frame-ancestors * — 외부 사이트 embed 허용
포털 embed=koiscore-portal handshake 불필요

공개 카탈로그: /api/public/replay-games · 계약 JSON: contracts/platform/replay-service.v1.json

URL / STANDARD

공유 URL 규약

https://replay.koiscore.com/{gameId}?replay={id}
https://replay.koiscore.com/{gameId}?replay={id}&from={n}&to={n}   // optional clip

replay query 필수
from / to optional (구간 클립)
포털 URL(koiscore.com/beta/game/...)과 분리 — 공유·embed는 replay 호스트 사용

게임 등록 (한 번만)

게임 등록 콘솔에서 draft를 만듭니다. runtimeUrl이 HTTPS로 등록되어 있어야 합니다.
게임 카드에서 리플레이 호스트 등록을 켭니다 (replay_enabled=1).
즉시 https://replay.koiscore.com/{gameId}?replay=... 경로가 활성화됩니다. 게임별 nginx/DNS 설정은 필요 없습니다.

PATCH /api/developers/games/{gameId}
{ "action": "set_replay", "replayEnabled": true }

// API origin이 runtime과 다를 때만 (optional)
{
  "action": "set_replay",
  "replayEnabled": true,
  "replayApiOrigin": "https://api.example.com"
}

MCP: update_game_draft에 replayEnabled, replayApiOrigin 필드를 넣거나 list_replay_games / build_replay_share_url 도구를 사용합니다.

RUNTIME / API

게임팀 구현 체크리스트

영역	요구사항
Runtime	`?replay={id}` (+ optional `from`/`to`) query를 읽어 리플레이 모드 진입. 포털 shell 없이 standalone viewer.
API	게임 서버에 `GET\|POST /api/replays/{id}` 구현. 클라이언트는 상대 경로 `/api/replays/...` 호출 권장 (replay 호스트 same-origin proxy).
Assets	번들은 root-relative path 사용 (`/assets/`, `./assets/`). replay gateway가 URL rewrite.
Engagement	(선택) `/api/replays/{id}/engagement` — 조회·공유 이벤트

API는 replay 페이지 로드 후 cookie/referer로 game context가 잡힙니다. 페이지 진입 없이 API만 단독 호출하는 클라이언트는 피하세요.

DEV / PROD

환경

env	replay host	upstream
prod	`replay.koiscore.com`	registry `runtimeUrl` (prod)
dev	`replay.dev.koiscore.com`	dev/sandbox `runtimeUrl`
local	`replay.localhost:9301`	로컬 registry 또는 tunnel URL

TEST

연동 확인

# 등록된 게임 목록
curl https://koiscore.com/api/public/replay-games

# runtime proxy
curl -I 'https://replay.koiscore.com/your-game?replay=TEST_ID'

# replay API (페이지 로드 후 same-origin)
curl 'https://replay.koiscore.com/api/replays/TEST_ID' \
  -H 'Referer: https://replay.koiscore.com/your-game?replay=TEST_ID'

UX / PORTAL

포털 연동 (선택)

리플레이 종료 CTA → https://koiscore.com/beta/game/{gameId}/{locale}
포털 “리플레이 보기” 링크도 replay URL 사용 (포털 페이지 embed 불필요)