Skip to content
스토브
마지막 업데이트

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_UserLogoutPCBang_UnInitializeBase_UnInitialize로 진행해야 해요.



개발 흐름

  1. 초기화Base_Initialize 완료 이후 PCBang_Initialize()로 PCBang SDK를 초기화하고, 성공한 뒤 PC방 상태 조회를 호출해요.
  2. PC방 상태 조회PCBang_CheckPCBangStatus(...)로 PC방 상태 객체를 받아 혜택 등급을 검사해요. StovePCBangStatus::GetPremiumStatus()를 사용해요.
    • PCBANG_PREMIUM / PCBANG_FREE → PC방 접속. 다음 단계 진행
    • PCBANG_FREE_OTHER / PCBANG_ERROR → 후속 단계 미진행
  3. 이용자 로그인 PC방 접속이 확인되면 PCBang_UserLogin(...)을 호출해요. 초기 로그인 콜백과 4분 주기 갱신 콜백을 한 번에 등록해요. 초기 로그인 콜백에서 혜택 코드·PC방 고유번호(시리얼 번호)·남은 시간을 가져와 게임 상태에 반영해요.
  4. 혜택 자동 갱신 로그인 이후 4분마다 혜택 갱신 콜백(StovePCRefreshUserBenefits)이 자동 호출돼요. 게임 측 타이머는 필요 없으며 콜백 값만 반영하면 돼요.
  5. 이용자 로그아웃 게임 종료 직전 PCBang_UserLogout(...)을 호출해 과금·혜택 갱신을 종료해요.
  6. 정리PCBang_UnInitialize()Base_UnInitialize()로 정리하고 게임 프로세스를 종료해요.
  7. 버전 확인(선택) 기술지원 문의 시 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_UserLogoutPCBang_UnInitializeBase_UnInitialize 순서를 지켜야 해요. 모듈을 여러 개 사용 중이라면 모든 SDK 모듈을 정리한 뒤 마지막에 BaseSDK를 정리하면 문제없어요.

PCBANG_FREE 상태에서도 RefreshUserBenefits 콜백은 호출돼요
무료가맹(PC방) 이용자도 PC방 접속에 해당하므로 4분 단위 갱신 콜백이 정상 전달돼요. 혜택 등급에 따라 게임 측 처리만 분기하세요.



샘플 코드

cpp
// 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 호출

자주 묻는 질문



Q1. PC방 연동은 모든 게임이 적용해야 하나요?
A. PCBang SDK 연동은 선택 적용 항목이에요. Stove PC방 서비스를 이용하고자 하는 게임만 연동하면 돼요.
PC방 서비스를 활용하지 않는 게임은 별도의 연동 없이 일반 PC SDK 연동만으로 충분해요.
Q2. SDK 호출 순서는 어떻게 되나요?
A. 게임 시작 시에는 Base_Initialize → PCBang_Initialize → PCBang_CheckPCBangStatus → (PC방인 경우) PCBang_UserLogin
게임 종료 시에는 반대로 PCBang_UserLogout → PCBang_UnInitialize → Base_UnInitialize 순서로 호출해야 해요.
Base SDK를 먼저 정리하면 PCBang SDK 정리가 정상적으로 이루어지지 않을 수 있어 순서 준수가 중요해요.
Q3. PC방이 아닌 환경에서는 어떻게 동작하나요?
A. PCBang_CheckPCBangStatus 호출 결과 PC방 접속이 아닌 것으로 확인되면 이후 PC방 연동 단계는 진행하지 않아도 돼요.
PC방 여부를 확인하지 않고 다음 동작을 진행하면 불필요한 API 호출과 오류가 발생할 수 있으니, PC방 여부를 확인한 뒤 분기 처리하는 것을 반드시 권장해요.
Q4. PC방 여부 판단은 어떤 값으로 하면 되나요?
A. StovePCBangStatusGetPremiumStatus() 반환값이 PCBANG_PREMIUM 또는 PCBANG_FREE 인 경우 PC방 접속으로 판단할 수 있어요.
PCBANG_FREE_OTHER는 집(PC방 이외) 무료가맹에 해당하므로 PC방 이용자 로그인 대상이 아니에요.
PCBANG_ERROR는 조회 자체가 실패한 경우이므로 후속 동작을 진행하지 않아요.
Q5. 4분마다 호출되는 콜백은 어떤 용도인가요?
A. PC방 이용자 로그인 이후 PCBang SDK가 4분 단위로 PC방 혜택을 자동 갱신해요. 갱신될 때마다 StovePCRefreshUserBenefits 콜백이 게임으로 전달돼요.
게임에서는 별도 타이머를 구현할 필요 없이, 콜백으로 받은 갱신 정보(혜택 코드, 남은 시간)를 게임 상태에 반영해 주세요.
이용자 로그아웃이 호출되면 4분 단위 갱신도 함께 종료돼요.
Q6. 게임 종료 시 이용자 로그아웃을 꼭 호출해야 하나요?
A. 네, 게임 종료 전에 PCBang_UserLogout이 먼저 호출되어야 해요.
로그아웃이 호출되어야 PC방 이용자 관리와 과금이 정상적으로 종료되며, 4분 단위 혜택 갱신도 종료돼요.
로그아웃 없이 게임을 종료하면 과금 처리에 영향이 발생할 수 있어요.
Q7. PCBang SDK 초기화가 실패하면 어떻게 처리하나요?
A. PCBang SDK 초기화 단계가 구현되지 않으면 PCBang SDK의 기능을 사용할 수 없어요. 우선 Base SDK 초기화가 정상 완료되었는지 확인이 필요해요.
Base SDK 초기화 미완료 상태에서 PCBang SDK를 초기화하면 실패하므로, 호출 순서를 재확인해 주세요.
그래도 실패하면 SDK 버전 정보를 함께 확인하여 기술지원으로 문의해 주세요.
Q8. PC방이 아닌 일반 환경에서 테스트하려면 어떻게 하나요?
A. PCBang SDK는 스마일게이트 PC방 가맹점 IP로 접속한 경우에만 PC방으로 인식돼요.
일반 환경에서는 PCBANG_FREE_OTHER 또는 PCBANG_ERROR가 반환되며, 이용자 로그인이나 혜택 갱신은 동작하지 않아요.
PC방 환경에서의 동작 검증이 필요한 경우 퍼블리싱 기술 담당자에게 테스트 환경 지원을 요청해 주세요.
Q9. 해외에서도 사용할 수 있나요?
A. PCBang SDK는 국내에서만 사용할 수 있는 기능이에요. 해외 환경에서는 PC방 인식 자체가 이루어지지 않으므로 연동 효과가 없어요.
Q10. SDK 버전은 어디서 확인할 수 있나요?
A. PCBang_GetVersion API에 미리 할당한 버퍼(예: wchar_t buffer[256])와 버퍼 크기를 전달하면 현재 연동된 SDK 버전 문자열이 채워져 반환돼요.
기술지원 문의 시 SDK 버전 정보를 함께 전달하면 빠른 원인 파악에 도움이 돼요.



직접 문의하고 싶으신가요? stove.developers@smilegate.com