- 마지막 업데이트
PC방 연동
이해하기
PC방 연동은 게임에서 스토브 PC방 서비스를 활용할 수 있도록 지원하는 기능이에요.
스마일게이트 PC방 가맹점 IP로 접속한 이용자에게 PC방 접속 확인, 로그인·로그아웃, 혜택 갱신, 과금 처리가 자동으로 이루어져요.
연동에는 스토브 PC SDK가 제공하는 별도의 PCBang SDK를 사용해요.
이건 꼭 알아 두세요
PCBang SDK 연동은 선택 적용 항목이에요. Stove PC방 서비스를 이용하고자 하는 경우에만 연동하면 되고, 클라이언트 연동을 통해서 적용해요.
PCBang SDK는 국내에서만 사용할 수 있는 기능이에요.
스팀런처로 실행한 경우에는 지원하지 않는 기능이에요. 그러므로 스팀런처를 통해 실행중이라면 사용할 수 없어요.
적용 환경 및 동작 범위
| 항목 | 내용 |
|---|---|
| 제공 플랫폼 | PC SDK 3.0 (PCBang SDK) 전용. 클라이언트 연동. |
| 동작 국가 | 국내에서만 사용 가능. |
| 적용 여부 | 선택 적용. Stove PC방 서비스 이용 게임에 한해 연동. |
| 접속 인식 | 스마일게이트 PC방 가맹점 IP 접속 시 인식. PC방 외 접속은 콜백 처리 없이 우회. |
PC방 혜택 종류
PC방 접속 이용자의 혜택 등급은 PCBangPremium 열거형 값으로 전달돼요.
| 값 | 설명 |
|---|---|
| PCBANG_ERROR = -1 | 에러. |
| PCBANG_PREMIUM = 1 | 프리미엄. |
| PCBANG_FREE = 2 | 무료가맹. |
| PCBANG_FREE_OTHER = 3 | 집(PC방 이외) 무료가맹. |
PC방 접속 판단은 PCBANG_PREMIUM 또는 PCBANG_FREE 일 때 유효해요.
접속이 확인된 경우에만 이용자 로그인을 진행하고, 그 외에는 PC방 연동 동작을 진행하지 않아요.
4분 단위 혜택 자동 갱신
PCBang SDK는 PC방 이용자 로그인이 완료된 이후, 4분마다 자동으로 PC방 혜택을 갱신해요.
게임에서 별도 타이머를 구현할 필요가 없어요.
| 시점 | 동작 |
|---|---|
| 이용자 로그인 직후 | StovePCBangUserLogin 콜백을 통해 초기 혜택 정보 전달. |
| 4분마다 (loop) | StovePCRefreshUserBenefits 콜백을 통해 갱신된 혜택 정보 전달. |
| 이용자 로그아웃 시 | 4분 단위 갱신 동작 종료. |
연동 가이드
연동 준비
| 항목 | 내용 |
|---|---|
| Base SDK 연동 | PC방 기능을 사용하려면 게임에 Base SDK 연동이 선행되어야 함. |
| Base SDK 초기화 | Base_Initialize API를 통해 Base SDK 초기화 완료. Base SDK 초기화 미완료 시 PCBang SDK 사용 불가. |
| PCBang SDK 헤더 포함 | PCBangSDK.h 헤더 파일 include. Stove::PCSDK::PCBang 네임스페이스 사용 선언. |
| 콜백 구동 환경 | SDK 비동기 API 콜백 처리를 위해 게임 루프에서 Base_RunCallback() 주기 호출. |
개발하기
PC (PCSDK) — PCBang SDK
PC SDK 전용 기능이에요.
PCBang SDK 연동은 선택 적용 항목이며 국내에서만 동작해요. PC방이 아닌 환경에서는 후속 단계를 진행하지 않아요.
사전 준비
- BaseSDK 연동 및 초기화(
Base_Initialize)가 선행돼야 해요. 초기화 전에 PCBang SDK를 초기화하면 실패해요. - 게임 루프에서
Base_RunCallback()이 주기적으로 호출돼야 콜백이 정상 전달돼요. - 헤더는
PCBangSDK.h를 include하고Stove::PCSDK::PCBang네임스페이스를 사용해요. - 정리 순서는
PCBang_UserLogout→PCBang_UnInitialize→Base_UnInitialize로 진행해야 해요.
개발 흐름
- 초기화
Base_Initialize완료 이후PCBang_Initialize()로 PCBang SDK를 초기화하고, 성공한 뒤 PC방 상태 조회를 호출해요. - PC방 상태 조회
PCBang_CheckPCBangStatus(...)로 PC방 상태 객체를 받아 혜택 등급을 검사해요.StovePCBangStatus::GetPremiumStatus()를 사용해요.PCBANG_PREMIUM/PCBANG_FREE→ PC방 접속. 다음 단계 진행PCBANG_FREE_OTHER/PCBANG_ERROR→ 후속 단계 미진행
- 이용자 로그인
PC방 접속이 확인되면
PCBang_UserLogin(...)을 호출해요. 초기 로그인 콜백과 4분 주기 갱신 콜백을 한 번에 등록해요. 초기 로그인 콜백에서 혜택 코드·PC방 고유번호(시리얼 번호)·남은 시간을 가져와 게임 상태에 반영해요. - 혜택 자동 갱신
로그인 이후 4분마다 혜택 갱신 콜백(
StovePCRefreshUserBenefits)이 자동 호출돼요. 게임 측 타이머는 필요 없으며 콜백 값만 반영하면 돼요. - 이용자 로그아웃
게임 종료 직전
PCBang_UserLogout(...)을 호출해 과금·혜택 갱신을 종료해요. - 정리
PCBang_UnInitialize()후Base_UnInitialize()로 정리하고 게임 프로세스를 종료해요. - 버전 확인(선택)
기술지원 문의 시
PCBang_GetVersion(buffer, length)으로 받은 버전 문자열을 함께 전달해요.
트러블슈팅
| 상황 | 원인 | 해결 방법 |
|---|---|---|
게임 진입 직후 PCBang_Initialize 호출이 실패해요 | BaseSDK 초기화가 끝나지 않은 상태에서 PCBangSDK를 초기화했어요. PCBangSDK는 BaseSDK가 제공하는 이용자·환경 정보에 의존해요. | BaseSDK 초기화 콜백(OnInitializeFinished) 성공 이후에 PCBang_Initialize를 호출해야 해요. 부팅 시퀀스에서 BaseSDK → PCBangSDK 순서로 초기화하면 문제없어요. |
PCBang_CheckPCBangStatus에서 PCBANG_ERROR(-1)가 반환돼요 | 본 API는 스토브 /pcbang/v1.0/user/status 엔드포인트로 HTTP 호출을 보내요. 네트워크 단절이나 서버 응답 실패가 지속되면 PC방 여부를 판별할 수 없어 PCBANG_ERROR로 회신돼요. SDK 내부에 자동 재시도 로직이 있으므로, 게임이 받는 PCBANG_ERROR는 이미 재시도까지 모두 실패한 상태예요. | 게임에서 추가 호출을 하지 않아도 돼요. PCBANG_ERROR 반환 시 PCBang_UserLogin 같은 후속 단계를 진행하지 말아야 해요. 이용자에게는 일반(비PC방) 플레이 흐름을 그대로 노출하면 문제없어요. |
PCBANG_FREE_OTHER가 반환돼요 | 이용자가 무료가맹 PC(주로 가정)에 접속한 상태예요. PC방이 아니므로 PC방 이용자 로그인 흐름은 진행하지 말아야 해요. | PCBANG_FREE_OTHER는 PC방이 아닌 환경으로 분류해 일반 플레이 흐름으로 분기해야 해요. PC방 혜택 화면을 띄우지 말고 평소대로 게임을 진행하면 문제없어요. |
RefreshUserBenefits 콜백이 한참 호출되지 않아요 | 게임 메인 루프에서 Base_RunCallback()이 호출되지 않으면 SDK가 4분 단위 혜택 갱신을 게임에 전달할 수 없어요. | 메인 루프에서 매 프레임 또는 일정 주기로 Base_RunCallback()을 호출해야 해요. 입력 처리와 렌더 사이에 한 번 호출하면 문제없어요. |
| 4분 갱신 콜백이 처음 한 번도 오지 않아요 | PCBang_UserLogin을 호출하지 않았거나 호출 결과가 실패했어요. 또는 이미 PCBang_UserLogout이 호출된 상태라 SDK가 이용자를 로그아웃 상태로 보고 있어요. | PC방 환경에서 게임 진입 시 PCBang_UserLogin을 호출하고 성공 결과를 확인해야 해요. 로그아웃은 게임 종료 직전 한 번만 호출하도록 흐름을 정리하면 4분 갱신이 정상적으로 들어오므로 문제없어요. |
| 게임을 종료한 뒤에도 PC방 사장님 측에 이용자 세션이 한동안 활성으로 보여요 | PCBang_UserLogout은 스토브 /pcbang/v1.0/game/logout 엔드포인트로 세션 종료를 알리는 HTTP POST를 보내요. 호출하지 않고 게임이 종료되면 스토브 백엔드는 게임 세션이 계속 진행 중인 것으로 인지해 PC방 측에 활성 상태로 보여요. 게임 크래시·강제 종료 시에도 같은 상황이 발생할 수 있어요. | 게임 정상 종료 시퀀스에 PCBang_UserLogout 호출을 반드시 포함해야 해요. 비정상 종료 가능성을 줄이려면 종료 처리 흐름의 가능한 이른 시점에 로그아웃을 호출하면 문제없어요. |
| BaseSDK를 먼저 정리한 뒤 PCBangSDK를 정리하면 로그가 어색해지거나 일부 처리가 누락돼요 | PCBangSDK는 BaseSDK가 제공하는 공통 자원(전역 SDK 상태, 로깅 컨텍스트 등)을 사용해요. BaseSDK가 먼저 정리되면 PCBangSDK 정리 시점에 기대하는 컨텍스트가 사라져 후처리가 정상적으로 진행되지 않을 수 있어요. | 정리는 등록 역순으로 PCBang_UserLogout → PCBang_UnInitialize → Base_UnInitialize 순서를 지켜야 해요. 모듈을 여러 개 사용 중이라면 모든 SDK 모듈을 정리한 뒤 마지막에 BaseSDK를 정리하면 문제없어요. |
PCBANG_FREE 상태에서도 RefreshUserBenefits 콜백은 호출돼요
무료가맹(PC방) 이용자도 PC방 접속에 해당하므로 4분 단위 갱신 콜백이 정상 전달돼요. 혜택 등급에 따라 게임 측 처리만 분기하세요.
샘플 코드
// PCBang SDK C/C++ API 예제. Unreal 도 동일하게 사용해요.
#include "PCBangSDK.h"
using namespace Stove::PCSDK;
using namespace Stove::PCSDK::Base;
using namespace Stove::PCSDK::PCBang;
// 1) 초기화 (Base_Initialize 완료 이후)
auto initResult = PCBang_Initialize();
if (!initResult.IsSuccessful())
{
return;
}
// 2) PC방 여부 조회
PCBang_CheckPCBangStatus(
[](CallbackResult callbackResult, StovePCBangStatus status)
{
if (!callbackResult.GetResult().IsSuccessful()) return;
auto premium = status.GetPremiumStatus();
if (premium != PCBangPremium::PCBANG_PREMIUM &&
premium != PCBangPremium::PCBANG_FREE)
{
// PC방 접속 아님. 후속 단계 미진행
return;
}
// 3) PC방 유저 로그인 (초기 로그인 + 4분 주기 갱신 콜백 동시 등록)
PCBang_UserLogin(
[](CallbackResult loginResult, StovePCBangUserLogin login)
{
if (loginResult.GetResult().IsSuccessful())
{
int32_t serial = login.GetPCBangSerialNumber();
int32_t remain = login.GetRemainTime();
// 게임 상태에 혜택 반영
}
},
// 4) 4분마다 자동 호출되는 혜택 갱신 콜백
[](CallbackResult refreshResult, StovePCRefreshUserBenefits benefits)
{
if (refreshResult.GetResult().IsSuccessful())
{
// PCBANG_FREE 상태에서도 본 콜백은 호출돼요.
auto premium = benefits.GetPremiumStatus();
}
}
);
}
);
// 5) 게임 종료 시
PCBang_UserLogout([](CallbackResult result) { /* 결과 처리 */ });
PCBang_UnInitialize();
// 이후 Base_UnInitialize 호출