PATCH /session/heartbeat

게임 세션 하트비트를 전송하여 세션을 유지합니다

PATCH /v1/game/session/heartbeat

게임 세션이 활성 상태임을 서버에 알립니다. 2분(120초) 간격으로 호출해야 합니다.

하트비트를 보내지 않으면 Redis TTL(4분) 만료로 세션이 자동 삭제됩니다.

​

요청

​

Headers

X-Api-Key · string · 필수

게임별 API Key.

Content-Type · string · 필수

application/json

​

Body

game_session_id · string · 필수

verify에서 반환된 게임 세션 ID.

provider_user_id · string · 필수

Roblox Player UserId (문자열).

{
  "game_session_id": "gs_550e8400-e29b-41d4-a716-446655440000",
  "provider_user_id": "123456789"
}

​

응답

​

성공 — 200

{
  "success": true,
  "request_id": "req_abc123",
  "data": {
    "result": "OK",
    "next_heartbeat_in": 120,
    "play_duration_sec": 1800
  }
}

result · string · 필수

세션 상태. OK, CHARGE_EXHAUSTED, SESSION_REPLACED 중 하나.

next_heartbeat_in · integer · 필수

다음 하트비트까지 권장 대기 시간 (초). 기본 120.

play_duration_sec · integer · 필수

서버 기준 누적 플레이 시간 (초).

​

result 값

result	설명	처리
OK	정상	next_heartbeat_in 후 다음 하트비트 전송
CHARGE_EXHAUSTED	G-coin 소진	유저에게 안내. 서버 2분 유예 후 자동 종료
SESSION_REPLACED	같은 PC에서 다른 게임 세션이 시작됨	하트비트 중지. 세션 종료 API를 호출하지 마세요 — 서버에서 이미 종료 처리됨

런처 하트비트 타임아웃: 게임 서버 하트비트를 처리할 때 서버는 런처의 하트비트도 함께 확인합니다. 런처가 4분 이상 하트비트를 보내지 않으면 서버는 런처가 죽은 것으로 판단하고 게임 세션을 종료합니다. 이 경우 하트비트 응답으로 HTTP 410 SESSION_ENDED가 반환됩니다. PlayWave 런처가 크래시되거나 강제 종료된 경우에 발생할 수 있습니다.

​

에러

HTTP	코드	설명	처리
404	SESSION_NOT_FOUND	세션 없음 (만료/삭제)	하트비트 중지, 유저 킥
410	SESSION_ENDED	이미 종료된 세션	하트비트 중지, 유저 킥
410	SESSION_ENDING	종료 진행 중	하트비트 중지, 유저 킥

​

Luau 예제

local function sendHeartbeat(gameSessionId, providerUserId)
    local success, response = pcall(function()
        return HttpService:RequestAsync({
            Url = API_URL .. "/game/session/heartbeat",
            Method = "PATCH",
            Headers = {
                ["X-Api-Key"] = API_KEY,
                ["Content-Type"] = "application/json",
            },
            Body = HttpService:JSONEncode({
                game_session_id = gameSessionId,
                provider_user_id = providerUserId,
            }),
        })
    end)

    if not success then
        warn("[Playwave] Heartbeat failed:", response)
        return nil, "NETWORK_ERROR"
    end

    if response.StatusCode == 404 or response.StatusCode == 410 then
        return nil, "SESSION_LOST"
    end

    local body = HttpService:JSONDecode(response.Body)
    return body.data, nil
end