실제 적용 흐름이 궁금하신가요?

이용 시나리오 / 게임에서 구매하기

쿠폰

이해하기

스토브 플랫폼의 쿠폰 서비스를 연동하면, 스토브 파트너스에서 쿠폰을 발행해 게임·웹에서 이용자에게 아이템 등 보상을 지급할 수 있어요.
쿠폰은 사전 등록·콜라보·이벤트 보상, 마케팅 유입·전환 트래킹, CS 수동 보상 등에 활용해 이용자 리텐션을 높이는 데 쓰여요.

쿠폰 유형과 보상

쿠폰의 종류와 보상 구성을 함께 살펴보면 상황에 맞는 쿠폰을 고를 수 있어요.

상황에 맞는 쿠폰 유형을 먼저 골라보세요.

쿠폰 유형 선택 가이드

이용자가 코드를 직접 입력하나요?

쿠폰 유형에 따라 발급 방식과 이용자가 쿠폰을 받는 경험이 달라져요.

쿠폰 유형이 "누구에게 · 어떻게 나눠줄까"라면, 쿠폰 속성은 "무엇을 줄까"예요.
발행할 때는 유형을 먼저 정하고, 그다음 속성(보상)을 설정하는 순서예요.

"이럴 땐 이렇게" — 실제로 자주 쓰이는 조합이에요.

이럴 땐 이 조합

· SNS·콜라보로 아이템 뿌리기 → 대표(공용) 쿠폰 + 아이템

· 개인별 아이템 지급 / 사전등록 / CS 보상 → 일반 쿠폰 + 아이템

· 특정 이용자에게 아이템 바로 지급 (VIP·오류 보상) → 계정 지급 쿠폰 + 아이템

· 인게임 결제 할인 이벤트 → 일반 또는 대표(공용) 쿠폰 + 할인 (이용자는 결제창에서 사용)

· 크리에이터·홍보 이용자에게 게임이용권 지급 (체험 제공) → 계정 지급 쿠폰 + 게임이용권

설정별 화면 예시

쿠폰 유형과 세부 설정에 따라 이용자가 인게임에서 보는 화면과 경험이 달라져요.

쿠폰 발행 흐름

쿠폰을 발행하고 이용자에게 전달되기까지의 전체 흐름이에요.

1단계. 쿠폰 정보 설정

파트너스 [Billing > 쿠폰 관리 > 쿠폰 정보 설정]에서 쿠폰 유형·보상·대표 이미지 등을 입력해요.

ℹ️ 이 단계는 최초 1회만 설정하면 돼요. 한 번 설정해두면 이후 발행할 때마다 다시 할 필요가 없고, 유형·보상 등 설정을 바꾸고 싶을 때만 수정하면 돼요. 실제 쿠폰 발행은 2단계부터 반복돼요.

2단계. 쿠폰 발행

파트너스 [Billing > 쿠폰 관리 > 쿠폰 발행]에서 쿠폰 이름 등 기본 정보와 유형·속성을 설정해요.

3단계. 이용자 전달

이벤트·SNS·CS 등으로 코드를 전달하고, 계정 지급·다운로드 쿠폰은 자동 적재돼요.

이벤트 참여 보상 수령

4단계. 이용자 수령

인게임 쿠폰 입력창에서 등록하거나 쿠폰함에서 자동 확인하면 보상(아이템·할인)이 지급돼요.

인게임 쿠폰 등록 예시

플랫폼·채널별 노출 위치

개발하기

모바일 (SDK) - 쿠폰 사용

쿠폰 사용은 SDK가 제공하는 View.useCoupon 한 번의 호출로 끝나요. SDK가 STOVE ItemBox 서버에 사용 처리를 요청하고, 이후 게임 서버 콜백(아이템 지급)까지 이어지는 흐름을 처리해요. 쿠폰박스 리스트 검색·상세 조회·쿠폰박스 쿠폰 사용은 SDK가 아닌 서버 REST API 영역이라 서버 연동 - 아이템박스(Itembox) 섹션을 참고하세요.

사전 준비

• 이용자 로그인이 완료된 상태여야 해요.
• 파트너스에 팝업 정보가 등록되어 있어야 정상 동작해요. (직접 호출 페이지 방식 제외)

개발 흐름

1. 쿠폰 번호 수집 : 게임 내 쿠폰 입력 화면에서 이용자가 입력한 쿠폰 번호를 받아요.
2. 쿠폰 사용 호출 : View.useCoupon(context, code, callback)을 호출하면 SDK가 ItemBox 서버에 사용 처리를 진행해요.
3. 결과 처리 : 콜백으로 전달된 Result로 성공/실패를 분기해요. : 실패 시 OperationUI.HandleResult(result, ...)에 위임하면 SDK 공통 안내 화면이 노출돼요.

트러블슈팅

• ErrorCodes

  Domain	ErrorCode	Description	조치
  com.stove.server	100	PC방에서만 사용 가능한 쿠폰	사용 환경 안내 메시지를 노출하고 입력 화면을 유지하세요.
  com.stove.server	997	Not Verify AccessToken	Auth.accessToken을 다시 조회해 재호출하세요. 동일 오류가 지속되면 로그인 흐름으로 유도해 토큰을 재발급받게 하세요.
  com.stove.server	998	Expired AccessToken	로그인 흐름으로 유도해 토큰을 재발급받게 하세요.
  com.stove.server	999	System Error	—
  com.stove.server	2605	해당 멤버쉽 계정은 사용할 수 없습니다.	—
  com.stove.server	5031	일일 인증 횟수를 초과하였습니다.	안내 메시지를 노출하고 일정 시간 후 재시도하도록 유도하세요.
  com.stove.server	5105	잘못된 쿠폰 번호입니다.	쿠폰 번호 재확인 메시지를 노출하고 입력 화면을 초기화하세요.
  com.stove.server	5125	이미 사용한 쿠폰입니다.	입력 화면을 초기화하고 사용 완료 안내를 노출하세요.
  com.stove.server	5130	사용 중지된 쿠폰입니다.	—
  com.stove.server	5135	유효기간이 만료된 쿠폰입니다.	입력 화면을 초기화하고 만료 안내를 노출하세요.
  com.stove.server	5155	해당 쿠폰의 사용 가능 횟수를 초과하였습니다.	입력 화면을 초기화하고 안내 메시지를 노출하세요.
  com.stove.server	5161	등록 기간이 만료된 쿠폰입니다.	—
  com.stove.server	5162	해당 국가에서 사용할 수 없는 쿠폰입니다.	—
  com.stove.server	5164	해당 월드에서는 사용할 수 없는 쿠폰입니다.	—
  com.stove.server	5165	쿠폰함에서만 사용 가능한 쿠폰입니다.	—
  com.stove.server	5169	해당 쿠폰의 사용 기간이 아닙니다.	—
  com.stove.server	5200	해당 쿠폰에 대한 사용 대상이 아닙니다.	—
  com.stove.server	5202	이미 쿠폰함에 등록된 쿠폰입니다.	—
  com.stove.server	6002	해당 쿠폰번호를 더 이상 사용하실 수 없습니다.	—
  com.stove.server	6026	사용 횟수가 초과 되었습니다.	입력 화면을 초기화하고 안내 메시지를 노출하세요.

샘플 코드

public void UseCoupon()
{
    /**
     * code : 쿠폰 입력 (string)
     **/
    View.UseCoupon("code", (Result result) =>
    {
        if (result.IsSuccessful)
        {
        }
        else
        {
            OperationUI.HandleResult(result, (Result operationResult) =>
            {
                /** ex) 현재 화면 유지 **/
            });
        }
    });
}

PC (PCSDK) - 쿠폰 팝업

PCSDK ViewSDK가 제공하는 쿠폰 팝업 API를 사용하면 게임 클라이언트 안에서 스토브 쿠폰 입력 화면을 띄울 수 있어요. 이용자가 팝업에서 직접 쿠폰 번호를 입력하면 스토브가 사용 처리·아이템 지급 흐름을 진행해요.

사전 준비

• BaseSDK 초기화(Base_Initialize 또는 Base_InitializeEx)가 완료된 후 ViewSDK를 초기화(View_Initialize)하면 쿠폰 팝업 API를 사용할 수 있어요.
• 게임 루프에서 Base_RunCallback()이 주기적으로 호출돼야 비동기 콜백이 동작해요.
• 내장 WebView(WebViewMode::INTERNAL) 팝업을 사용한다면 View_Initialize 대신 View_InitializeWithWndInfo(mainWndHandle)에 게임 메인 HWND를 전달해 초기화해요.

개발 흐름

1. 초기화 : Base_Initialize(또는 Base_InitializeEx)로 BaseSDK 초기화를 완료한 뒤 View_Initialize()를 호출해요. 내장 WebView 팝업을 사용한다면 View_Initialize 대신 View_InitializeWithWndInfo(mainWndHandle)에 게임 메인 HWND를 전달해 초기화해요.
2. 쿠폰 팝업 호출 : 이용자가 쿠폰 입력 UI를 요청한 시점에 View_CouponPopup 또는 View_CouponPopupEx를 호출해요.
   • C/C++ : View_CouponPopup(mode, onFinished)를 호출해요. 팝업 종료 이벤트까지 받으려면 View_CouponPopupEx(mode, onFinished, onDestroy)를 사용해요. mode는 WebViewMode 값이에요.
   • C# : View_CouponPopup(mode, onFinished) 또는 View_CouponPopupEx(mode, onFinished, onDestroy)를 호출해요.
   • onFinished는 팝업 표시 완료 시점, onDestroy는 팝업의 네이티브 리소스가 완전히 정리된 시점에 호출돼요.
     
3. WebViewMode 선택 : mode에 WebViewMode::EXTERNAL(외부 브라우저) 또는 WebViewMode::INTERNAL(SDK 내장 WebView) 중 게임 환경에 맞는 모드를 설정해요. : Exclusive fullscreen 모드 게임은 반드시 WebViewMode::EXTERNAL을 사용해야 해요.
4. 종료 처리 : onDestroy 콜백을 받아 게임 흐름을 재개해요. 쿠폰 사용 후 인벤토리 새로고침이 필요하면 이 콜백 이후에 수행해요.
5. 정리 : 쿠폰 팝업 사용을 마치면 View_UnInitialize()로 ViewSDK를 정리하고, 게임 종료 직전 Base_UnInitialize()를 호출해요.

트러블슈팅

샘플 코드

#include "ViewSDK.h"

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

// 1) ViewSDK 초기화 (Base_Initialize 완료 이후)
auto initResult = View_Initialize();
if (!initResult.IsSuccessful())
{
    return;
}

// 2) 쿠폰 팝업 (Ex 버전: 종료 이벤트 수신)
View_CouponPopupEx(
    WebViewMode::EXTERNAL,
    [](CallbackResult openResult)
    {
        if (openResult.GetResult().IsSuccessful())
        {
            // 팝업 열림 처리
        }
    },
    [](CallbackResult destroyResult)
    {
        // 팝업 종료 시 게임 흐름 재개
    }
);

// 3) 종료 시 정리
View_UnInitialize();

서버 연동 - 아이템박스(Itembox)

이용자가 이벤트에 참여한 경우, 게임 서버는 보상 지급 요청을 수신하고 처리할 수 있도록 연동되어야 해요. 보상 지급 요청은 스토브의 아이템박스(ItemBox) 서버로부터 실시간 Callback 형태의 알림(Notification)으로 전달되며, 게임 서버는 해당 요청을 수신하여 적절한 지급 보상을 처리해주세요.

사전 준비

아래 항목이 사전에 파트너스를 통해 등록되어야 해요

1. 아이템박스 연동타입 선택: "Stove 서버에서 게임서버로 호출 (Transaction Id 포함)" 선택. 위치: 파트너스 > Launching > 서비스 연동 > SDK 실행 환경 설정

2. 기본 월드 등록: 월드가 필요없는 게임이라도 기본 월드를 지정해야 해요. (예: world_kr 등). 위치: 파트너스 > Launching > SDK 실행 환경(MO) > 월드/채널 정보 탭

3. 콜백 서버 URL 등록: 아이템 지급 요청을 수신할 콜백 서버 URL을 등록해요. 위치: 파트너스 > GM > 서비스 연동 > 아이템박스 연동 환경(mo)

Loop back URL 설정 방법
콜백 서버(URL)는 CP사에서 준비되어야 하지만, 준비 전이고 파트너스 테스트가 필요하면 아래 Loop back URL 설정으로 가능해요.
Sandbox: http://i-api.gate8.com/itembox/v2/item/inboundReward
ItemBox와 통신을 위해 ACL 작업이 필요해요. 스토브 플랫폼은 별도 서비스 오픈 정책이 필요하지 않으며, 게임서버만 필시 Inbound 오픈 작업을 해주세요.

아이템지급 API

CP사에서 제공되어야 하는 API 연동 규격에 대해 설명해요.

API 연동 정보

POST {파트너스 등록 URL 정보}
Content-Type: application/json

Request

• Body

• 암호화 전 msg payload

Response

게임서버는 ItemBox Call API에 대한 처리 결과를 하단에 명시된 return code를 활용하여 응답(application/json 형식)해야 해요. Content-Type : application/json

• Body

• Return Code

Sample

• Request
  • 암호화하지 않은 상태의 Request Body입니다. 실제 게임 서버로 전달 시 "msg" json value 부분이 암호화되어 전송됩니다.
    
  • 복호화 순서는 전달받은 msg data를 BASE64 Decoding 처리를 하고 AES256 Decryption처리를 하셔야 합니다.
  json

  {
      "msg_id": "baf84a85-abcc-49fc-ba85-54b7c38331e9",
      "msg" :
      {
          "game_id":"STOVE_GAME",
          "world_id":"world_global",
          "member_no": 503510,
          "nickname_no": 1603829809,
          "item_id": "ITEM_K001",
          "transaction_id":"6b384ab9d65f422db0abf186a7f79311",
          "service_type":"COUPON",
          "item_amt":3,
          "reward_msg":"사전등록 이벤트 참여 보상입니다",
          "end_dt":"20150116",
          "payload":
          {
              "item_period":0
          }
      },
      "timestamp": 1480512039
  }
  

• Response
  json

  - Content-Type : application/json
  {
      "return_code": 0,
      "return_message": "성공했습니다."
  }
  

복호화(decrypt) 과정

• 아이템박스 시스템과 게임 서버 간 요청에 대한 안정성과 유효성 검증을 위해 전송 시 일부 데이터(Json Data - msg values)를 암호화(Encrypted)하여 전송해요. 메시지 본문을 확인하기 위해서는 복호화(decrypt) 작업이 필요해요.
• 암호화(encrypt) 방식: AES256
• 복호화(decrypt) 키: Client Secret Key
• Transformation: AES/CBC/PKCS5Padding
• IV Spec: 'Client Secret Key' 값의 앞에서 16 자리
• 복호화 순서: 전달받은 msg data를 BASE64 Decoding 처리를 하고 AES256 Decryption 처리해야 해요.
• Secret Key 위치: 파트너스 > Launching > 서비스 연동 > 플랫폼 연동 키 > 모바일 서비스 연동 키 > 클라이언트 Secret Key

중복 지급 방어 처리

• transaction_id는 지급 요청이 발생하면 자동 생성되는 유니크한 값으로 게임 서버와 ItemBox 간의 아이템의 지급 누락 및
  중복 지급 방지 목적에 사용돼요.
• 게임 서버에서는 보상 지급에 성공한 경우 transaction_id를 게임 내 저장하여 중복 지급이 되지 않도록 관리해야 해요.
• 만약 ItemBox 서버에서 지급 완료된 transaction_id가 요청되면 게임 서버에서는 response Data "return_code"를 "0"으로 보내주면 돼요.

실패건에 대한 자동 재요청 발생

• STOVE ItemBox 서비스는 네트워크 장애/서버 오류 등으로 게임 서버 전송이 실패되면 실패 건에 대한 재전송(retry)을
  매 10분당 1번씩 최대 5회 수행해요. 이 경우 "msg" json의 "transaction_id"는 실패 건에 대한 구분키로 사용되므로 게임 서버에서
  "transaction_id"로 지급이 성공하여 처리한 건에 대해서는 저장하고 있어야 해요.
• 만약 게임 서버에서 지급 처리되었으나 회신 누락이나, 네트워크 오류로 인해 아이템박스 플랫폼에서 실패 처리된 경우,
  재 지급 요청이 발생할 수 있어요.

트러블슈팅

자주 묻는 질문