Skip to content
스토어 연동
마지막 업데이트

추가 연동

5. 스탯 · 업적 · 리더보드

스탯 · 업적 · 리더보드는 STOVE 스토어 페이지에 노출되는 기능이에요. 이 장에서는 Brick Smash 가 게임오버 때 스탯을 저장하고, 업적 · 랭킹 · 스탯 화면에서 서버 값을 읽어 오는 코드를 따라가며 함수 5개의 사용법을 설명해요.

초기화, 종료, 소유권 확인은 2장 에서 이미 다뤘어요. 이 장의 함수는 모두 Stove_Initialize() 가 성공한 뒤에 호출해요.

개념

  • 스탯: 게임을 하면서 쌓이는 수치 하나(예: 부순 블록 수)를 STOVE 서버에 저장하고 조회해요.
  • 업적: 스탯 값이 목표 조건을 만족했는지에 따라 달성 여부가 정해지는 항목이에요.
  • 리더보드: 스탯을 기준으로 사용자 순위를 매긴 목록이에요. 페이지 단위로 조회해요.

업적과 리더보드는 코드로 갱신하지 않아요. 게임은 Stove_SetStat() 으로 스탯만 올리고, 서버가 STOVE Studio 에 등록한 설정에 따라 업적 달성과 순위를 평가해요. 그래서 Brick Smash 는 게임오버 때 Stove_SetStat() 만 호출하고, 업적과 리더보드는 화면을 열 때 조회만 해요.

STOVE Studio 에서 먼저 등록할 것

STOVE Studio 에 스탯 · 업적 · 리더보드를 먼저 등록해야 해요. 등록하지 않은 ID 로 호출하면 정상적인 값을 받을 수 없어요. Brick Smash 는 다음과 같이 등록해요.

항목등록 내용
스탯ID 는 MAX_BROKEN_BLOCKS, 값 처리 방식은 MAX 예요.
업적2종을 등록하고 위 스탯에 연결해요. "최초 블록격파"(조건 GTE 1)와 "10개 블록격파"(조건 GTE 10)예요.
리더보드위 스탯을 기준으로 만들어요.

스탯 ID 는 설정 파일의 stat_id, 리더보드 ID 는 leaderboard_id 에 넣어 두고 코드에서 읽어 써요. 스탯 ID 는 영문 대문자 · 숫자 · 밑줄 · 하이픈([A-Z0-9_-])으로만 이루어져야 해요.

ini
[gamesupport]
; 스탯 ID 형식: [A-Z0-9_-]
stat_id = MAX_BROKEN_BLOCKS
; STOVE Studio 에서 생성한 리더보드 식별자
leaderboard_id = YOUR_LEADERBOARD_ID

이 예시는 config/stove_config.example.ini 의 일부예요.

함수 5개

함수 5개 모두 비동기 함수예요. 결과는 Stove_RunCallback() 을 호출하는 스레드에서 콜백으로 와요. 파라미터 객체는 Stove_CreateParam() 으로 만들고, 호출한 뒤 Destroy() 해야 해요.

함수파라미터 종류 값콜백 형식콜백 결과
Stove_FetchStatk_EStoveGameSupportTypeKind_FetchStatParamOnGetStatCallbackIStoveStat
Stove_SetStatk_EStoveGameSupportTypeKind_SetStatParamOnSetStatCallbackIStoveSetStatOutcome
Stove_FetchAchievementk_EStoveGameSupportTypeKind_FetchAchievementParamOnGetAchievementCallbackIStoveAchievement
Stove_FetchAchievementsk_EStoveGameSupportTypeKind_FetchAchievementsParamOnGetAchievementsCallbackIStoveAchievementList
Stove_FetchRankingk_EStoveGameSupportTypeKind_FetchRankingParamOnGetRankingCallbackIStoveRanking

예제 게임의 구조

Brick Smash 는 SDK 호출을 src/stove/StoveGameSupport.cpp 한 곳에 모아 두었어요. 헤더 src/stove/StoveGameSupport.h 는 함수 4개만 공개해요.

cpp
namespace StoveGameSupport
{
    void SetStat(const std::wstring& statId, int value, SetStatState* out);
    void FetchStat(const std::wstring& statId, StatState* out);
    void FetchAchievements(AchievementsState* out);
    void FetchRanking(const std::wstring& leaderboardId, RankingState* out);
}

각 함수는 결과를 받을 상태 구조체의 포인터(out)를 받아요. 이 포인터를 userData 로 SDK 에 넘기면, 콜백에서 callbackResult->GetUserData() 로 되찾아 값을 채워요. 콜백이 받은 객체는 콜백이 끝나면 무효가 되므로, 화면에 필요한 값은 콜백 안에서 복사해요. 상태 구조체는 src/StoveState.h 에 있고 status 가 Idle → Loading → Done 또는 Error 로 바뀌어요.

cpp
enum class AsyncStatus
{
    Idle,
    Loading,
    Done,
    Error,
};

화면은 status 가 Idle 일 때 한 번만 호출을 시작해요. 콜백은 Stove_RunCallback() 안에서 실행되므로 화면 코드와 같은 스레드예요. 잠금 없이 상태를 바꿔도 안전해요.

파라미터는 base_guard.h 의 StoveMakeParam<T>() 로 만들어요. 반환된 StoveGuard 가 범위를 벗어날 때 Destroy() 를 대신 호출해 줘요.

호출 순서

  1. 게임오버처럼 수치가 확정되는 때 Stove_SetStat() 으로 스탯 값을 보내요.
  2. 콜백의 IsUpdated() 로 값이 실제로 바뀌었는지 확인해요.
  3. 스탯 화면을 열 때 Stove_FetchStat() 으로 현재 값을 조회해요.
  4. 업적 화면을 열 때 Stove_FetchAchievements() 로 목록을 조회해요. 하나만 필요하면 Stove_FetchAchievement() 를 써요.
  5. 랭킹 화면을 열 때 Stove_FetchRanking() 으로 원하는 페이지를 조회해요.

스탯 저장 (Stove_SetStat)

cpp
void Stove_SetStat(const IStoveSetStatParam* param, OnSetStatCallback onFinished, void* userData);
typedef void(__cdecl* OnSetStatCallback)(const IStoveCallbackResult* callbackResult, const IStoveSetStatOutcome* statOutcome);
Setter형식설명
SetStatsIdconst wchar_t*바꿀 스탯 ID 예요.
SetStatValueint32_t스탯에 적용할 새 값이에요. 지정한 값으로 바뀌고 기존 값에 더해지지 않아요.
메서드(IStoveSetStatOutcome)반환형설명
IsUpdated()bool스탯 값이 실제로 갱신되었으면 true 예요.
GetCurrentValue()int32_t갱신이 반영된 현재 값이에요.
GetErrorMessage()const wchar_t*값을 갱신하는 중에 문제가 있었다면 그 메시지예요.

src/stove/StoveGameSupport.cpp 의 SetStat() 이에요.

cpp
void StoveGameSupport::SetStat(const std::wstring& statId, int value, SetStatState* out)
{
    auto param = StoveMakeParam<IStoveSetStatParam>();
    if (!param.IsValid())
        return;
    param->SetStatsId(statId.c_str()); // [A-Z0-9_-] 형식
    param->SetStatValue(value);        // 지정한 값으로 바뀐다(더해지지 않는다)

    out->status = AsyncStatus::Loading;
    Stove_SetStat(param.Get(), OnSetStatFinished, out);
}

콜백은 같은 파일의 OnSetStatFinished() 예요.

cpp
void __cdecl OnSetStatFinished(const IStoveCallbackResult* r, const IStoveSetStatOutcome* outcome)
{
    auto* st = Self<SetStatState>(r);
    if (!r->GetResult()->IsSuccessful())
    {
        st->status = AsyncStatus::Error;
        st->error = DescribeFailure(r);
        return;
    }
    // 호출이 성공해도 값이 바뀌지 않을 수 있다(예: MAX 스탯에 더 작은 값). 오류가 아니다.
    st->updated = outcome->IsUpdated();
    st->currentValue = outcome->GetCurrentValue();
    st->status = AsyncStatus::Done;
}

Self<T>() 는 같은 파일 위쪽에 있는 도우미로, r->GetUserData() 를 T* 로 바꿔 줘요.

게임오버 때는 src/ui/GameScreen.cpp 에서 이 함수를 호출해요. 화면 상태를 게임오버(AppScreen::GameOver)로 바꾸는 코드와 같은 자리에 있어서, 게임오버로 바뀌는 순간 한 번만 호출돼요.

cpp
// 방금 죽었으면 게임오버로 전환 + 스탯 등록(한 번만)
if (game.IsGameOver())
{
    *ctx.current = AppScreen::GameOver;
    StoveGameSupport::SetStat(ctx.cfg->stat_id, game.score(), &ctx.state->setStat);
}

스탯은 값 처리 방식이 MAX 라서, 이번 판에서 부순 블록 수가 기존 최고 기록보다 클 때만 값이 바뀌어요. 이 호출 하나로 업적 달성 평가와 리더보드 갱신이 서버에서 함께 일어나요.

값이 실제로 바뀌었는지는 결과 코드가 아니라 IsUpdated() 로 판단해요. MAX 스탯에 더 작은 값을 보내면 호출은 성공하지만 IsUpdated() 는 false 예요. 이것은 오류가 아니에요.

스탯 조회 (Stove_FetchStat)

cpp
void Stove_FetchStat(const IStoveFetchStatParam* param, OnGetStatCallback onFinished, void* userData);
typedef void(__cdecl* OnGetStatCallback)(const IStoveCallbackResult* callbackResult, const IStoveStat* stat);
Setter형식설명
SetStatsIdconst wchar_t*조회할 스탯 ID 예요. 영문 대문자 · 숫자 · 밑줄 · 하이픈으로만 이루어져요.
메서드(IStoveStat)반환형설명
GetStatsFullId()const IStoveStatFullId*스탯의 전체 식별 정보예요. GetGameId() 와 GetStatsId() 를 가져요.
GetCurrentValue()int32_t스탯의 현재 값이에요.
GetUpdatedAt()uint64_t마지막으로 갱신된 시각이에요. Unix epoch 밀리초예요.

FetchStat() 과 콜백이에요.

cpp
void StoveGameSupport::FetchStat(const std::wstring& statId, StatState* out)
{
    auto param = StoveMakeParam<IStoveFetchStatParam>();
    if (!param.IsValid())
        return;
    param->SetStatsId(statId.c_str());

    out->status = AsyncStatus::Loading;
    Stove_FetchStat(param.Get(), OnFetchStatFinished, out);
}
cpp
void __cdecl OnFetchStatFinished(const IStoveCallbackResult* r, const IStoveStat* stat)
{
    auto* st = Self<StatState>(r);
    if (!r->GetResult()->IsSuccessful())
    {
        st->status = AsyncStatus::Error;
        st->error = DescribeFailure(r);
        return;
    }
    st->currentValue = stat->GetCurrentValue();
    st->status = AsyncStatus::Done;
}

src/ui/ServiceScreens.cpp 의 스탯 화면은 status 가 Idle 일 때 조회를 시작하고, Done 이 되면 값을 그려요. 새로고침 버튼은 status 를 Idle 로 되돌려 다음 프레임에 다시 조회하게 해요.

cpp
void DrawStatsScreen(ScreenContext& ctx)
{
    StatState& st = ctx.state->stat;

    if (st.status == AsyncStatus::Idle)
        StoveGameSupport::FetchStat(ctx.cfg->stat_id, &st);

    bool back = DrawHeader("스탯");

    DrawLoadingOrError(st.status, st.error);
    if (st.status == AsyncStatus::Done)
    {
        ImGui::SetWindowFontScale(1.4f);
        ImGui::Text("격파한 최대 블록 수: %d", st.currentValue);
        ImGui::SetWindowFontScale(1.0f);

        if (ImGui::Button("새로고침"))
            st.status = AsyncStatus::Idle;
    }
    // (뒤로 버튼 처리 생략)
}

업적 목록 조회 (Stove_FetchAchievements)

cpp
void Stove_FetchAchievements(const IStoveFetchAchievementsParam* param, OnGetAchievementsCallback onFinished, void* userData);
typedef void(__cdecl* OnGetAchievementsCallback)(const IStoveCallbackResult* callbackResult, const IStoveAchievementList* list);
Setter형식설명
SetPageSizeuint32_t한 페이지에 받을 업적 개수예요. 1 ~ 100 이에요. 설정하지 않거나 범위를 벗어나면 전체 목록을 한 번에 받아요.
SetAchievementIdconst wchar_t*페이지 단위로 받을 때만 써요. 첫 페이지는 비워 두고, 다음 페이지부터는 직전에 받은 목록의 마지막 업적 ID 를 넣어요.
메서드(IStoveAchievementList)반환형설명
GetCount()uint32_t이번에 받은 업적 개수예요.
GetAt(uint32_t index)const IStoveAchievement*index 번째 업적이에요. 범위를 벗어나면 nullptr 이에요.
GetTotalCount()uint32_t전체 업적 개수예요. 페이지 단위로 받지 않았으면 GetCount() 와 같아요.

업적 정보(IStoveAchievement)는 다음 값을 가져요. 1개 조회 함수의 결과도 같은 형식이에요.

메서드반환형설명
GetAchievementId()const wchar_t*업적 ID 예요.
GetName()const wchar_t*현지화된 업적 이름이에요.
GetDescription()const wchar_t*현지화된 업적 설명이에요.
GetDefaultImage()const wchar_t*달성 전 이미지의 URL 이에요.
GetAchievedImage()const wchar_t*달성 후 이미지의 URL 이에요.
GetValue()int32_t업적의 현재 진행 값이에요.
GetStatus()const wchar_t*상태예요. ONGOING(진행 중) 또는 ACHIEVED(달성)예요.
GetCondition()const IStoveAchievementCondition*달성 조건이에요. 아래 표를 참고해요.
메서드(IStoveAchievementCondition)반환형설명
GetGoalValue()int32_t목표값이에요.
GetType()const wchar_t*목표값과 사용자 값을 비교하는 방식이에요. GTE(이상) 또는 LTE(이하)예요.
GetValueOperation()const wchar_t*값 처리 방식이에요. DELTA_SUM(누적 합산) · REPLACE(교체) · MAX(더 큰 값으로 교체) · MIN(더 작은 값으로 교체)이 있어요.

상태와 조건 값은 열거형이 아니라 문자열로 와요. 비교할 때는 wcscmp 를 써요.

FetchAchievements() 는 파라미터에 아무 값도 넣지 않아서 전체 목록을 한 번에 받아요.

cpp
void StoveGameSupport::FetchAchievements(AchievementsState* out)
{
    // 페이지 크기를 넣지 않으면 전체 목록을 한 번에 받는다.
    auto param = StoveMakeParam<IStoveFetchAchievementsParam>();
    if (!param.IsValid())
        return;

    out->status = AsyncStatus::Loading;
    Stove_FetchAchievements(param.Get(), OnFetchAchievementsFinished, out);
}

콜백은 목록을 순회하면서 화면에 필요한 값을 UTF-8 문자열과 정수로 복사해요. 달성 여부는 GetStatus() 를 wcscmp 로 비교해 판단해요.

cpp
void __cdecl OnFetchAchievementsFinished(const IStoveCallbackResult* r, const IStoveAchievementList* list)
{
    auto* st = Self<AchievementsState>(r);
    if (!r->GetResult()->IsSuccessful())
    {
        st->status = AsyncStatus::Error;
        st->error = DescribeFailure(r);
        return;
    }
    st->items.clear();
    for (uint32_t i = 0; i < list->GetCount(); ++i)
    {
        const IStoveAchievement* a = list->GetAt(i);
        if (a == nullptr)
            continue;
        AchievementsState::Item item;
        item.name = WideToUtf8(a->GetName());
        item.description = WideToUtf8(a->GetDescription());
        item.achieved = (wcscmp(a->GetStatus(), L"ACHIEVED") == 0); // 상태는 문자열로 온다
        item.value = a->GetValue();
        item.goal = a->GetCondition() ? a->GetCondition()->GetGoalValue() : 0;
        st->items.push_back(item);
    }
    st->status = AsyncStatus::Done;
}

src/ui/ServiceScreens.cpp 의 DrawAchievementsScreen() 은 이 목록을 "달성" 또는 "진행중"과 진행 값(value / goal)으로 그려요. 화면 아래에는 새로고침 버튼이 있어요.

cpp
if (ImGui::Button("새로고침"))
    st.status = AsyncStatus::Idle;

게임오버 직후 곧바로 업적 화면을 열면 방금 달성한 업적이 아직 보이지 않을 수 있어요. 업적 평가는 서버에서 일어나고 반영이 즉시가 아닐 수 있으므로, 사용자가 다시 조회할 수 있게 새로고침 버튼을 두었어요.

페이지 단위로 받기

업적이 많으면 페이지 단위로 받을 수 있어요. Brick Smash 는 업적이 2개라 쓰지 않아요.

  1. 첫 호출은 SetPageSize(20) 처럼 페이지 크기만 넣고 AchievementId 는 비워 둬요.
  2. 콜백에서 받은 목록의 마지막 항목의 GetAchievementId() 를 게임 쪽에 복사해 둬요.
  3. 다음 페이지가 필요하면 같은 페이지 크기와 2번의 ID 를 넣어 다시 호출해요.
  4. 지금까지 받은 개수가 GetTotalCount() 에 이르면 멈춰요.

업적 1개 조회 (Stove_FetchAchievement)

cpp
void Stove_FetchAchievement(const IStoveFetchAchievementParam* param, OnGetAchievementCallback onFinished, void* userData);
typedef void(__cdecl* OnGetAchievementCallback)(const IStoveCallbackResult* callbackResult, const IStoveAchievement* achievement);
Setter형식설명
SetAchievementIdconst wchar_t*조회할 업적 ID 예요.

콜백으로 오는 IStoveAchievement 는 위 업적 목록 조회의 표와 같아요. 예제는 목록 조회를 써요. 이 함수는 업적 하나의 진행 상태만 보여 주는 화면처럼 하나만 필요할 때 써요.

랭킹 조회 (Stove_FetchRanking)

cpp
void Stove_FetchRanking(const IStoveFetchRankingParam* rankParams, OnGetRankingCallback onFinished, void* userData);
typedef void(__cdecl* OnGetRankingCallback)(const IStoveCallbackResult* callbackResult, const IStoveRanking* ranking);
Setter형식설명
SetLeaderboardIdconst wchar_t*STOVE Studio 에서 만든 리더보드 ID 예요.
SetPageIndexuint32_t조회할 페이지 번호예요. 1부터 시작해요.
SetPageSizeuint32_t한 페이지에 받을 순위 개수예요. 1 ~ 50 이에요.
SetIncludeMyRankbooltrue 이면 결과의 첫 항목이 항상 로그인한 사용자 본인의 순위예요.
메서드(IStoveRanking)반환형설명
GetCount()uint32_t이번 페이지의 순위 항목 개수예요.
GetAt(uint32_t index)const IStoveRank*index 번째 순위 항목이에요. 범위를 벗어나면 nullptr 이에요.
GetTotalCount()uint32_t모든 페이지를 합친 순위 항목 개수예요.
메서드(IStoveRank)반환형설명
GetNickname()const wchar_t*사용자 닉네임이에요.
GetProfileImage()const wchar_t*사용자 프로필 이미지의 URL 이에요.
GetScore()int32_t리더보드 점수예요.
GetRank()uint32_t현재 순위예요.
cpp
void StoveGameSupport::FetchRanking(const std::wstring& leaderboardId, RankingState* out)
{
    auto param = StoveMakeParam<IStoveFetchRankingParam>();
    if (!param.IsValid())
        return;
    param->SetLeaderboardId(leaderboardId.c_str());
    param->SetPageIndex(1);        // 1부터 시작
    param->SetPageSize(20);        // 1 ~ 50
    param->SetIncludeMyRank(true); // 첫 항목이 항상 본인 순위

    out->status = AsyncStatus::Loading;
    Stove_FetchRanking(param.Get(), OnFetchRankingFinished, out);
}
cpp
void __cdecl OnFetchRankingFinished(const IStoveCallbackResult* r, const IStoveRanking* ranking)
{
    auto* st = Self<RankingState>(r);
    if (!r->GetResult()->IsSuccessful())
    {
        st->status = AsyncStatus::Error;
        st->error = DescribeFailure(r);
        return;
    }
    st->rows.clear();
    st->total = ranking->GetTotalCount();
    for (uint32_t i = 0; i < ranking->GetCount(); ++i)
    {
        const IStoveRank* rank = ranking->GetAt(i);
        if (rank == nullptr)
            continue;
        st->rows.push_back({ rank->GetRank(), WideToUtf8(rank->GetNickname()), rank->GetScore() });
    }
    st->status = AsyncStatus::Done;
}

src/ui/ServiceScreens.cpp 의 DrawRankingScreen() 이 이 목록을 순위 · 닉네임 · 점수 표로 그리고, 위쪽에 전체 인원(st.total)을 보여 줘요. 업적 화면과 마찬가지로 Idle 일 때 한 번만 조회하고 새로고침 버튼으로 다시 조회해요.

cpp
if (st.status == AsyncStatus::Idle)
    StoveGameSupport::FetchRanking(ctx.cfg->leaderboard_id, &st);

주의할 점

스탯 · 업적 · 리더보드 ID 는 STOVE Studio 에 미리 등록한 값과 정확히 같아야 해요. 스탯 ID 는 [A-Z0-9_-] 형식이에요.

스탯 값이 바뀌었는지는 IsUpdated() 로 판단해요. IsUpdated() 가 false 여도 오류가 아니에요.

업적의 상태(GetStatus())와 조건(GetType() · GetValueOperation())은 열거형이 아니라 문자열이에요. wcscmp 로 비교해요.

SetIncludeMyRank(true) 를 넣으면 결과의 첫 항목이 본인 순위예요. Brick Smash 는 첫 항목을 따로 구분하지 않고 다른 순위와 같은 표에 그려요. 본인 순위를 강조하려면 i == 0 인 항목을 따로 처리해요. 페이지 크기 범위는 랭킹 조회가 1 ~ 50, 업적 목록 조회가 1 ~ 100 이에요.

업적 달성은 서버가 평가하므로 반영이 즉시가 아닐 수 있어요. 업적 화면에 새로고침 버튼을 두어 사용자가 다시 조회할 수 있게 해 주세요.

콜백으로 받은 객체(IStoveStat · IStoveAchievementList · IStoveRanking 등)는 콜백이 끝나면 무효가 돼요. 포인터를 보관하지 말고 필요한 값을 콜백 안에서 복사해요.

6. 결제

인게임 상점을 열고 상품을 파는 기능이에요. 이 장에서는 Brick Smash 의 상점 화면과 보관함 화면을 따라가며 상품 조회, 구매, 보관함 조회를 설명해요. 상점을 열지 않는 게임은 이 장을 건너뛰어도 돼요.

초기화와 종료는 2장 에서 다뤘어요. 이 장의 함수는 모두 Stove_Initialize() 가 성공한 뒤에 호출해요.

준비

  1. STOVE Studio 에서 인게임 상점을 등록해 샵 키를 받아요.
  2. 상품이 들어갈 카테고리와 판매할 상품을 STOVE Studio 에 등록해요. 등록이 끝나지 않으면 조회 함수가 빈 목록을 돌려줘요. Brick Smash 는 상점 화면을 확인할 테스트 상품 하나를 등록해요.
  3. 초기화 파라미터에 SetShopKey 와 SetMainWndHandle 을 둘 다 넣어요. 자세한 초기화 순서는 2장 을 참고해요.
  4. 결제 창은 SDK 가 WebView2 로 띄우므로 사용자 PC 에 WebView2 런타임이 필요해요.

Brick Smash 는 샵 키를 설정 파일(config/stove_config.ini)의 shop_key 에서 읽어요. 이 값을 비우면 상점과 보관함을 쓸 수 없어요.

ini
[stove]
; 인게임 상점 ShopKey. 비워 두면 결제 기능을 초기화하지 않는다.
shop_key = YOUR_SHOP_KEY

src/stove/StoveSession.cpp 의 Initialize() 는 결제를 쓰기 때문에 샵 키와 메인 창 핸들을 모두 넣어요.

cpp
// 결제를 쓰므로 샵 키와 메인 창 핸들을 둘 다 넣는다. 결제가 없으면 Stove_Initialize(nullptr) 로 충분하다.
param->SetShopKey(cfg_->shop_key.c_str());
param->SetMainWndHandle(hwnd_);

메인 창 핸들은 창이 만들어진 뒤에만 유효해요. Brick Smash 는 창을 만든 다음 초기화하므로 그대로 넘길 수 있어요.

함수 5개

함수하는 일콜백 결과
Stove_FetchShopCategories상점 카테고리 목록을 조회해요.IStoveShopCategoryList
Stove_FetchProducts카테고리 · 페이지 조건으로 상품 목록을 조회해요.IStoveProductList
Stove_StartPurchase상품 1개 이상의 구매 절차를 시작해요.IStoveStartPurchaseOutcome + 결제 창 닫힘 콜백
Stove_ConfirmPurchase시작한 구매를 확정해요.IStoveConfirmPurchaseOutcome
Stove_FetchInventory사용자의 구매 내역(보관함)을 조회해요.IStoveInventoryList

Brick Smash 는 SDK 호출을 src/stove/StoveIAP.cpp 에 모아 두었어요. 공개 함수는 3개이고, 결제 진행 방식은 WithWebViewAndConfirmResult 라서 Stove_ConfirmPurchase() 와 Stove_FetchShopCategories() 는 쓰지 않아요.

cpp
// 인게임 상점. 결제 창은 SDK 웹뷰가 띄우고 확정까지 처리한다(WithWebViewAndConfirmResult).
namespace StoveIAP
{
    void FetchProducts(ShopState* out);
    void StartPurchase(int64_t productId, double salePrice, ShopState* out);
    void FetchInventory(InventoryState* out);
}

이 코드는 src/stove/StoveIAP.h 예요. 상태 구조체(ShopState · InventoryState)는 5장에서 설명한 것과 같은 방식으로 콜백 결과를 화면으로 넘겨요.

호출 순서

  1. 상점 화면을 열 때 Stove_FetchProducts() 로 상품 목록을 받아요. 카테고리별 탭이 필요하면 먼저 Stove_FetchShopCategories() 로 카테고리를 받아요.
  2. 사용자가 상품을 고르면 Stove_StartPurchase() 로 구매를 시작해요.
  3. 결제 방식(Operation)에 따라 구매를 확정해요.
    • WithWebViewAndConfirmResult: SDK 가 결제 창을 띄우고, 결제가 성공하면 확정까지 처리한 결과를 Stove_StartPurchase() 의 콜백으로 돌려줘요. 게임은 Stove_ConfirmPurchase() 를 호출하지 않아요.
    • Default · WithWebView: 결제가 끝난 뒤 게임이 Stove_ConfirmPurchase() 를 직접 호출해야 구매가 완료돼요.
  4. 확정 결과로 받은 상품을 게임에서 지급해요.
  5. 게임을 시작할 때와 상점을 열 때 Stove_FetchInventory() 로 구매 내역을 조회해, 아직 지급하지 않은 항목이 있으면 지급해요.

이 장은 가장 단순한 WithWebViewAndConfirmResult 방식을 기준으로 설명하고, 나머지 방식은 결제 진행 방식 에서 따로 설명해요.

상품 조회 (Stove_FetchProducts)

cpp
void Stove_FetchProducts(const IStoveFetchProductsParam* params, OnFetchProductsCallback onFinished, void* userData);
typedef void(__cdecl* OnFetchProductsCallback)(const IStoveCallbackResult* callbackResult, const IStoveProductList* list);
Setter형식설명
SetCategoryIdconst wchar_t*카테고리 ID 예요. 비워 두면 모든 카테고리의 상품을 받아요.
SetPageIndexuint32_t페이지 번호예요. 1부터 시작해요.
SetPageSizeuint32_t한 페이지에 받을 상품 개수예요.

상품(IStoveProduct)에서 상점 화면과 구매 요청에 주로 쓰는 값은 다음과 같아요.

메서드반환형설명
GetProductId()int64_t상품 ID 예요. 구매 요청에 넘겨요.
GetInserviceItemId()const wchar_t*이 상품에 연결된 게임 쪽 아이템 ID 예요. 지급할 아이템을 고를 때 써요.
GetProductName() · GetProductDescription()const wchar_t*현지화된 상품 이름과 설명이에요.
GetQuantity()int32_t한 번 구매할 때 들어 있는 아이템 수량이에요.
GetProductTypeCode()int32_t상품 분류예요. EStoveProductTypeCode 값이에요.
GetCurrencyCode()const wchar_t*통화 코드예요(ISO 4217, 예: KRW, USD).
GetPrice() · GetSalePrice()double결제 처리에 쓰는 정가와 판매가예요. 할인 중이 아니면 두 값이 같아요.
GetStrDisplayPrice() · GetStrDisplaySalePrice()const wchar_t*통화 서식이 적용된 화면 표시용 가격 문자열이에요.
IsDiscounted()bool지금 할인 중이면 true 예요.
GetDiscountType() · GetDiscountTypeValue()int32_t할인 방식(정률 · 정액)과 할인 폭이에요.
HasPurchased()bool사용자가 이 상품을 한 번이라도 구매했으면 true 예요.
GetPurchaseAvailabilityCode()int16_t구매 가능 여부예요. 1 은 구매 가능, 2 는 구매 제한 초과, 3 은 품절, 4 는 이미 수령함이에요. 상품 1개를 구매할 때 기준이라, 2개 이상을 함께 요청하면 결과가 다를 수 있어요.
GetThumbnailUrl()const wchar_t*대표 이미지의 URL 이에요.

할인 기간 · 판매 기간 · 구매 제한 정책 등 나머지 값은 헤더의 IStoveProduct 에서 확인해요.

src/stove/StoveIAP.cpp 의 FetchProducts() 예요.

cpp
void StoveIAP::FetchProducts(ShopState* out)
{
    auto param = StoveMakeParam<IStoveFetchProductsParam>();
    if (!param.IsValid())
        return;
    param->SetCategoryId(L""); // 비우면 모든 카테고리
    param->SetPageIndex(1);
    param->SetPageSize(20);

    out->status = AsyncStatus::Loading;
    Stove_FetchProducts(param.Get(), OnFetchProductsFinished, out);
}

콜백은 구매 요청에 필요한 값(상품 ID 와 판매가)과 화면 표시용 값을 복사해 둬요.

cpp
void __cdecl OnFetchProductsFinished(const IStoveCallbackResult* r, const IStoveProductList* list)
{
    auto* st = Self<ShopState>(r);
    if (!r->GetResult()->IsSuccessful())
    {
        st->status = AsyncStatus::Error;
        st->error = DescribeFailure(r);
        return;
    }
    st->products.clear();
    for (uint32_t i = 0; i < list->GetCount(); ++i)
    {
        const IStoveProduct* p = list->GetAt(i);
        if (p == nullptr)
            continue;
        ShopState::Product item;
        item.id = p->GetProductId();
        item.name = WideToUtf8(p->GetProductName());
        item.desc = WideToUtf8(p->GetProductDescription());
        item.priceStr = WideToUtf8(p->GetStrDisplaySalePrice()); // 통화 서식이 적용된 표시용 문자열
        item.salePrice = p->GetSalePrice();                       // 결제 요청에 그대로 넘긴다
        item.purchased = p->HasPurchased();
        st->products.push_back(item);
    }
    st->status = AsyncStatus::Done;
}

화면에 가격을 보여 줄 때는 GetStrDisplaySalePrice() 를, 구매 요청에 넘길 때는 GetSalePrice() 를 써요. 두 값의 용도가 달라요.

카테고리 조회 (Stove_FetchShopCategories)

Brick Smash 는 상품을 카테고리로 나누지 않아서 이 함수를 쓰지 않아요. 상점에 탭이 필요한 게임을 위해 함수 모양과 메서드만 소개해요.

cpp
void Stove_FetchShopCategories(const IStoveTypeBase* param, OnFetchShopCategoriesCallback onFinished, void* userData);
typedef void(__cdecl* OnFetchShopCategoriesCallback)(const IStoveCallbackResult* callbackResult, const IStoveShopCategoryList* list);

파라미터 자리에는 nullptr 을 넘겨요. 목록(IStoveShopCategoryList)은 GetCount() · GetAt(index) 로 순회해요.

메서드(IStoveShopCategory)반환형설명
GetCategoryId()const wchar_t*카테고리 ID 예요. 상품 조회에 넘겨요.
GetCategoryParentId()const wchar_t*상위 카테고리 ID 예요. 최상위 카테고리는 빈 문자열이에요.
GetCategoryDisplayNo()int32_t같은 단계의 카테고리 사이에서 보여 줄 순서예요.
GetCategoryName()const wchar_t*현지화된 카테고리 이름이에요.
GetCategoryDepth()int32_t카테고리 트리에서의 깊이예요. 최상위가 0 이에요.

구매 시작 (Stove_StartPurchase)

cpp
void Stove_StartPurchase(const IStoveStartPurchaseParam* params,
                         OnStartPurchaseCallback onFinished, OnIAPPopupDestroyCallback onDestroy,
                         void* userData1, void* userData2);
typedef void(__cdecl* OnStartPurchaseCallback)(const IStoveCallbackResult* callbackResult, const IStoveStartPurchaseOutcome* outcome);
typedef void(__cdecl* OnIAPPopupDestroyCallback)(const IStoveCallbackResult* callbackResult, const IStoveTypeBase* reserved);

콜백을 2개 받아요. onFinished 는 구매 결과를, onDestroy 는 이 호출로 열린 결제 창이 모두 닫혔음을 알려 줘요. userData1 은 onFinished 로, userData2 는 onDestroy 로 전달돼요. onDestroy 의 두 번째 인자(reserved)는 항상 nullptr 이에요.

파라미터는 객체 3종류를 조립해서 만들어요.

객체종류 값Setter설명
IStoveOrderProductParamk_EStoveIAPTypeKind_OrderProductParamSetProductId(int64_t) · SetSalePrice(double) · SetQuantity(int32_t)상품 1개분 주문 정보예요. 판매가는 상품 조회에서 받은 GetSalePrice() 값을 넣어요. 서버가 가격이 맞는지 확인하는 데 써요.
IStovePurchaseParamk_EStoveIAPTypeKind_PurchaseParamSetOperation(int32_t) · SetWebViewMode(int32_t) · SetWebViewPosX · SetWebViewPosY · SetWebViewWidth · SetWebViewHeight(모두 int32_t, 픽셀)결제 진행 방식과 결제 창의 위치 · 크기예요. 위치 · 크기는 Operation 이 Default 가 아닐 때만 써요.
IStoveStartPurchaseParamk_EStoveIAPTypeKind_StartPurchaseParamSetProducts(IStoveOrderProductParam**, uint32_t) · SetPurchaseParam(IStovePurchaseParam*) · SetServiceTxnNo(const wchar_t*) · SetExtraData(const wchar_t*)위 2가지를 묶는 객체예요. ServiceTxnNo(게임 쪽 거래 번호)와 ExtraData(보통 JSON 문자열)는 선택이에요.

SetWebViewMode 에는 k_EStoveWebViewMode_External(0, 게임 창과 별개의 창) 또는 k_EStoveWebViewMode_Internal(1, 게임 메인 창의 자식 창)을 넣어요. Internal 을 쓸 수 없으면 External 로 열려요.

콜백으로 오는 IStoveStartPurchaseOutcome 은 다음 값을 가져요.

메서드반환형설명
GetTxnMasterNo()int64_t구매 거래 번호예요. Stove_ConfirmPurchase() 에 넘겨요.
GetTxnDetailNos() · GetTxnDetailNosCount()const int64_t* · uint32_t상품별 거래 상세 번호 배열과 그 개수예요.
GetPurchaseProgress()int32_t진행 상태예요. k_EStovePurchaseProgress_NeedPaymentWindow(1)이면 게임이 결제 창을 직접 열어야 하고, k_EStovePurchaseProgress_NotNeedPaymentWindow(2)이면 결제 창이 필요 없어요.
GetTempPaymentUrl()const wchar_t*1회용 결제 URL 이에요. Operation 이 Default 일 때 와요.
IsPurchased()boolWithWebViewAndConfirmResult 에서 결제와 확정이 성공했으면 true 예요.
GetPurchasedProductCount() · GetPurchasedProductAt(i)uint32_t · const IStovePurchasedProduct*구매된 상품 목록이에요. WithWebViewAndConfirmResult 에서 결제가 성공했을 때 채워져요.
GetChargeInfoCount() · GetChargeInfoAt(i)uint32_t · const IStoveChargeInfo*결제에 쓴 결제 수단 목록이에요.
GetExtraData()const wchar_t*요청할 때 넣은 ExtraData 를 그대로 돌려줘요.
IsPopupCreated()bool이 호출로 결제 창이 하나라도 만들어졌는지 알려 줘요. 성공 · 실패와 관계없이 항상 확인해요. false 이면 onDestroy 가 오지 않아요.

구매된 상품(IStovePurchasedProduct)은 GetTxnDetailNo()(거래 상세 번호) · GetProductId() · GetCategoryId() · GetTotalQuantity() · GetMemberQuantity() · GetGuidQuantity() 를 가져요.

src/stove/StoveIAP.cpp 의 StartPurchase() 예요. 파라미터 3개를 조립해서 호출해요.

cpp
void StoveIAP::StartPurchase(int64_t productId, double salePrice, ShopState* out)
{
    // 파라미터 3개를 조립한다. 부모를 Destroy 해도 자식은 해제되지 않으므로 각각 StoveGuard 로 관리한다.
    auto order = StoveMakeParam<IStoveOrderProductParam>();
    auto option = StoveMakeParam<IStovePurchaseParam>();
    auto param = StoveMakeParam<IStoveStartPurchaseParam>();
    if (!order.IsValid() || !option.IsValid() || !param.IsValid())
        return;

    order->SetProductId(productId);
    order->SetSalePrice(salePrice); // 상품 조회에서 받은 값 그대로. 서버가 가격 불일치를 검사한다
    order->SetQuantity(1);

    option->SetOperation(k_EStovePurchaseOperation_WithWebViewAndConfirmResult);
    option->SetWebViewMode(k_EStoveWebViewMode_Internal); // 게임 창의 자식 창
    option->SetWebViewPosX(50);  // 만든 직후에는 모두 0 이므로 반드시 넣는다
    option->SetWebViewPosY(50);
    option->SetWebViewWidth(800);
    option->SetWebViewHeight(600);

    IStoveOrderProductParam* orders[] = { order.Get() };
    param->SetProducts(orders, 1);
    param->SetPurchaseParam(option.Get());

    out->purchaseStatus = AsyncStatus::Loading;
    out->purchaseError.clear();
    out->popupOpen = true;
    // userData1 → onFinished, userData2 → onDestroy
    Stove_StartPurchase(param.Get(), OnStartPurchaseFinished, OnPurchasePopupDestroyed, out, out);
    // SDK 는 반환 전에 필요한 값을 복사하므로, 여기서 param · option · order 가 해제되어도 안전하다.
}

이 코드에서 눈여겨볼 점이 3가지 있어요.

  • 부모(IStoveStartPurchaseParam)를 Destroy() 해도 SetProducts · SetPurchaseParam 으로 넘긴 자식 객체는 해제되지 않아요. 그래서 3개 모두 각각 StoveGuard 로 관리해요. Stove_StartPurchase() 가 반환되면 SDK 가 필요한 값을 이미 복사해 두었으므로, 함수가 끝나면서 3개가 해제돼도 안전해요.
  • 결제 창의 위치와 크기(WebViewPosX · WebViewPosY · WebViewWidth · WebViewHeight)는 파라미터를 만든 직후 모두 0 이에요. 값을 넣지 않으면 크기가 0 인 창이 만들어져요. 게임 화면 해상도에 맞춰 직접 정해요.
  • userData1 과 userData2 에 같은 out 을 넘겼어요. 두 콜백이 같은 상태(ShopState)를 써서 그래요.

구매 결과 콜백 OnStartPurchaseFinished() 예요. 결제와 확정이 끝났는지(IsPurchased()), 호출은 성공했지만 구매는 되지 않았는지, 호출이 실패했는지 3가지로 나눠요.

cpp
// 결제 + 확정 결과. WithWebViewAndConfirmResult 에서는 확정이 끝난 뒤에 온다.
void __cdecl OnStartPurchaseFinished(const IStoveCallbackResult* r, const IStoveStartPurchaseOutcome* outcome)
{
    auto* st = Self<ShopState>(r);
    if (r->GetResult()->IsSuccessful() && outcome->IsPurchased())
    {
        // 거래 상세 번호(GetPurchasedProductAt(i)->GetTxnDetailNo())를 기준으로 중복 지급을 막는다.
        st->justPurchased = true;
        st->purchaseStatus = AsyncStatus::Done;
        st->status = AsyncStatus::Idle; // 상품 목록을 다시 읽어 HasPurchased 를 갱신한다
    }
    else if (r->GetResult()->IsSuccessful())
    {
        // 호출은 성공했지만 구매가 확정되지 않았다(결제하지 않고 창을 닫은 경우 등).
        st->purchaseStatus = AsyncStatus::Idle;
    }
    else
    {
        st->purchaseStatus = AsyncStatus::Error;
        st->purchaseError = DescribeFailure(r);
    }

    // 결제 창이 만들어지지 않았으면 onDestroy 가 오지 않으므로 여기서 정리한다.
    if (!outcome->IsPopupCreated())
        st->popupOpen = false;
}

결제 창이 모두 닫히면 OnPurchasePopupDestroyed() 가 와요. 구매 버튼을 다시 누를 수 있게 popupOpen 을 내려요.

cpp
// 이 호출로 열린 결제 창이 모두 닫혔을 때 온다.
void __cdecl OnPurchasePopupDestroyed(const IStoveCallbackResult* r, const IStoveTypeBase* /*reserved*/)
{
    Self<ShopState>(r)->popupOpen = false;
}

IsPopupCreated() 가 false 이면 이 호출에 대한 onDestroy 는 오지 않아요. 결제 창이 만들어지기 전에 실패한 경우예요. 그래서 OnStartPurchaseFinished() 의 맨 끝에서 popupOpen 을 직접 내려요. 이 처리가 없으면 구매 버튼이 영원히 비활성 상태로 남아요.

결제 진행 방식

IStovePurchaseParam::SetOperation 에 넣는 값에 따라 결제 창을 누가 띄우고 누가 확정하는지가 달라져요.

값결제 창구매 확정onFinished 가 오는 때
k_EStovePurchaseOperation_Default(0)SDK 가 띄우지 않아요. 게임이 GetTempPaymentUrl() 의 1회용 URL 로 결제 페이지를 직접 열어요.게임이 Stove_ConfirmPurchase() 를 호출해요.결제 URL 이 준비되었을 때
k_EStovePurchaseOperation_WithWebView(1)SDK 가 결제 창을 띄워요.게임이 Stove_ConfirmPurchase() 를 호출해요.결제 창을 연 직후
k_EStovePurchaseOperation_WithWebViewAndConfirmResult(2)SDK 가 결제 창을 띄워요.결제가 성공하면 SDK 가 확정까지 처리해요.확정이 끝났을 때. 결제를 마치기 전에 창이 닫히면 실패로 와요.

Brick Smash 는 WithWebViewAndConfirmResult 를 써서 Stove_ConfirmPurchase() 를 호출하지 않아요. 가장 단순해서 처음 연동할 때 권하는 방식이에요.

  • Default · WithWebView 로 시작한 구매는 결제 창에서 결제를 마쳤더라도 게임이 Stove_ConfirmPurchase() 를 호출하기 전까지 완료되지 않아요. WithWebView 에서는 onDestroy 로 결제 창이 닫힌 것을 확인한 뒤 확정을 호출하고, 확정 결과의 IsConfirmed() 로 실제 결제 여부를 판단해요.
  • 상품 가격의 합이 0원이면 Operation 과 관계없이 결제 창 없이 바로 구매가 완료돼요. 이때 GetPurchaseProgress() 가 NotNeedPaymentWindow(2)로 와요. Default 방식에서는 이 값을 확인하지 않고 늘 결제 URL 을 열면 오동작해요.
  • 0원 상품을 WithWebViewAndConfirmResult 로 구매하면 Stove_StartPurchase() 콜백에서 IsPurchased() 가 true 로 와요. 이미 확정까지 끝난 상태라 Stove_ConfirmPurchase() 를 호출하지 않아요.

구매 확정 (Stove_ConfirmPurchase)

cpp
void Stove_ConfirmPurchase(const IStoveConfirmPurchaseParam* param, OnConfirmPurchaseCallback onFinished, void* userData);
typedef void(__cdecl* OnConfirmPurchaseCallback)(const IStoveCallbackResult* callbackResult, const IStoveConfirmPurchaseOutcome* outcome);

Operation 이 WithWebViewAndConfirmResult 가 아닌 구매를 확정하는 함수예요.

Setter형식설명
SetTxnMasterNoint64_tStove_StartPurchase() 결과의 GetTxnMasterNo() 값이에요.
메서드(IStoveConfirmPurchaseOutcome)반환형설명
IsConfirmed()bool구매가 확정되었으면 true 예요.
GetPurchasedProductCount() · GetPurchasedProductAt(i)uint32_t · const IStovePurchasedProduct*구매된 상품 목록이에요.
GetChargeInfoCount() · GetChargeInfoAt(i)uint32_t · const IStoveChargeInfo*결제에 쓴 결제 수단 목록이에요.

결제 수단(IStoveChargeInfo)은 GetChargeType()(2 쿠폰, 98 STOVE 캐시, 99 포인트, 그 밖은 외부 결제 수단) · GetChargeTypeName() · GetChargeDeductVal() · GetChargeDisplayDeductVal() 을 가져요.

아래 코드는 예제 게임에는 없는 흐름이에요. WithWebView 로 시작한 구매에서 결제 창이 닫힌 뒤 확정을 호출하는 짧은 예예요. 구매 시작 콜백에서 GetTxnMasterNo() 를 복사해 두었다가, onDestroy 에서 아래 코드로 확정해요. GrantItemOnce() 는 SDK 가 제공하지 않는 가상 함수예요. 거래 상세 번호로 중복 지급을 막는 지급 함수를 게임이 직접 구현해야 해요.

cpp
// 구매 시작 콜백에서 GetTxnMasterNo() 를 복사해 둔 값이에요.
static int64_t g_pendingTxnMasterNo = 0;

void __cdecl OnConfirmPurchaseFinished(const IStoveCallbackResult* callbackResult, const IStoveConfirmPurchaseOutcome* outcome)
{
    if (callbackResult->GetResult()->IsSuccessful() && outcome->IsConfirmed())
    {
        for (uint32_t i = 0; i < outcome->GetPurchasedProductCount(); ++i)
        {
            const IStovePurchasedProduct* purchased = outcome->GetPurchasedProductAt(i);
            if (purchased == nullptr)
                continue;
            // 가상 함수예요. 거래 상세 번호로 이미 지급했는지 확인한 뒤 지급해요.
            GrantItemOnce(purchased->GetTxnDetailNo(), purchased->GetProductId(), purchased->GetTotalQuantity());
        }
    }
    // 호출이 성공해도 IsConfirmed() 가 false 이면 확정되지 않은 구매라 지급하지 않아요.
}

// 결제 창이 닫힌 뒤(onDestroy)에 호출해요.
auto param = StoveMakeParam<IStoveConfirmPurchaseParam>();
if (param.IsValid())
{
    param->SetTxnMasterNo(g_pendingTxnMasterNo);
    Stove_ConfirmPurchase(param.Get(), OnConfirmPurchaseFinished, nullptr);
}

호출의 성공 여부(IsSuccessful())와 확정 여부(IsConfirmed())는 별개예요. 호출이 성공해도 IsConfirmed() 가 false 이면 구매가 확정되지 않은 상태이니 아이템을 지급하지 않아요.

보관함 조회 (Stove_FetchInventory)

cpp
void Stove_FetchInventory(const IStoveTypeBase* param, OnFetchInventoryCallback onFinished, void* userData);
typedef void(__cdecl* OnFetchInventoryCallback)(const IStoveCallbackResult* callbackResult, const IStoveInventoryList* list);

로그인한 사용자의 구매 내역(보관함)을 조회해요. 파라미터 자리에는 nullptr 을 넘기고, 목록은 GetCount() · GetAt(index) 로 순회해요.

메서드(IStoveInventoryItem)반환형설명
GetTxnMasterNo()int64_t구매 거래 번호예요.
GetTxnDetailNo()int64_t상품별 거래 상세 번호예요. 중복 지급을 막는 기준으로 써요.
GetProductId()int64_t상품 ID 예요.
GetInserviceItemId()const wchar_t*게임 쪽 아이템 ID 예요.
GetProductName()const wchar_t*현지화된 상품 이름이에요.
GetQuantity()int32_t구매 수량이에요.
GetThumbnailUrl()const wchar_t*대표 이미지의 URL 이에요.

src/stove/StoveIAP.cpp 의 FetchInventory() 예요. 파라미터가 필요 없어서 nullptr 을 넘겨요.

cpp
void StoveIAP::FetchInventory(InventoryState* out)
{
    out->status = AsyncStatus::Loading;
    Stove_FetchInventory(nullptr, OnFetchInventoryFinished, out);
}

콜백은 항목마다 거래 상세 번호, 상품 이름, 수량을 복사해요.

cpp
void __cdecl OnFetchInventoryFinished(const IStoveCallbackResult* r, const IStoveInventoryList* list)
{
    auto* st = Self<InventoryState>(r);
    if (!r->GetResult()->IsSuccessful())
    {
        st->status = AsyncStatus::Error;
        st->error = DescribeFailure(r);
        return;
    }
    st->items.clear();
    for (uint32_t i = 0; i < list->GetCount(); ++i)
    {
        const IStoveInventoryItem* item = list->GetAt(i);
        if (item == nullptr)
            continue;
        st->items.push_back({ item->GetTxnDetailNo(), WideToUtf8(item->GetProductName()), item->GetQuantity() });
    }
    st->status = AsyncStatus::Done;
}

Brick Smash 의 보관함 화면(DrawInventoryScreen())은 항목마다 상품 이름, 수량, 거래 상세 번호를 그대로 보여 줘요.

cpp
for (const auto& it : st.items)
    ImGui::Text("%s  x%d  (거래상세번호 %lld)", it.name.c_str(), it.quantity,
                static_cast<long long>(it.txnDetailNo));

클라이언트가 갑자기 종료되거나 네트워크가 끊기면 구매는 끝났는데 아이템이 지급되지 않은 상태가 생길 수 있어요. 아이템을 실제로 지급하는 게임이라면 게임을 시작할 때와 상점을 열 때 보관함을 조회하고, GetTxnDetailNo() 기준으로 아직 지급하지 않은 항목을 찾아 지급을 마무리해요.

상점 화면

src/ui/ServiceScreens.cpp 의 DrawShopScreen() 은 샵 키가 비어 있으면 호출을 시도하지 않고 안내 문구만 보여 줘요.

cpp
if (ctx.cfg->shop_key.empty())
{
    if (DrawHeader("상점"))
        *ctx.current = AppScreen::Menu;
    ImGui::TextUnformatted("shop_key 가 설정되지 않았어요. config/stove_config.ini 를 확인해 주세요.");
    return;
}

구매 버튼은 결제 창이 열려 있거나 구매가 진행 중일 때 비활성으로 만들어서, 같은 상품을 연속으로 눌러 결제 창이 겹치는 일을 막아요. 이미 구매한 상품(HasPurchased())에는 버튼 대신 안내 문구를 보여 줘요.

cpp
if (p.purchased)
{
    ImGui::TextColored(ImVec4(1, 0.7f, 0.3f, 1), "이미 구매한 상품");
}
else
{
    bool busy = st.popupOpen || st.purchaseStatus == AsyncStatus::Loading;
    ImGui::BeginDisabled(busy);
    if (ImGui::Button("구매"))
    {
        st.justPurchased = false;
        StoveIAP::StartPurchase(p.id, p.salePrice, &st);
    }
    ImGui::EndDisabled();
}

구매가 끝나면(justPurchased) 화면 위쪽에 배너를 띄우고, 상품 목록을 다시 조회해서 HasPurchased() 를 갱신해요. 상품 목록을 다시 조회하는 것은 OnStartPurchaseFinished() 가 status 를 Idle 로 되돌려 두었기 때문이에요. 다음에 상점 화면을 그릴 때 Idle 을 보고 FetchProducts() 를 다시 호출해요.

cpp
// 구매 완료 배너 (상단)
if (st.justPurchased)
{
    ImGui::PushStyleColor(ImGuiCol_ChildBg, ImVec4(0.15f, 0.45f, 0.2f, 1.0f));
    ImGui::BeginChild("buy_banner", ImVec2(0, 32), true);
    ImGui::TextColored(ImVec4(0.7f, 1.0f, 0.7f, 1.0f), "아이템을 구매했습니다!");
    ImGui::EndChild();
    ImGui::PopStyleColor();
}

주의할 점

샵 키 없이 초기화했다면 이 장의 함수는 동작하지 않아요. 초기화 파라미터에 SetShopKey 와 SetMainWndHandle 을 둘 다 넣었는지 확인해요.

SDK 가 결제 창을 띄우는 방식(WithWebView · WithWebViewAndConfirmResult)은 게임 화면의 전체 화면 설정에 제약이 있어요. Exclusive Fullscreen 에서는 결제 창이 보이지 않으니 Borderless Windowed Fullscreen 을 써 주세요.

결제 창을 한꺼번에 닫아야 하면 Stove_CloseAllPopups() 를 써요. 동기 함수이고 IStoveResult* 를 반환하니, 확인한 뒤 Destroy() 해요.

콜백으로 받은 상품 · 구매 · 보관함 객체와 배열(GetTxnDetailNos() 포함)은 콜백이 끝나면 무효가 돼요. 필요한 값은 콜백 안에서 복사해요. 콜백은 Stove_RunCallback() 을 호출한 스레드에서 실행되므로, Brick Smash 처럼 상태 구조체에 복사하면 화면 코드가 안전하게 읽을 수 있어요.

아이템을 지급할 때는 반드시 거래 상세 번호(TxnDetailNo)를 기준으로 이미 지급했는지 확인해요. 구매 콜백과 보관함 조회에서 같은 거래가 두 번 보일 수 있어요.

확정 콜백이 실패하거나 IsConfirmed() 가 false 이면 지급하지 말고 Stove_FetchInventory() 로 미확정 구매를 다시 조회해 처리해요.

가격과 통화 코드는 사용자에 맞춰 달라질 수 있어요. 가격을 화면에 보일 때는 GetStrDisplaySalePrice() 같은 서식 문자열을 쓰고, 구매 요청에는 GetSalePrice() 값을 그대로 넘겨요.

7. 베트남 게임시간 제한

베트남 법령에 따라 베트남에서 서비스하는 게임은 연령등급 표시와 과몰입 알림을 화면에 띄워야 해요. 이 장에서는 Brick Smash 가 알림을 받아 오버레이를 그리는 코드를 따라가며 함수 2개의 사용법을 설명해요.

한국의 셧다운과 과몰입 방지 알림은 4장 에서 다뤘어요. 초기화와 종료는 2장 을 참고해요.

무엇을 연동해야 하나요

베트남 내 서비스는 연령등급 표시와 과몰입 알림 2가지를 모두 연동해야 해요.

함수대상콜백이 오는 때콜백 정보
Stove_VietnamAgeRatingNotification베트남 사용자연령등급 오버레이를 표시하거나 숨겨야 할 때IStoveVietnamAgeRatingInfo
Stove_VietnamOverimmersionNotification베트남 사용자정해진 주기마다(게임 시작 직후 포함)IStoveVietnamOverimmersionInfo

두 함수는 모두 알림을 받을 콜백을 등록하는 함수예요. 한 번만 호출해 두면 SDK 가 필요한 때마다 콜백을 여러 번 보내요. 첫 번째 인자는 SDK 가 쓰지 않는 자리라 nullptr 을 넘겨요.

cpp
void Stove_VietnamAgeRatingNotification(const IStoveTypeBase* param, OnVietnamAgeRatingNotificationCallback onFinished, void* userData);
void Stove_VietnamOverimmersionNotification(const IStoveTypeBase* param, OnVietnamOverimmersionNotificationCallback onFinished, void* userData);
typedef void(__cdecl* OnVietnamAgeRatingNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveVietnamAgeRatingInfo* ageRatingInfo);
typedef void(__cdecl* OnVietnamOverimmersionNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveVietnamOverimmersionInfo* overimmersionInfo);

두 함수는 베트남 전용이에요. 접속 IP 로 판별한 국가가 베트남이 아니면 NotSupportedCountry(31)로 실패해요. 이 실패는 정상이에요. 다른 국가의 사용자에게는 오류로 안내하지 말고 조용히 무시해요.

호출 순서

  1. 창을 만든 뒤 Stove_Initialize() 가 성공하면, 화면을 그릴 수 있는 상태이므로 곧바로 두 함수를 한 번씩 호출해요.
  2. 게임 루프의 Stove_RunCallback() 에서 콜백이 올 때마다 전달된 정보를 게임 쪽 변수로 복사해요.
  3. 렌더링 코드가 복사해 둔 값으로 오버레이를 그려요.
  4. 노출 시간이 지난 오버레이는 게임이 매 프레임 시간을 줄여 가며 숨겨요.

베트남 함수 2개는 화면을 그릴 수 있는 시점 이후에 등록해요. 과몰입 알림은 게임을 시작한 직후(경과 0분)에도 한 번 오기 때문에, 그보다 먼저 등록하면 첫 안내를 화면에 띄우지 못해요. Brick Smash 는 창을 만든 뒤 초기화하므로 Initialize() 안에서 바로 등록해요.

src/stove/StoveSession.cpp 의 Initialize() 끝부분이에요. 한국용 알림 2개(셧다운 · 과몰입)를 등록한 다음 베트남용 2개를 등록해요.

cpp
// 3) 규제 알림 콜백 등록. 한 번만 등록하면 SDK 가 필요할 때마다 콜백을 보낸다.
Stove_ShutdownNotification(nullptr, OnShutdownNotificationFinished, this);
Stove_OverImmersionNotification(nullptr, OnOverImmersionNotificationFinished, this);
// 베트남 알림 2종은 화면을 그릴 수 있는 시점 이후에 등록해야 한다. 이 예제는 창을 만든 뒤 초기화하므로 여기서 바로 등록한다.
Stove_VietnamAgeRatingNotification(nullptr, OnVietnamAgeRatingNotificationFinished, this);
Stove_VietnamOverimmersionNotification(nullptr, OnVietnamOverimmersionNotificationFinished, this);

userData 로 StoveSession 의 this 를 넘기고, 같은 파일 위쪽의 콜백이 이 포인터를 되찾아 OnVietnamAgeRating() 과 OnVietnamOverimmersion() 으로 넘겨 줘요.

cpp
void __cdecl OnVietnamAgeRatingNotificationFinished(const IStoveCallbackResult* r, const IStoveVietnamAgeRatingInfo* info)
{
    Self(r)->OnVietnamAgeRating(r, info);
}
void __cdecl OnVietnamOverimmersionNotificationFinished(const IStoveCallbackResult* r, const IStoveVietnamOverimmersionInfo* info)
{
    Self(r)->OnVietnamOverimmersion(r, info);
}

오버레이 상태 (EStoveOverlayMode)

두 알림 모두 GetOverlayMode() 로 오버레이를 어떻게 할지 알려 줘요. 값은 EStoveOverlayMode 예요.

값이름뜻
0k_EStoveOverlayMode_Show오버레이를 표시해요. 과몰입 알림에서는 타이머가 시작된 상태라는 뜻이라 아직 표시하지 않아도 돼요.
1k_EStoveOverlayMode_Hide오버레이를 숨겨요.
2k_EStoveOverlayMode_Expanded오버레이를 펼쳐서 표시해요. 과몰입 알림에서 와요.

연령등급 알림은 Show 와 Hide 로 표시 여부를 정하고, 과몰입 알림은 Expanded 일 때 펼쳐 표시하고 Hide 일 때 숨겨요.

오버레이 모양

두 알림은 오버레이의 모양을 정하는 값도 함께 보내요.

값설명
테마(GetOverlayType())0 은 Black 이에요. 어두운 배경 RGB(33,33,33)에 흰 글자예요. 1 은 White 예요. 흰 배경 RGB(255,255,255)에 검은 글자예요. 기본값은 White 예요.
크기 배율(GetOverlayScale())0.0 ~ 1.0 이에요.
불투명도(GetOverlayOpacity())0.0 ~ 1.0 이에요.
위치(GetDisplayPositionX() · GetDisplayPositionY())화면 왼쪽 · 위쪽을 기준으로 한 비율이에요. 각각 0.0 ~ 1.0 이에요.

위치가 픽셀이 아니라 화면 크기에 대한 비율이므로, 해상도가 바뀌어도 같은 값으로 그릴 수 있어요.

연령등급 알림 (Stove_VietnamAgeRatingNotification)

게임의 연령등급을 화면에 띄워 두는 기능이에요. 오버레이를 실제로 그리는 것은 게임이에요.

메서드(IStoveVietnamAgeRatingInfo)반환형설명
GetOverlayMode()int32_t오버레이 상태예요. Show(0)이면 표시하고, Hide(1)이면 숨겨요.
GetOverlayType()int32_t테마예요. 0 은 Black, 1 은 White 예요.
GetOverlayScale()float오버레이 크기 배율이에요. 0.0 ~ 1.0 이에요.
GetOverlayOpacity()float오버레이 불투명도예요. 0.0 ~ 1.0 이에요.
GetAgeRating()int32_t게임 연령등급이에요. 0 은 전체이용가, 12 · 16 · 18 은 각 나이 이상이에요.
GetMsg()const wchar_t*연령등급 안내 메시지예요.
GetDisplayPositionX()float표시 위치의 x 좌표예요. 화면 왼쪽 기준 0.0 ~ 1.0 이에요.
GetDisplayPositionY()float표시 위치의 y 좌표예요. 화면 위쪽 기준 0.0 ~ 1.0 이에요.
GetLanguage()const wchar_t*글꼴을 고를 때 쓰는 언어 코드예요(예: ko, en, vi, zh-cn).

콜백 밖에서 그리므로 값을 복사해 둘 구조체가 필요해요. src/stove/StoveSession.h 의 AgeRatingOverlay 예요.

cpp
// 베트남 연령등급 오버레이. 콜백 밖에서 그리므로 값을 복사해 둔다.
struct AgeRatingOverlay
{
    bool visible = false;
    int32_t type = 1;          // 0 Black, 1 White
    float scale = 1.0f;
    float opacity = 1.0f;
    int32_t ageRating = 0;
    std::string message;
    float posX = 0.0f;
    float posY = 0.0f;
};

src/stove/StoveSession.cpp 의 OnVietnamAgeRating() 이 콜백에서 값을 복사해요. 실패 결과는 베트남 사용자가 아니라는 뜻일 수 있으므로 조용히 돌아가요.

cpp
void StoveSession::OnVietnamAgeRating(const IStoveCallbackResult* r, const IStoveVietnamAgeRatingInfo* info)
{
    // 베트남 전용. 다른 국가 사용자는 NotSupportedCountry(31) 로 실패하며 이는 정상이다.
    if (!r->GetResult()->IsSuccessful())
        return;

    ageRating_.visible = (info->GetOverlayMode() == k_EStoveOverlayMode_Show);
    ageRating_.type = info->GetOverlayType();
    ageRating_.scale = info->GetOverlayScale();
    ageRating_.opacity = info->GetOverlayOpacity();
    ageRating_.ageRating = info->GetAgeRating();
    ageRating_.message = WideToUtf8(info->GetMsg());
    ageRating_.posX = info->GetDisplayPositionX();
    ageRating_.posY = info->GetDisplayPositionY();
}

visible 은 Show 일 때만 true 가 돼요. Hide 가 오면 false 가 되어 오버레이가 사라져요. 시간이 지났다고 게임이 임의로 숨기는 코드는 없어요.

연령등급 오버레이는 늘 보이는 것이 기본이에요. Hide 가 오기 전까지 게임이 임의로 숨기지 않아요.

과몰입 알림 (Stove_VietnamOverimmersionNotification)

연령등급 알림에 더해 다음 값이 함께 와요.

메서드(IStoveVietnamOverimmersionInfo)반환형설명
GetOverlayMode()int32_t오버레이 상태예요. Show(0)이면 타이머가 시작된 상태라 아직 표시하지 않아도 되고, Expanded(2)이면 오버레이를 펼쳐서 표시하고, Hide(1)이면 숨겨요.
GetOverlayType() · GetOverlayScale() · GetOverlayOpacity() · GetAgeRating()연령등급 정보와 같아요연령등급 정보의 같은 이름 메서드와 뜻이 같아요.
GetMsg()const wchar_t*과몰입 경고 메시지예요.
GetStyledMsg()const wchar_t*굵게 · 색상 같은 서식 태그(예: <b>, <color=#RRGGBBAA>)가 들어간 경고 메시지예요. 서식 있는 텍스트를 그릴 수 있으면 이 값을, 아니면 GetMsg() 를 써요.
GetElapsedMinutes()int32_t게임을 이용한 시간이에요. 분 단위예요.
GetExposureTime()int32_t메시지 노출 시간이에요. 초 단위예요. 이 시간이 지나면 오버레이를 숨겨요.
GetExpandAnimationTime()floatShow 에서 Expanded 로 바뀔 때 오버레이를 펼치는 애니메이션 시간이에요. 초 단위예요.
GetDisplayPositionX() · GetDisplayPositionY()float표시 위치예요. 화면 왼쪽 · 위쪽 기준 0.0 ~ 1.0 이에요.
GetLanguage()const wchar_t*글꼴을 고를 때 쓰는 언어 코드예요.

src/stove/StoveSession.h 의 OverimmersionOverlay 에는 남은 노출 시간(secondsLeft)이 더 들어 있어요.

cpp
// 베트남 과몰입 오버레이.
struct OverimmersionOverlay
{
    bool visible = false;
    int32_t type = 1;
    float scale = 1.0f;
    float opacity = 1.0f;
    std::string message;
    float secondsLeft = 0.0f;
    float posX = 0.0f;
    float posY = 0.0f;
};

OnVietnamOverimmersion() 은 오버레이 상태에 따라 3가지로 나눠요.

cpp
void StoveSession::OnVietnamOverimmersion(const IStoveCallbackResult* r, const IStoveVietnamOverimmersionInfo* info)
{
    if (!r->GetResult()->IsSuccessful())
        return;

    int32_t mode = info->GetOverlayMode();
    if (mode == k_EStoveOverlayMode_Expanded)
    {
        // 펼쳐서 표시하고, 노출 시간이 지나면 숨긴다.
        overimmersion_.visible = true;
        overimmersion_.type = info->GetOverlayType();
        overimmersion_.scale = info->GetOverlayScale();
        overimmersion_.opacity = info->GetOverlayOpacity();
        overimmersion_.message = WideToUtf8(info->GetMsg()); // 서식 있는 텍스트를 그릴 수 있으면 GetStyledMsg()
        overimmersion_.secondsLeft = static_cast<float>(info->GetExposureTime());
        overimmersion_.posX = info->GetDisplayPositionX();
        overimmersion_.posY = info->GetDisplayPositionY();
    }
    else if (mode == k_EStoveOverlayMode_Hide)
    {
        overimmersion_.visible = false;
    }
    // Show 는 타이머가 시작되었다는 뜻이라 아직 표시하지 않는다.
}

Brick Smash 의 그리기 코드는 서식 태그를 해석하지 못하는 ImGui 텍스트라서 GetMsg() 를 써요. 서식 있는 텍스트를 그릴 수 있는 UI 라면 GetStyledMsg() 를 쓰면 굵게나 색상이 적용된 문구를 그대로 보여 줄 수 있어요.

노출 시간 줄이기

Expanded 로 표시한 오버레이는 GetExposureTime() 초가 지나면 숨겨요. SDK 는 노출 시간 값만 알려 주므로, 남은 시간은 게임이 직접 세요. Brick Smash 는 Pump() 에서 Stove_RunCallback() 을 호출한 직후 매 프레임 경과 시간(dt)만큼 secondsLeft 를 줄여요. 이 Pump() 는 src/stove/StoveSession.cpp 에 있고 src/main.cpp 의 게임 루프가 매 프레임 호출해요.

cpp
void StoveSession::Pump(float dt)
{
    // 모든 비동기 콜백은 이 호출 안에서, 이 스레드에서 실행된다.
    Stove_RunCallback();

    if (notice_.secondsLeft > 0.0f && !notice_.blocksGame)
        notice_.secondsLeft -= dt;
    if (overimmersion_.visible && (overimmersion_.secondsLeft -= dt) <= 0.0f)
        overimmersion_.visible = false;
}

notice_ 는 한국용 셧다운 · 과몰입 안내에 쓰는 값이라 4장 에서 설명해요. 이 장에서 볼 부분은 overimmersion_ 을 줄이는 마지막 2줄이에요. 연령등급 오버레이는 시간이 없고 Hide 가 올 때까지 유지돼요.

오버레이 그리기

src/ui/RegulationOverlay.cpp 의 DrawBadge() 는 두 오버레이가 함께 쓰는 그리기 함수예요. 위치 비율에 화면 크기를 곱해 좌표를 구하고, 테마에 따라 배경과 글자 색을 정해요.

cpp
// 화면 비율 좌표(0.0~1.0, 왼쪽/위 기준)에 텍스트 박스를 그린다.
// type 0: 어두운 배경(33,33,33)+흰 글자 / type 1: 흰 배경+검은 글자
void DrawBadge(const char* text, int type, float scale, float opacity, float posX, float posY)
{
    ImDrawList* dl = ImGui::GetForegroundDrawList();
    ImVec2 screen = ImGui::GetIO().DisplaySize;
    float fontSize = ImGui::GetFontSize() * scale;
    ImVec2 sz = ImGui::GetFont()->CalcTextSizeA(fontSize, FLT_MAX, 0.0f, text);
    const float pad = 8.0f * scale;
    ImVec2 p0(screen.x * posX, screen.y * posY);
    ImVec2 p1(p0.x + sz.x + pad * 2, p0.y + sz.y + pad * 2);

    int a = static_cast<int>(opacity * 255.0f);
    ImU32 bg = type == 0 ? IM_COL32(33, 33, 33, a) : IM_COL32(255, 255, 255, a);
    ImU32 fg = type == 0 ? IM_COL32(255, 255, 255, a) : IM_COL32(0, 0, 0, a);
    dl->AddRectFilled(p0, p1, bg);
    dl->AddRect(p0, p1, fg);
    dl->AddText(ImGui::GetFont(), fontSize, ImVec2(p0.x + pad, p0.y + pad), fg, text);
}

GetForegroundDrawList() 로 그리므로 게임 UI 위에 항상 보여요. DrawRegulationOverlays() 는 매 프레임 두 오버레이의 visible 을 확인해서 그려요. 연령등급은 GetAgeRating() 값에 + 를 붙인 문구(예: 18+)를, 과몰입은 SDK 가 준 문구를 그대로 써요.

cpp
const AgeRatingOverlay& a = session.ageRating();
if (a.visible)
{
    std::string text = std::to_string(a.ageRating) + "+";
    DrawBadge(text.c_str(), a.type, a.scale, a.opacity, a.posX, a.posY);
}

const OverimmersionOverlay& o = session.overimmersion();
if (o.visible)
    DrawBadge(o.message.c_str(), o.type, o.scale, o.opacity, o.posX, o.posY);

주의할 점

베트남 서비스 게임은 연령등급 표시와 과몰입 알림을 모두 연동해야 해요. 하나만 연동하면 안 돼요.

두 함수는 한 번만 등록해요. 등록한 뒤에는 SDK 가 필요할 때마다 콜백을 여러 번 보내요. 콜백마다 다시 등록하지 않아요.

베트남이 아닌 국가의 사용자는 NotSupportedCountry(31)로 실패해요. 정상 동작이므로 오류 창을 띄우거나 게임을 막지 않아요.

화면을 그릴 수 있는 시점 이후에 등록해요. 과몰입 알림은 게임 시작 직후(경과 0분)에도 와요.

연령등급 오버레이는 Hide 가 오기 전까지 게임이 임의로 숨기지 않아요. 과몰입 오버레이는 GetExposureTime() 이 지나면 숨기고, Hide 가 오면 바로 숨겨요.

오버레이 문구는 SDK 가 내려 준 값(GetMsg() 또는 GetStyledMsg())을 그대로 써요. 게임이 문구를 바꾸거나 따로 만들지 않아요.

콜백으로 받은 정보 객체는 콜백이 끝나면 무효가 돼요. 오버레이를 그릴 때 필요한 값은 Brick Smash 처럼 콜백 안에서 복사해 둬요.

연령등급 표시 기준에 관해 궁금한 점은 기술지원으로 문의해 주세요.

연동 중에 막히는 부분이 있으면 기술지원으로 문의해 주세요.

메일문의 : store.support@smilegate.com