SDK 초기화부터 종료까지 기본 연동 흐름을 안내해요.

SDK 기본 연동

모바일 SDK

모바일 환경(STOVE Mobile SDK)에서 스토브 플랫폼을 연동하기 위한 기본 흐름을 안내해요.

개요

• 스토브 플랫폼은 게임 출시를 간편하게 만드는 통합 서비스를 제공해요.
• STOVE Mobile SDK(이하 Mobile SDK)를 게임에 연동하면 인증·운영·결제 기능을 게임에 쉽게 통합할 수 있어요.
• Mobile SDK는 Android(Kotlin/Java), iOS, Unity, Unreal 4개 빌드 환경에서 사용할 수 있어요.
• Auth/AuthUI 모듈이 통합 로그인을 담당하며, 기기 등록·본인인증·약관 동의·푸시 등록을 AuthUI.login 호출 한 번에 자동으로 처리해요.
• 전체 인증·계정 관리 흐름의 상세 옵션(직접 로그인, 회원 전환, 본인인증 수동 호출 등)은 로그인 가이드에서 다뤄요.

사전 준비

이 가이드를 진행하기 전에 아래 항목이 준비되어 있어야 해요.

연동 흐름

Mobile SDK 부팅 흐름은 4단계 핵심 호출과 자동 처리 영역으로 구성돼요.

• 게임 시작 동선
  • 앱이 실행되면 Auth.initialize로 SDK를 초기화해요. 이 단계에서 앱 업데이트·게임 점검도 함께 확인돼요.
  • AuthUI.setProviders로 게임이 지원할 인증 채널을 등록해요. 순서가 그대로 로그인 화면 노출 순서가 돼요.
  • AuthUI.login을 호출해 통합 로그인 화면을 띄우고 AccessToken을 발급받아요.
  • 로그인 완료 이후 User.setGameProfile로 캐릭터·월드 정보를 SDK에 전달해요.

• AuthUI.login 안에서 자동 처리되는 흐름
  • 통합 로그인 호출 한 번으로 신규 디바이스 기기 등록, 정책상 본인인증, 약관 동의, 푸시 등록이 함께 진행돼요.
  • 게임이 이 항목을 직접 호출할 필요는 없어요. 인게임 설정에서 다시 띄울 때만 별도 호출이 필요해요.

• 게임 진행 중
  • 캐릭터 설정이 끝나면 게임 메인 화면으로 진입해요.
  • AccessToken은 SDK가 만료 80% 시점에 자동 갱신하므로, 토큰을 캐싱하지 말고 매번 Auth.AccessToken을 조회해서 사용해요.

연동 상세

Mobile SDK 부팅 흐름의 핵심 5단계를 단계별 시나리오와 코드 예시로 안내해요.

1. SDK 초기화 (Auth.initialize)

서비스 이용에 필요한 초기 정보를 획득하는 단계예요. 초기화가 완료되어야 이후 로그인·결제·운영 기능을 사용할 수 있어요.

• 호출 조건
  • 앱 시작 시 1회 호출해요.
  • 다른 Mobile SDK API보다 먼저 호출되어야 해요.

• 동작 방식
  • 파트너스에 등록된 서비스 설정값(service_id, market_game_id)을 받아와요.
  • 앱 업데이트 필요 여부(AppUpdateError 30004)와 게임 점검 여부(MaintenanceError 30003)를 함께 확인해요.
  • 응답으로 받은 Result를 OperationUI.handleResult에 그대로 전달하면 점검·앱 업데이트 안내 UI가 자동으로 노출돼요. (직접 처리할 필요 없음)

• 시퀀스 다이어그램

• 샘플 코드
  • 플랫폼별(Unity / Unreal / Android (Kotlin · Java) / iOS) 전체 샘플 코드는 로그인 가이드 — 1. 초기화 (Auth.initialize) 섹션을 참고하세요.

2. 인증 채널 설정 (AuthUI.setProviders)

AuthUI.login을 호출하기 전에 게임이 지원할 인증 채널(Provider)을 등록해요. 전달한 배열의 순서가 그대로 로그인 화면의 노출 순서가 돼요.

• 호출 조건
  • Auth.initialize 완료 이후, AuthUI.login 호출 이전에 실행해요.
  • 게임당 1회 등록하면 돼요.

• 동작 방식
  • 게임이 지원하는 Provider 목록을 SDK에 전달해요.
  • 파트너스에 사전 등록된 채널만 정상 동작해요. 미등록 채널을 추가해도 로그인 시 인증되지 않아요.
  • 이메일 Provider는 별도 추가하지 않아도 기본 노출돼요. (로그인 화면 B타입은 이메일 Provider 필수)

• 샘플 코드
  • 플랫폼별(Unity / Unreal / Android (Kotlin · Java) / iOS) 전체 샘플 코드는 로그인 가이드 — 2. Provider 설정 (setProvider) 섹션을 참고하세요.

3. 통합 로그인 (AuthUI.login)

로그인 화면 노출부터 AccessToken 발급, 기기 등록·본인인증·약관 동의·푸시 등록까지 한 번에 처리하는 단계예요.

• 호출 조건
  • Auth.initialize와 AuthUI.setProviders가 모두 완료된 이후 호출해요.
  • 기존 AccessToken이 있다면 자동 로그인으로 처리되고, 없으면 이용자에게 로그인 화면을 노출해요.

• 동작 방식
  • 통합 로그인 UI를 띄우고 이용자가 선택한 Provider로 인증을 수행해요.
  • 인증 완료 후 AccessToken을 발급·갱신하고, 이용자 정보를 콜백으로 전달해요.
  • 아래 표의 항목들이 호출 한 번 안에서 함께 처리돼요.

• AuthUI.login 안에서 자동 처리되는 흐름

• 시퀀스 다이어그램

• 샘플 코드
  • 플랫폼별(Unity / Unreal / Android (Kotlin · Java) / iOS) 전체 샘플 코드는 로그인 가이드 — 3. 통합 로그인 (AuthUI.login) 섹션을 참고하세요.

4. 캐릭터·월드 설정 (User.setGameProfile)

로그인 완료 이후 이용자의 캐릭터 및 월드 정보를 SDK에 전달해요. 입력된 정보는 각 기능(쿠폰/팝업/빌링/푸시)에서 월드·캐릭터별로 구분해 사용돼요.

• 호출 조건
  • AuthUI.login이 성공한 이후, 게임 메인 페이지 진입 직전에 호출해요.
  • 이용자가 캐릭터를 변경하거나 다른 월드에 접속할 때 다시 호출해요.

• 동작 방식
  • characterNumber와 worldId를 GameProfile 객체로 만들어 AccessToken.user에 설정해요.
  • 월드를 지원하지 않는 게임은 worldId를 null로 전달하면 돼요. 단, 파트너스에는 default world가 최소 1개 등록되어 있어야 해요.
  • 값의 유효성(null 여부)은 SDK가 검사하지 않으므로 게임 측에서 null 체크를 해주세요.

• 샘플 코드
  • 월드 지원 게임 / 월드 미지원 게임 각각의 플랫폼별 전체 샘플 코드는 로그인 가이드 — 4. 캐릭터 설정 (setGameProfile) 섹션을 참고하세요.

5. AccessToken 사용 (Auth.AccessToken)

캐릭터 설정 이후 게임이 SDK 기능을 호출할 때 사용하는 토큰을 조회하는 단계예요.

• 호출 조건
  • 게임 실행 중 AccessToken이 필요한 시점마다 호출해요.
  • 토큰 값을 게임 내 변수로 캐싱하지 말고, 사용 시점마다 새로 조회해요.

• 동작 방식
  • SDK는 AccessToken 만료 시간의 80% 도달 시 자동으로 갱신해요.
  • 자동 갱신은 프로세스가 실행 중일 때만 동작하므로, 항상 Auth.AccessToken을 통해 최신 값을 받아야 해요.
  • AccessToken이 null이면 로그인이 풀린 상태이니, 로그인 흐름으로 다시 유도하세요.

• 샘플 코드
  • 플랫폼별(Unity / Unreal / Android (Kotlin · Java) / iOS) 전체 샘플 코드는 로그인 가이드 — SDK 토큰 관리 섹션을 참고하세요.

PC SDK

PC 환경(PCSDK3)에서 스토브 플랫폼을 연동하기 위한 기본 흐름을 안내해요.

• 스토브 플랫폼은 게임 출시를 간편하게 만드는 통합 서비스를 제공해요.
• STOVE PC SDK(이하 PC SDK)를 게임에 연동하면 스토브 플랫폼 서비스를 게임에 쉽게 통합할 수 있어요.
• STOVE PC Base SDK(이하 Base SDK)는 스토브 플랫폼 서비스의 기본 기능을 제공하는 필수 모듈이에요.

사전 준비

이 가이드를 진행하기 전에 개발 환경 설정 과정을 먼저 완료해 주세요. 시작하기 과정이 끝나야 아래 흐름을 문제 없이 진행할 수 있어요.

연동 흐름

Base SDK 연동 흐름은 다음과 같아요.

• 게임 시작 동선
  • 게임 시작 시 런처로부터 게임이 실행되었는지 검증해요.
  • 게임 시작 시 Base SDK를 초기화해요.
  • API 콜백 실행 루프를 구성해서 PC SDK API 실행 시 매 주기마다 콜백 큐에 적재된 콜백이 있으면 실행되도록 해요.

• API 콜백 실행 루프를 구성한 다음 게임에 맞게 선택적으로 구현
  • PC SDK에서 사용할 언어를 설정해요.
  • 캐릭터·월드 설정 (현재 접속한 worldId와 characterNumber를 PC SDK에 등록해요.)
  • 과몰입 방지 기능을 연동해요.
  • 게임시간선택제 기능을 연동해요.

• 게임 실행 중 선택적으로 사용 가능한 기능
  • 현재 이용자의 Game Access token을 획득해요.
  • 현재 이용자 정보를 획득해요.
  • 현재 이용자의 GDS 정보를 획득해요.
  • 현재 이용자의 Signin 정보를 획득해요.
  • Game Access token 갱신 알림 콜백을 등록해요. (토큰은 SDK 내부에서 자동 갱신되며, 갱신 시점에 등록된 콜백이 호출돼요.)

• 게임 종료 동선
  • 이용자가 게임을 종료하는 경우 Base SDK를 정리한 후 최종적으로 게임이 종료되도록 해요.

연동 상세

Base SDK를 연동하는 일반적인 시나리오를 시퀀스 다이어그램과 코드 예시로 안내해요.

1. 런처 실행 검증 및 Base SDK 초기화

게임이 정식 출시 버전이라면, 런처로부터 게임이 실행되었는지 먼저 검증한 다음 곧바로 Base SDK를 초기화해요. 검증과 초기화는 한 호출 흐름으로 묶여 있어요.

• 호출 조건
  • 정식 출시 버전에서는 런처를 통해 실행되었는지 검증해야 게임이 정상 실행돼요.
  • Base SDK 초기화는 다른 PC SDK 모듈 초기화보다 우선해서 이루어져야 해요.
  • 두 API 모두 UI Thread에서 호출되어야 해요.
  • 게임 시작 후 다른 Base SDK 기능을 사용하기 전에 호출되어야 해요.
  • 게임이 실행될 때 1번만 동작해야 해요. 실행 도중 Init/UnInit을 반복하면 안 돼요.

• 동작 방식
  1. 런처 검증: Base_RestartAppIfNecessaryAsync는 검증을 비동기(Asynchronous) 방식으로 처리해요. 결과는 콜백의 restartAppIfNecessary 인자로 전달돼요.
     • restartAppIfNecessary가 true이면 런처로 재실행됐다는 의미이므로 현재 게임 인스턴스는 종료해야 해요.
     • 런처 응답을 기다리는 타임아웃(밀리초)은 Base_RestartAppIfNecessaryAsync의 waitTimeMillisec 인자로 전달해요. 일반적으로 60,000(60초)을 사용해요.
  2. 파라미터 캐시: 검증 호출 시 전달한 initParam이 SDK 내부에 캐시돼요.
  3. Base SDK 초기화: 검증 콜백의 restartAppIfNecessary == false 분기에서 Base_InitializeEx를 호출해 캐시된 파라미터로 초기화해요. 별도 파라미터를 다시 전달할 필요가 없어요.
     • View, IAP 등 다른 모듈을 사용하는 경우 Base SDK 초기화 이후 각 모듈의 초기화 함수(예: View_Initialize, IAP_Initialize)를 별도로 호출해요. PCBang 등 다른 모듈도 각자의 초기화 흐름을 따라요.

• 시퀀스 다이어그램

• 코드 예시

#include "BaseSDK.h"

using namespace Stove::PCSDK;
using namespace Stove::PCSDK::Base;

void Base_RestartAppIfNecessaryAsync_Example()
{
    // 콜백에서 참조하므로 static으로 선언
    static StovePCInitializeParam initParam;
    initParam.SetEnvironment(L"YOUR_ENV(ex.SANDBOX)");
    initParam.SetGameID(L"YOUR_GAME_ID");
    initParam.SetApplicationKey(L"YOUR_APP_KEY");

    // Base_RestartAppIfNecessaryAsync 호출 (타임아웃 60초)
    Base_RestartAppIfNecessaryAsync(&initParam, 60'000, [](
        CallbackResult callbackResult, bool restartAppIfNecessary)
    {
        if (restartAppIfNecessary)
        {
            // 런처를 통해 재실행되었으므로 현재 인스턴스는 종료
            return;
        }

        // 검증 통과 → 캐시된 파라미터로 Base SDK 초기화 (Base_InitializeEx)
        Base_InitializeEx([](CallbackResult initResult)
        {
            if (initResult.GetResult().IsSuccessful())
            {
                // Base SDK 초기화 성공 시 로직을 구현해 주세요.
                // ex) 이곳에서 다른 SDK 모듈의 Initialize를 진행할 수 있어요.
            }
            else
            {
                // Base SDK 초기화 실패 시 로직을 구현해 주세요.
            }
        });
    });
}

2. API 콜백 실행

PC SDK의 비동기 API에 등록된 콜백을 실행하는 단계예요. 등록된 콜백은 콜백 큐에 적재되며, 본 API를 호출하는 시점에 큐에 쌓인 콜백이 한꺼번에 실행돼요.

• Base SDK 이외의 다른 PC SDK 모듈(View, IAP, PCBang 등)에 등록한 콜백도 본 기능 한 곳에서 실행돼요.
• 게임 메인 루프에서 주기적으로 호출하지 않으면 PC SDK 일부 API가 정상 동작하지 않을 수 있어요.
• 본 API는 반드시 UI Thread에서 호출되어야 해요.

• 두 가지 옵션 비교

• 시퀀스 다이어그램

• 코드 예시

#include "BaseSDK.h"

using namespace Stove::PCSDK;
using namespace Stove::PCSDK::Base;

void GameLoop()
{
    while (gameRunning)
    {
        ProcessGameLogic();

        // 옵션 A: 큐에 쌓인 모든 콜백 한 번에 실행
        Base_RunCallback();

        // 옵션 B: 콜백 실행 시간을 최대 10ms로 제한
        // 시간을 초과하면 남은 콜백은 다음 호출 시 이어서 실행
        // Base_RunCallbackWithTimeout(10);

        Render();
    }
}

3. Access token 조회 및 갱신 알림 등록

스토브 플랫폼 인증에 사용하는 Access token은 PCSDK 내부에서 만료 10분 전에 자동으로 갱신돼요. 게임 코드에서는 두 가지 API로 토큰을 다룰 수 있어요.

• 두 가지 API 비교

• 시퀀스 다이어그램

• 코드 예시

#include "BaseSDK.h"

using namespace Stove::PCSDK;
using namespace Stove::PCSDK::Base;

// (1) 갱신 알림 콜백 등록 - 초기화 직후 1회 호출
void Base_AccessTokenRenewed_Example()
{
    Base_AccessTokenRenewed(
        [](CallbackResult callbackResult, StovePCToken token)
        {
            if(callbackResult.GetResult().IsSuccessful())
            {
                // Access token 자동 갱신 후 후속 처리를 구현해 주세요.
                const wchar_t* renewed = token.GetAccessToken();
            }
            else
            {
                // 갱신 실패 시 로직을 구현해 주세요.
            }
        }
    );
}

// (2) 현재 Access token 즉시 조회 - 외부 호출 직전마다 호출
void Base_GetAccessToken_Example()
{
    // 토큰을 받을 버퍼를 충분한 크기로 준비해 주세요.
    wchar_t accessToken[4096] = { 0 };
    auto result = Base_GetAccessToken(accessToken, 4096);
    if(result.IsSuccessful())
    {
        // accessToken 버퍼에 항상 최신 토큰이 채워져요. 외부 서버 호출 등에 사용해 주세요.
    }
    else
    {
        // 조회 실패 시 로직을 구현해 주세요.
    }
}

4. 이용자·국가·인증 정보 조회

현재 스토브 런처로 로그인한 이용자에 대한 정보를 세 가지 API로 분리해 제공해요. 게임 화면·정책 분기·결제 가능 여부 판단 등 용도에 맞는 API를 골라 사용해요.

4-1. Base_GetUser — 이용자 기본 정보

StovePCUser가 제공하는 정보:

4-2. Base_GetGds — 접속 국가·규제·로케일

GDS(Geo-based Distribution Service)는 이용자의 접속 IP를 기반으로 한 국가·규제·로케일 정보예요. 베트남 규제, 셧다운, 약관 표시 언어 등 지역별 정책 분기에 활용해요.

StovePCGds가 제공하는 정보:

4-3. Base_GetSignin — 로그인 인증 정보

현재 게임이 실행 중인 스토브 플랫폼 인증 컨텍스트를 조회해요. 본인인증·이메일인증 여부, 가입 국가, 사용된 IDP(Identity Provider) 등을 확인할 수 있어요.

StovePCSignin가 제공하는 정보:

• 시퀀스 다이어그램

• 코드 예시

#include "BaseSDK.h"

using namespace Stove::PCSDK;
using namespace Stove::PCSDK::Base;

// (1) 사용자 기본 정보 조회
void Base_GetUser_Example()
{
    StovePCUser user;
    auto result = Base_GetUser(&user);
    if(result.IsSuccessful())
    {
        const wchar_t* nickname = user.GetNickname();
        uint64_t gameUserId = user.GetGameUserId();
    }
}

// (2) 접속 국가·규제·로케일 조회
void Base_GetGds_Example()
{
    StovePCGds gds;
    auto result = Base_GetGds(&gds);
    if(result.IsSuccessful())
    {
        const wchar_t* nation = gds.GetNation();
        bool isDefault = gds.IsDefault();
        const wchar_t* regulation = gds.GetRegulation();
        const wchar_t* language = gds.GetLanguage();
        const wchar_t* timeZone = gds.GetTimeZone();
    }
}

// (3) 로그인 인증 정보 조회
void Base_GetSignin_Example()
{
    StovePCSignin signin;
    auto result = Base_GetSignin(&signin);
    if(result.IsSuccessful())
    {
        const wchar_t* providerCode = signin.GetProviderCode();
        bool personVerify = signin.GetPersonVerify();
        bool emailVerify = signin.GetEmailVerify();
        const wchar_t* nationality = signin.GetNationality();
    }
}

5. 캐릭터·월드 설정

Base_SetGameProfile API를 통해 현재 게임에 접속한 월드 식별자(worldId) 와 캐릭터 식별자(characterNumber) 를 PC SDK에 등록해요. 등록된 식별자는 결제·운영 기능이 이용자 컨텍스트를 구분하는 키값으로 활용돼요.

• 호출 조건 및 주의 사항
  • 캐릭터·월드를 설정하지 않으면 결제(IAP)·쿠폰 등 일부 PC SDK 모듈이 정상 동작하지 않을 수 있어요.
  • 입력값의 유효성은 SDK가 별도로 검사하지 않으므로, 게임 측에서 null·빈 문자열 체크 후 호출해 주세요.
  • 입력한 캐릭터·월드 정보는 PC SDK 수명 주기 동안 유효해요. Base_UnInitialize 후 다시 초기화하는 경우에는 Base_SetGameProfile을 재호출해야 해요.
  • 이용자가 캐릭터 변경 / 월드 이동 등을 통해 컨텍스트가 바뀌면 즉시 재호출해 식별자를 갱신해 주세요.

• 시퀀스 다이어그램

• 코드 예시

#include "BaseSDK.h"

using namespace Stove::PCSDK;
using namespace Stove::PCSDK::Base;

// 함수 네이밍은 예시이므로 게임 구현에 맞게 변경하세요.
void Base_SetGameProfile_Example()
{
    // StovePCGameProfile 구조체 생성
    // 구조체 필드에 적절한 worldId, characterNumber 값을 할당하세요.
    auto gameProfile = StovePCGameProfile(L"YOUR_WORLD_ID", 0L);

    // 생성한 구조체를 이용해 Base_SetGameProfile 호출
    auto result = Base_SetGameProfile(&gameProfile);
    if(result.IsSuccessful())
    {
        // 캐릭터·월드 설정 성공 시 로직을 구현해 주세요.
    }
    else
    {
        // 캐릭터·월드 설정 실패 시 로직을 구현해 주세요.
    }
}

6. Base SDK 정리

Base_UnInitialize API를 호출해서 Base SDK를 정리하고 사용 중인 자원을 반환해요. 게임 종료 전에 BaseSDK 정리 로직을 진행해야 해요.

• 호출 조건
  • Base SDK 정리는 다른 PC SDK 정리보다 마지막으로 이루어져야 해요. 다른 PC SDK 정리 이전에 Base SDK를 정리하면 제대로 정리가 이루어지지 않을 수 있어요.
  • Base SDK를 정리한 후에는 Base SDK의 기능을 사용할 수 없어요.
  • Base SDK 정리는 UI Thread에서 호출되어야 해요.
  • 게임이 종료될 때 1번만 동작해야 해요.

• 시퀀스 다이어그램

• 코드 예시

#include "BaseSDK.h"

using namespace Stove::PCSDK;
using namespace Stove::PCSDK::Base;

void Base_UnInitialize_Example()
{
    // 다른 SDK를 사용했다면 Base_UnInitialize()가 마지막으로 호출되어야 해요.
    // ex) 정리 순서
    // PCBang_UserLogOut();
    // PCBang_UnInitialize();
    // View_UnInitialize();
    // IAP_UnInitialize();
    // Base_UnInitialize();
    auto result = Base_UnInitialize();
    if(result.IsSuccessful())
    {
        // Base SDK 정리 성공 시 로직을 구현해 주세요.
    }
    else
    {
        // Base SDK 정리 실패 시 로직을 구현해 주세요.
    }
}