- 마지막 업데이트
추가 연동
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_-])으로만 이루어져야 해요.
[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_FetchStat | k_EStoveGameSupportTypeKind_FetchStatParam | OnGetStatCallback | IStoveStat |
Stove_SetStat | k_EStoveGameSupportTypeKind_SetStatParam | OnSetStatCallback | IStoveSetStatOutcome |
Stove_FetchAchievement | k_EStoveGameSupportTypeKind_FetchAchievementParam | OnGetAchievementCallback | IStoveAchievement |
Stove_FetchAchievements | k_EStoveGameSupportTypeKind_FetchAchievementsParam | OnGetAchievementsCallback | IStoveAchievementList |
Stove_FetchRanking | k_EStoveGameSupportTypeKind_FetchRankingParam | OnGetRankingCallback | IStoveRanking |
예제 게임의 구조
Brick Smash 는 SDK 호출을 src/stove/StoveGameSupport.cpp 한 곳에 모아 두었어요. 헤더 src/stove/StoveGameSupport.h 는 함수 4개만 공개해요.
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 로 바뀌어요.
enum class AsyncStatus
{
Idle,
Loading,
Done,
Error,
};
화면은 status 가 Idle 일 때 한 번만 호출을 시작해요. 콜백은 Stove_RunCallback() 안에서 실행되므로 화면 코드와 같은 스레드예요. 잠금 없이 상태를 바꿔도 안전해요.
파라미터는 base_guard.h 의 StoveMakeParam<T>() 로 만들어요. 반환된 StoveGuard 가 범위를 벗어날 때 Destroy() 를 대신 호출해 줘요.
호출 순서
- 게임오버처럼 수치가 확정되는 때
Stove_SetStat()으로 스탯 값을 보내요. - 콜백의
IsUpdated()로 값이 실제로 바뀌었는지 확인해요. - 스탯 화면을 열 때
Stove_FetchStat()으로 현재 값을 조회해요. - 업적 화면을 열 때
Stove_FetchAchievements()로 목록을 조회해요. 하나만 필요하면Stove_FetchAchievement()를 써요. - 랭킹 화면을 열 때
Stove_FetchRanking()으로 원하는 페이지를 조회해요.
스탯 저장 (Stove_SetStat)
void Stove_SetStat(const IStoveSetStatParam* param, OnSetStatCallback onFinished, void* userData);
typedef void(__cdecl* OnSetStatCallback)(const IStoveCallbackResult* callbackResult, const IStoveSetStatOutcome* statOutcome);
| Setter | 형식 | 설명 |
|---|---|---|
SetStatsId | const wchar_t* | 바꿀 스탯 ID 예요. |
SetStatValue | int32_t | 스탯에 적용할 새 값이에요. 지정한 값으로 바뀌고 기존 값에 더해지지 않아요. |
메서드(IStoveSetStatOutcome) | 반환형 | 설명 |
|---|---|---|
IsUpdated() | bool | 스탯 값이 실제로 갱신되었으면 true 예요. |
GetCurrentValue() | int32_t | 갱신이 반영된 현재 값이에요. |
GetErrorMessage() | const wchar_t* | 값을 갱신하는 중에 문제가 있었다면 그 메시지예요. |
src/stove/StoveGameSupport.cpp 의 SetStat() 이에요.
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() 예요.
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)로 바꾸는 코드와 같은 자리에 있어서, 게임오버로 바뀌는 순간 한 번만 호출돼요.
// 방금 죽었으면 게임오버로 전환 + 스탯 등록(한 번만)
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)
void Stove_FetchStat(const IStoveFetchStatParam* param, OnGetStatCallback onFinished, void* userData);
typedef void(__cdecl* OnGetStatCallback)(const IStoveCallbackResult* callbackResult, const IStoveStat* stat);
| Setter | 형식 | 설명 |
|---|---|---|
SetStatsId | const wchar_t* | 조회할 스탯 ID 예요. 영문 대문자 · 숫자 · 밑줄 · 하이픈으로만 이루어져요. |
메서드(IStoveStat) | 반환형 | 설명 |
|---|---|---|
GetStatsFullId() | const IStoveStatFullId* | 스탯의 전체 식별 정보예요. GetGameId() 와 GetStatsId() 를 가져요. |
GetCurrentValue() | int32_t | 스탯의 현재 값이에요. |
GetUpdatedAt() | uint64_t | 마지막으로 갱신된 시각이에요. Unix epoch 밀리초예요. |
FetchStat() 과 콜백이에요.
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);
}
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 로 되돌려 다음 프레임에 다시 조회하게 해요.
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)
void Stove_FetchAchievements(const IStoveFetchAchievementsParam* param, OnGetAchievementsCallback onFinished, void* userData);
typedef void(__cdecl* OnGetAchievementsCallback)(const IStoveCallbackResult* callbackResult, const IStoveAchievementList* list);
| Setter | 형식 | 설명 |
|---|---|---|
SetPageSize | uint32_t | 한 페이지에 받을 업적 개수예요. 1 ~ 100 이에요. 설정하지 않거나 범위를 벗어나면 전체 목록을 한 번에 받아요. |
SetAchievementId | const 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() 는 파라미터에 아무 값도 넣지 않아서 전체 목록을 한 번에 받아요.
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 로 비교해 판단해요.
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)으로 그려요. 화면 아래에는 새로고침 버튼이 있어요.
if (ImGui::Button("새로고침"))
st.status = AsyncStatus::Idle;
게임오버 직후 곧바로 업적 화면을 열면 방금 달성한 업적이 아직 보이지 않을 수 있어요. 업적 평가는 서버에서 일어나고 반영이 즉시가 아닐 수 있으므로, 사용자가 다시 조회할 수 있게 새로고침 버튼을 두었어요.
페이지 단위로 받기
업적이 많으면 페이지 단위로 받을 수 있어요. Brick Smash 는 업적이 2개라 쓰지 않아요.
- 첫 호출은
SetPageSize(20)처럼 페이지 크기만 넣고AchievementId는 비워 둬요. - 콜백에서 받은 목록의 마지막 항목의
GetAchievementId()를 게임 쪽에 복사해 둬요. - 다음 페이지가 필요하면 같은 페이지 크기와 2번의 ID 를 넣어 다시 호출해요.
- 지금까지 받은 개수가
GetTotalCount()에 이르면 멈춰요.
업적 1개 조회 (Stove_FetchAchievement)
void Stove_FetchAchievement(const IStoveFetchAchievementParam* param, OnGetAchievementCallback onFinished, void* userData);
typedef void(__cdecl* OnGetAchievementCallback)(const IStoveCallbackResult* callbackResult, const IStoveAchievement* achievement);
| Setter | 형식 | 설명 |
|---|---|---|
SetAchievementId | const wchar_t* | 조회할 업적 ID 예요. |
콜백으로 오는 IStoveAchievement 는 위 업적 목록 조회의 표와 같아요. 예제는 목록 조회를 써요. 이 함수는 업적 하나의 진행 상태만 보여 주는 화면처럼 하나만 필요할 때 써요.
랭킹 조회 (Stove_FetchRanking)
void Stove_FetchRanking(const IStoveFetchRankingParam* rankParams, OnGetRankingCallback onFinished, void* userData);
typedef void(__cdecl* OnGetRankingCallback)(const IStoveCallbackResult* callbackResult, const IStoveRanking* ranking);
| Setter | 형식 | 설명 |
|---|---|---|
SetLeaderboardId | const wchar_t* | STOVE Studio 에서 만든 리더보드 ID 예요. |
SetPageIndex | uint32_t | 조회할 페이지 번호예요. 1부터 시작해요. |
SetPageSize | uint32_t | 한 페이지에 받을 순위 개수예요. 1 ~ 50 이에요. |
SetIncludeMyRank | bool | true 이면 결과의 첫 항목이 항상 로그인한 사용자 본인의 순위예요. |
메서드(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 | 현재 순위예요. |
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);
}
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 일 때 한 번만 조회하고 새로고침 버튼으로 다시 조회해요.
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() 가 성공한 뒤에 호출해요.
준비
- STOVE Studio 에서 인게임 상점을 등록해 샵 키를 받아요.
- 상품이 들어갈 카테고리와 판매할 상품을 STOVE Studio 에 등록해요. 등록이 끝나지 않으면 조회 함수가 빈 목록을 돌려줘요. Brick Smash 는 상점 화면을 확인할 테스트 상품 하나를 등록해요.
- 초기화 파라미터에
SetShopKey와SetMainWndHandle을 둘 다 넣어요. 자세한 초기화 순서는 2장 을 참고해요. - 결제 창은 SDK 가 WebView2 로 띄우므로 사용자 PC 에 WebView2 런타임이 필요해요.
Brick Smash 는 샵 키를 설정 파일(config/stove_config.ini)의 shop_key 에서 읽어요. 이 값을 비우면 상점과 보관함을 쓸 수 없어요.
[stove]
; 인게임 상점 ShopKey. 비워 두면 결제 기능을 초기화하지 않는다.
shop_key = YOUR_SHOP_KEY
src/stove/StoveSession.cpp 의 Initialize() 는 결제를 쓰기 때문에 샵 키와 메인 창 핸들을 모두 넣어요.
// 결제를 쓰므로 샵 키와 메인 창 핸들을 둘 다 넣는다. 결제가 없으면 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() 는 쓰지 않아요.
// 인게임 상점. 결제 창은 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장에서 설명한 것과 같은 방식으로 콜백 결과를 화면으로 넘겨요.
호출 순서
- 상점 화면을 열 때
Stove_FetchProducts()로 상품 목록을 받아요. 카테고리별 탭이 필요하면 먼저Stove_FetchShopCategories()로 카테고리를 받아요. - 사용자가 상품을 고르면
Stove_StartPurchase()로 구매를 시작해요. - 결제 방식(
Operation)에 따라 구매를 확정해요.WithWebViewAndConfirmResult: SDK 가 결제 창을 띄우고, 결제가 성공하면 확정까지 처리한 결과를Stove_StartPurchase()의 콜백으로 돌려줘요. 게임은Stove_ConfirmPurchase()를 호출하지 않아요.Default·WithWebView: 결제가 끝난 뒤 게임이Stove_ConfirmPurchase()를 직접 호출해야 구매가 완료돼요.
- 확정 결과로 받은 상품을 게임에서 지급해요.
- 게임을 시작할 때와 상점을 열 때
Stove_FetchInventory()로 구매 내역을 조회해, 아직 지급하지 않은 항목이 있으면 지급해요.
이 장은 가장 단순한 WithWebViewAndConfirmResult 방식을 기준으로 설명하고, 나머지 방식은 결제 진행 방식 에서 따로 설명해요.
상품 조회 (Stove_FetchProducts)
void Stove_FetchProducts(const IStoveFetchProductsParam* params, OnFetchProductsCallback onFinished, void* userData);
typedef void(__cdecl* OnFetchProductsCallback)(const IStoveCallbackResult* callbackResult, const IStoveProductList* list);
| Setter | 형식 | 설명 |
|---|---|---|
SetCategoryId | const wchar_t* | 카테고리 ID 예요. 비워 두면 모든 카테고리의 상품을 받아요. |
SetPageIndex | uint32_t | 페이지 번호예요. 1부터 시작해요. |
SetPageSize | uint32_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() 예요.
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 와 판매가)과 화면 표시용 값을 복사해 둬요.
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 는 상품을 카테고리로 나누지 않아서 이 함수를 쓰지 않아요. 상점에 탭이 필요한 게임을 위해 함수 모양과 메서드만 소개해요.
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)
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 | 설명 |
|---|---|---|---|
IStoveOrderProductParam | k_EStoveIAPTypeKind_OrderProductParam | SetProductId(int64_t) · SetSalePrice(double) · SetQuantity(int32_t) | 상품 1개분 주문 정보예요. 판매가는 상품 조회에서 받은 GetSalePrice() 값을 넣어요. 서버가 가격이 맞는지 확인하는 데 써요. |
IStovePurchaseParam | k_EStoveIAPTypeKind_PurchaseParam | SetOperation(int32_t) · SetWebViewMode(int32_t) · SetWebViewPosX · SetWebViewPosY · SetWebViewWidth · SetWebViewHeight(모두 int32_t, 픽셀) | 결제 진행 방식과 결제 창의 위치 · 크기예요. 위치 · 크기는 Operation 이 Default 가 아닐 때만 써요. |
IStoveStartPurchaseParam | k_EStoveIAPTypeKind_StartPurchaseParam | SetProducts(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() | bool | WithWebViewAndConfirmResult 에서 결제와 확정이 성공했으면 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개를 조립해서 호출해요.
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가지로 나눠요.
// 결제 + 확정 결과. 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 을 내려요.
// 이 호출로 열린 결제 창이 모두 닫혔을 때 온다.
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)
void Stove_ConfirmPurchase(const IStoveConfirmPurchaseParam* param, OnConfirmPurchaseCallback onFinished, void* userData);
typedef void(__cdecl* OnConfirmPurchaseCallback)(const IStoveCallbackResult* callbackResult, const IStoveConfirmPurchaseOutcome* outcome);
Operation 이 WithWebViewAndConfirmResult 가 아닌 구매를 확정하는 함수예요.
| Setter | 형식 | 설명 |
|---|---|---|
SetTxnMasterNo | int64_t | Stove_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 가 제공하지 않는 가상 함수예요. 거래 상세 번호로 중복 지급을 막는 지급 함수를 게임이 직접 구현해야 해요.
// 구매 시작 콜백에서 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)
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 을 넘겨요.
void StoveIAP::FetchInventory(InventoryState* out)
{
out->status = AsyncStatus::Loading;
Stove_FetchInventory(nullptr, OnFetchInventoryFinished, out);
}
콜백은 항목마다 거래 상세 번호, 상품 이름, 수량을 복사해요.
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())은 항목마다 상품 이름, 수량, 거래 상세 번호를 그대로 보여 줘요.
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() 은 샵 키가 비어 있으면 호출을 시도하지 않고 안내 문구만 보여 줘요.
if (ctx.cfg->shop_key.empty())
{
if (DrawHeader("상점"))
*ctx.current = AppScreen::Menu;
ImGui::TextUnformatted("shop_key 가 설정되지 않았어요. config/stove_config.ini 를 확인해 주세요.");
return;
}
구매 버튼은 결제 창이 열려 있거나 구매가 진행 중일 때 비활성으로 만들어서, 같은 상품을 연속으로 눌러 결제 창이 겹치는 일을 막아요. 이미 구매한 상품(HasPurchased())에는 버튼 대신 안내 문구를 보여 줘요.
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() 를 다시 호출해요.
// 구매 완료 배너 (상단)
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 을 넘겨요.
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)로 실패해요. 이 실패는 정상이에요. 다른 국가의 사용자에게는 오류로 안내하지 말고 조용히 무시해요.
호출 순서
- 창을 만든 뒤
Stove_Initialize()가 성공하면, 화면을 그릴 수 있는 상태이므로 곧바로 두 함수를 한 번씩 호출해요. - 게임 루프의
Stove_RunCallback()에서 콜백이 올 때마다 전달된 정보를 게임 쪽 변수로 복사해요. - 렌더링 코드가 복사해 둔 값으로 오버레이를 그려요.
- 노출 시간이 지난 오버레이는 게임이 매 프레임 시간을 줄여 가며 숨겨요.
베트남 함수 2개는 화면을 그릴 수 있는 시점 이후에 등록해요. 과몰입 알림은 게임을 시작한 직후(경과 0분)에도 한 번 오기 때문에, 그보다 먼저 등록하면 첫 안내를 화면에 띄우지 못해요. Brick Smash 는 창을 만든 뒤 초기화하므로
Initialize()안에서 바로 등록해요.
src/stove/StoveSession.cpp 의 Initialize() 끝부분이에요. 한국용 알림 2개(셧다운 · 과몰입)를 등록한 다음 베트남용 2개를 등록해요.
// 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() 으로 넘겨 줘요.
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 예요.
| 값 | 이름 | 뜻 |
|---|---|---|
| 0 | k_EStoveOverlayMode_Show | 오버레이를 표시해요. 과몰입 알림에서는 타이머가 시작된 상태라는 뜻이라 아직 표시하지 않아도 돼요. |
| 1 | k_EStoveOverlayMode_Hide | 오버레이를 숨겨요. |
| 2 | k_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 예요.
// 베트남 연령등급 오버레이. 콜백 밖에서 그리므로 값을 복사해 둔다.
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() 이 콜백에서 값을 복사해요. 실패 결과는 베트남 사용자가 아니라는 뜻일 수 있으므로 조용히 돌아가요.
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() | float | Show 에서 Expanded 로 바뀔 때 오버레이를 펼치는 애니메이션 시간이에요. 초 단위예요. |
GetDisplayPositionX() · GetDisplayPositionY() | float | 표시 위치예요. 화면 왼쪽 · 위쪽 기준 0.0 ~ 1.0 이에요. |
GetLanguage() | const wchar_t* | 글꼴을 고를 때 쓰는 언어 코드예요. |
src/stove/StoveSession.h 의 OverimmersionOverlay 에는 남은 노출 시간(secondsLeft)이 더 들어 있어요.
// 베트남 과몰입 오버레이.
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가지로 나눠요.
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 의 게임 루프가 매 프레임 호출해요.
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() 는 두 오버레이가 함께 쓰는 그리기 함수예요. 위치 비율에 화면 크기를 곱해 좌표를 구하고, 테마에 따라 배경과 글자 색을 정해요.
// 화면 비율 좌표(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 가 준 문구를 그대로 써요.
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