> ## Documentation Index
> Fetch the complete documentation index at: https://playwave.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> PlayWave Roblox 연동 시 자주 묻는 질문

## 설정 관련

<AccordionGroup>
  <Accordion title="&#x22;HttpService is not allowed to send requests&#x22; 에러가 발생합니다">
    Roblox Studio → Game Settings → Security → **Allow HTTP Requests**를 활성화하세요.
  </Accordion>

  <Accordion title="API Key는 어디서 발급받나요?">
    PlayWave 관리자 콘솔에서 게임별로 발급받습니다. PlayWave 서비스 운영 담당자에게 발급을 요청하세요.
  </Accordion>

  <Accordion title="테스트 환경과 프로덕션 환경의 API URL이 다른가요?">
    | 환경       | URL                                   | 상태    |
    | -------- | ------------------------------------- | ----- |
    | **Dev**  | `https://wave-api.playwave.dev/v1`    | 사용 가능 |
    | **QA**   | `https://wave-api-qa.playwave.dev/v1` | 준비 중  |
    | **Live** | `https://wave-api.playwave.io/v1`     | 준비 중  |

    API Key도 환경별로 별도 발급됩니다.
  </Accordion>
</AccordionGroup>

## 세션 관련

<AccordionGroup>
  <Accordion title="PlayWave 런처 없이 접속한 유저는 어떻게 되나요?">
    `LaunchData`가 비어있으므로 OTT 추출이 `nil`을 반환합니다. 이는 정상 동작이며, 해당 유저에게는 PC방 혜택을 부여하지 않으면 됩니다. 일반 플레이에는 영향이 없습니다.
  </Accordion>

  <Accordion title="OTT_EXPIRED가 계속 발생합니다">
    OTT는 런처에서 발급된 후 **1분 내에** verify를 호출해야 합니다. 게임 로딩이 오래 걸리는 경우 `PlayerAdded` 이벤트에서 즉시 verify를 호출하고 있는지 확인하세요.
  </Accordion>

  <Accordion title="하트비트를 보내지 않으면 어떻게 되나요?">
    게임 세션의 Redis TTL은 **4분**입니다. 하트비트가 없으면 4분 후 세션이 자동 삭제되고, 과금이 비정상 종료됩니다. 반드시 2분 간격으로 하트비트를 보내세요.
  </Accordion>

  <Accordion title="CHARGE_EXHAUSTED 이후에도 하트비트를 보내야 하나요?">
    네. 서버가 2분 유예 기간을 두고 자동 종료합니다. 유예 기간 동안 하트비트를 계속 보내야 세션이 정상적으로 유지됩니다. 유저에게 G-coin 소진을 안내하되, 즉시 킥하지 않아도 됩니다.
  </Accordion>

  <Accordion title="verify 성공 후 is_pc_cafe가 false일 수 있나요?">
    현재 PlayWave는 PC방 전용 플랫폼이므로 verify 성공 시 `is_pc_cafe`는 항상 `true`입니다. 향후 확장을 위해 플래그를 확인하는 코드를 작성하는 것을 권장합니다.
  </Accordion>

  <Accordion title="서버가 재시작되면 세션은 어떻게 되나요?">
    Roblox 서버 재시작 시 `game:BindToClose`에서 모든 활성 세션의 종료 API를 호출합니다. 호출이 실패하더라도 4분 후 TTL 만료로 자동 정리됩니다.
  </Accordion>
</AccordionGroup>

## 텔레포트 관련

<AccordionGroup>
  <Accordion title="SubPlace로 텔레포트하면 PC방 혜택이 끊어집니다">
    텔레포트 시 `TeleportOptions`에 PlayWave 세션 데이터를 포함해야 합니다. `PlayWaveServer.prepareForTeleport(player, teleportOptions)`를 호출한 뒤 `TeleportAsync`를 실행하세요. 상세 가이드는 [텔레포트 연동](/ko/roblox/teleport)을 참고하세요.
  </Accordion>

  <Accordion title="텔레포트 연동 시 모든 SubPlace에 SDK를 설치해야 하나요?">
    네. 텔레포트 대상이 되는 모든 SubPlace에 PlayWave SDK가 설치되어 있어야 세션 데이터를 수신하고 인증을 유지할 수 있습니다.
  </Accordion>

  <Accordion title="플러그인 업데이트 후 기존 콜백 코드가 사라졌습니다">
    **Install SDK** 클릭 시 `PlayWaveSetup`과 `PlayWaveClient` 스크립트가 초기화됩니다. SDK 재설치 전에 반드시 기존 콜백 코드를 백업하고, 설치 후 복원하세요.
  </Accordion>

  <Accordion title="텔레포트 연동을 적용하지 않으면 어떻게 되나요?">
    SubPlace로 이동한 유저의 세션이 유지되지 않아 과금이 적용되지 않습니다. 이로 인해 수익 손실이 발생할 수 있습니다.
  </Accordion>
</AccordionGroup>

## Roblox 관련

<AccordionGroup>
  <Accordion title="LaunchData 길이 제한이 있나요?">
    OTT UUID 형태 (36자)를 전달하므로 길이 제한에 걸리지 않습니다.
  </Accordion>

  <Accordion title="PlayerRemoving에서 HTTP 호출이 완료되나요?">
    개별 유저 퇴장 시에는 서버가 살아있으므로 HTTP 호출이 정상 완료됩니다. 마지막 유저 퇴장으로 서버가 종료되는 경우를 위해 `game:BindToClose`를 사용합니다. `BindToClose`는 30초 제한이 있으며, 그 안에 HTTP 호출이 완료되어야 합니다.
  </Accordion>

  <Accordion title="task.spawn 하트비트 루프가 장시간 안정적인가요?">
    `task.spawn` + `task.wait` 루프는 Roblox에서 장시간 실행에 안정적입니다. 플레이어가 게임에 있는 동안 지속 실행되며, `activeSessions` 테이블에서 세션이 제거되면 루프가 자동 종료됩니다.
  </Accordion>

  <Accordion title="HttpService 외부 도메인 호출에 별도 허용 설정이 필요한가요?">
    Game Settings → Security → **Allow HTTP Requests** 활성화만으로 충분합니다. 별도 도메인 화이트리스트 설정은 필요 없습니다.
  </Accordion>
</AccordionGroup>