This explains the basic integration flow from SDK initialization to shutdown.

SDK Basic Integration

Mobile SDK

This explains the basic flow for integrating the STOVE platform in the mobile environment (STOVE Mobile SDK).

Overview

• The STOVE platform provides an integrated service that makes game launches simple.
• Integrating the STOVE Mobile SDK (hereafter Mobile SDK) into your game lets you easily integrate authentication, operations, and payment features.
• The Mobile SDK can be used in 4 build environments: Android (Kotlin/Java), iOS, Unity, and Unreal.
• The Auth/AuthUI module handles integrated login, automatically processing device registration, identity verification, terms agreement, and push registration in a single AuthUI.login call.
• Detailed options for the full authentication/account-management flow (direct login, member conversion, manual identity-verification calls, etc.) are covered in the Sign-in Guide.

Prerequisites

Before proceeding with this guide, the items below must be ready.

Integration Flow

The Mobile SDK boot flow consists of 4 core calls and an automatic-processing area.

• Game-start path
  • When the app runs, initialize the SDK with Auth.initialize. This step also checks for app updates and game maintenance.
  • Register the authentication channels the game will support with AuthUI.setProviders. The order becomes the login-screen display order as-is.
  • Call AuthUI.login to show the integrated login screen and receive an AccessToken.
  • After login completes, pass the character/world info to the SDK with User.setGameProfile.

• Flow auto-processed inside AuthUI.login
  • A single integrated-login call also performs new-device registration, policy-required identity verification, terms agreement, and push registration.
  • The game doesn't need to call these directly. A separate call is needed only when re-showing them from in-game settings.

• During gameplay
  • Once character setup finishes, enter the game's main screen.
  • The SDK auto-renews the AccessToken at 80% of expiry, so don't cache the token—look it up via Auth.AccessToken each time.

Integration Details

This explains the 5 core steps of the Mobile SDK boot flow with step-by-step scenarios and code examples.

1. SDK Initialization (Auth.initialize)

This is the step that acquires the initial info needed to use the service. Login, payment, and operations features become usable only after initialization completes.

• Call conditions
  • Call once at app start.
  • It must be called before other Mobile SDK APIs.

• How it works
  • It fetches the service settings registered in Partners (service_id, market_game_id).
  • It also checks whether an app update is needed (AppUpdateError 30004) and whether the game is under maintenance (MaintenanceError 30003).
  • Passing the Result from the response directly to OperationUI.handleResult automatically shows the maintenance/app-update notice UI. (no need to handle it yourself)

• Sequence diagram

• Sample code
  • For the full per-platform sample code (Unity / Unreal / Android (Kotlin, Java) / iOS), see the Sign-in Guide — 1. Initialization (Auth.initialize) section.

2. Authentication-Channel Setup (AuthUI.setProviders)

Before calling AuthUI.login, register the authentication channels (Providers) the game will support. The order of the passed array becomes the login-screen display order as-is.

• Call conditions
  • Run it after Auth.initialize completes and before calling AuthUI.login.
  • Register once per game.

• How it works
  • Pass the list of Providers the game supports to the SDK.
  • Only channels pre-registered in Partners work correctly. Adding an unregistered channel won't authenticate at login.
  • The email Provider is shown by default without adding it separately. (login-screen type B requires the email Provider)

• Sample code
  • For the full per-platform sample code (Unity / Unreal / Android (Kotlin, Java) / iOS), see the Sign-in Guide — 2. Provider Setup (setProvider) section.

3. Integrated Login (AuthUI.login)

This is the step that handles everything at once—from showing the login screen to issuing the AccessToken and doing device registration, identity verification, terms agreement, and push registration.

• Call conditions
  • Call it after both Auth.initialize and AuthUI.setProviders complete.
  • If an existing AccessToken exists, it's handled as auto-login; otherwise the login screen is shown to the user.

• How it works
  • It shows the integrated-login UI and authenticates via the Provider the user selects.
  • After authentication, it issues/renews the AccessToken and delivers the user info via callback.
  • The items in the table below are all handled within a single call.

• Flow auto-processed inside AuthUI.login

• Sequence diagram

• Sample code
  • For the full per-platform sample code (Unity / Unreal / Android (Kotlin, Java) / iOS), see the Sign-in Guide — 3. Integrated Login (AuthUI.login) section.

4. Character/World Setup (User.setGameProfile)

After login completes, pass the user's character and world info to the SDK. The entered info is used per world/character in each feature (coupons/pop-ups/billing/push).

• Call conditions
  • Call it after AuthUI.login succeeds, right before entering the game's main page.
  • Call it again when the user changes character or connects to a different world.

• How it works
  • Create a GameProfile object with characterNumber and worldId and set it on AccessToken.user.
  • For games that don't support worlds, pass worldId as null. However, at least one default world must be registered in Partners.
  • The SDK doesn't check value validity (whether it's null), so please do a null check on the game side.

• Sample code
  • For the full per-platform sample code for world-supporting and non-world games, see the Sign-in Guide — 4. Character Setup (setGameProfile) section.

5. Using the AccessToken (Auth.AccessToken)

This is the step that looks up the token used when the game calls SDK features after character setup.

• Call conditions
  • Call it whenever an AccessToken is needed during gameplay.
  • Don't cache the token value in a game variable; look it up anew at each point of use.

• How it works
  • The SDK auto-renews when the AccessToken reaches 80% of its expiry time.
  • Auto-renewal only works while the process is running, so always get the latest value via Auth.AccessToken.
  • If the AccessToken is null, the login has been lost, so guide the user back to the login flow.

• Sample code
  • For the full per-platform sample code (Unity / Unreal / Android (Kotlin, Java) / iOS), see the Sign-in Guide — SDK Token Management section.

PC SDK

This explains the basic flow for integrating the STOVE platform in the PC environment (PCSDK3).

• The STOVE platform provides an integrated service that makes game launches simple.
• Integrating the STOVE PC SDK (hereafter PC SDK) into your game lets you easily integrate STOVE platform services.
• The STOVE PC Base SDK (hereafter Base SDK) is the required module that provides the basic features of STOVE platform services.

Prerequisites

Before proceeding with this guide, please first complete the Development Environment Setup process. The flow below can only proceed smoothly once the getting-started process is done.

Integration Flow

The Base SDK integration flow is as follows.

• Game-start path
  • At game start, verify whether the game was launched from the launcher.
  • At game start, initialize the Base SDK.
  • Configure the API-callback execution loop so that, each cycle when PC SDK APIs run, any callbacks queued in the callback queue are executed.

• Optionally implement to fit the game after configuring the API-callback execution loop
  • Set the language to use in the PC SDK.
  • Character/world setup (register the currently connected worldId and characterNumber to the PC SDK.)
  • Integrate the overindulgence-prevention feature.
  • Integrate the Game-Time Choice System feature.

• Features optionally usable during gameplay
  • Get the current user's Game Access token.
  • Get the current user's info.
  • Get the current user's GDS info.
  • Get the current user's Signin info.
  • Register a Game Access-token renewal-notification callback. (the token is auto-renewed inside the SDK, and the registered callback is called at renewal.)

• Game-exit path
  • When the user exits the game, clean up the Base SDK, then have the game finally exit.

Integration Details

This explains the typical scenario for integrating the Base SDK with sequence diagrams and code examples.

1. Launcher-Launch Verification and Base SDK Initialization

If the game is an official release build, first verify whether it was launched from the launcher, then initialize the Base SDK right away. Verification and initialization are bundled into one call flow.

• Call conditions
  • In an official release build, the game runs correctly only after verifying it was launched via the launcher.
  • Base SDK initialization must happen before other PC SDK module initialization.
  • Both APIs must be called on the UI Thread.
  • It must be called after game start and before using other Base SDK features.
  • It must run only once when the game launches. Don't repeat Init/UnInit during execution.

• How it works
  1. Launcher verification: Base_RestartAppIfNecessaryAsync handles verification asynchronously. The result is delivered via the callback's restartAppIfNecessary argument.
     • If restartAppIfNecessary is true, it means the game was relaunched via the launcher, so the current game instance must exit.
     • The timeout (milliseconds) for waiting on the launcher response is passed via the waitTimeMillisec argument of Base_RestartAppIfNecessaryAsync. Typically 60,000 (60 seconds) is used.
  2. Parameter cache: the initParam passed at the verification call is cached inside the SDK.
  3. Base SDK initialization: in the verification callback's restartAppIfNecessary == false branch, call Base_InitializeEx to initialize with the cached parameters. No need to pass parameters again.
     • If you use other modules such as View or IAP, call each module's initialization function (e.g., View_Initialize, IAP_Initialize) separately after Base SDK initialization. Other modules such as PCBang also follow their own initialization flows.

• Sequence diagram

• Code example

#include "BaseSDK.h"

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

void Base_RestartAppIfNecessaryAsync_Example()
{
    // Declared static since it's referenced in the callback
    static StovePCInitializeParam initParam;
    initParam.SetEnvironment(L"YOUR_ENV(ex.SANDBOX)");
    initParam.SetGameID(L"YOUR_GAME_ID");
    initParam.SetApplicationKey(L"YOUR_APP_KEY");

    // Call Base_RestartAppIfNecessaryAsync (60-second timeout)
    Base_RestartAppIfNecessaryAsync(&initParam, 60'000, [](
        CallbackResult callbackResult, bool restartAppIfNecessary)
    {
        if (restartAppIfNecessary)
        {
            // Relaunched via the launcher, so exit the current instance
            return;
        }

        // Verification passed → initialize the Base SDK with cached parameters (Base_InitializeEx)
        Base_InitializeEx([](CallbackResult initResult)
        {
            if (initResult.GetResult().IsSuccessful())
            {
                // Implement the logic for Base SDK initialization success.
                // e.g., you can run other SDK modules' Initialize here.
            }
            else
            {
                // Implement the logic for Base SDK initialization failure.
            }
        });
    });
}

2. API-Callback Execution

This is the step that executes callbacks registered on the PC SDK's async APIs. Registered callbacks are queued in the callback queue, and the queued callbacks are executed all at once when this API is called.

• Callbacks registered on PC SDK modules other than the Base SDK (View, IAP, PCBang, etc.) are also executed in this one function.
• If you don't call it periodically in the game's main loop, some PC SDK APIs may not work correctly.
• This API must be called on the UI Thread.

• Comparison of the two options

• Sequence diagram

• Code example

#include "BaseSDK.h"

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

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

        // Option A: execute all queued callbacks at once
        Base_RunCallback();

        // Option B: limit callback-execution time to a maximum of 10ms
        // If the time is exceeded, remaining callbacks continue on the next call
        // Base_RunCallbackWithTimeout(10);

        Render();
    }
}

3. Access-Token Lookup and Renewal-Notification Registration

The Access token used for STOVE platform authentication is automatically renewed inside the PCSDK 10 minutes before expiry. In game code, you can handle the token with two APIs.

• Comparison of the two APIs

• Sequence diagram

• Code example

#include "BaseSDK.h"

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

// (1) Register the renewal-notification callback - call once right after initialization
void Base_AccessTokenRenewed_Example()
{
    Base_AccessTokenRenewed(
        [](CallbackResult callbackResult, StovePCToken token)
        {
            if(callbackResult.GetResult().IsSuccessful())
            {
                // Implement follow-up processing after the Access token is auto-renewed.
                const wchar_t* renewed = token.GetAccessToken();
            }
            else
            {
                // Implement the logic for renewal failure.
            }
        }
    );
}

// (2) Immediately look up the current Access token - call right before each external call
void Base_GetAccessToken_Example()
{
    // Prepare a buffer large enough to receive the token.
    wchar_t accessToken[4096] = { 0 };
    auto result = Base_GetAccessToken(accessToken, 4096);
    if(result.IsSuccessful())
    {
        // The accessToken buffer is always filled with the latest token. Use it for external server calls, etc.
    }
    else
    {
        // Implement the logic for lookup failure.
    }
}

4. User/Country/Authentication Info Lookup

Info about the user currently logged in via the STOVE launcher is provided split across three APIs. Choose the API that fits your purpose—game screen, policy branching, judging payment eligibility, etc.

4-1. Base_GetUser — User basic info

Info provided by StovePCUser:

4-2. Base_GetGds — Access country/regulation/locale

GDS (Geo-based Distribution Service) is country/regulation/locale info based on the user's access IP. Used for per-region policy branching such as Vietnam regulation, shutdown, and terms-display language.

Info provided by StovePCGds:

4-3. Base_GetSignin — Login authentication info

Looks up the STOVE platform authentication context in which the game is currently running. You can check whether identity/email verification is done, the sign-up country, the IDP (Identity Provider) used, etc.

Info provided by StovePCSignin:

• Sequence diagram

• Code example

#include "BaseSDK.h"

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

// (1) Look up user basic info
void Base_GetUser_Example()
{
    StovePCUser user;
    auto result = Base_GetUser(&user);
    if(result.IsSuccessful())
    {
        const wchar_t* nickname = user.GetNickname();
        uint64_t gameUserId = user.GetGameUserId();
    }
}

// (2) Look up access country/regulation/locale
void Base_GetGds_Example()
{
    StovePCGds gds;
    auto result = Base_GetGds(&gds);
    if(result.IsSuccessful())
    {
        const wchar_t* nation = gds.GetNation();
        bool isDefault = gds.IsDefault();
        const wchar_t* regulation = gds.GetRegulation();
        const wchar_t* language = gds.GetLanguage();
        const wchar_t* timeZone = gds.GetTimeZone();
    }
}

// (3) Look up login authentication info
void Base_GetSignin_Example()
{
    StovePCSignin signin;
    auto result = Base_GetSignin(&signin);
    if(result.IsSuccessful())
    {
        const wchar_t* providerCode = signin.GetProviderCode();
        bool personVerify = signin.GetPersonVerify();
        bool emailVerify = signin.GetEmailVerify();
        const wchar_t* nationality = signin.GetNationality();
    }
}

5. Character/World Setup

Register the world identifier (worldId) and character identifier (characterNumber) the game is currently connected to into the PC SDK via the Base_SetGameProfile API. The registered identifiers are used as key values by payment/operations features to distinguish user context.

• Call conditions and cautions
  • Without setting character/world, some PC SDK modules such as payment (IAP) and coupons may not work correctly.
  • The SDK doesn't separately check input validity, so check for null/empty strings on the game side before calling.
  • The entered character/world info is valid for the PC SDK's lifecycle. If you reinitialize after Base_UnInitialize, you must call Base_SetGameProfile again.
  • When the context changes via the user changing character or moving worlds, call it again immediately to update the identifiers.

• Sequence diagram

• Code example

#include "BaseSDK.h"

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

// The function naming is an example; change it to fit your game's implementation.
void Base_SetGameProfile_Example()
{
    // Create the StovePCGameProfile struct
    // Assign appropriate worldId and characterNumber values to the struct fields.
    auto gameProfile = StovePCGameProfile(L"YOUR_WORLD_ID", 0L);

    // Call Base_SetGameProfile using the created struct
    auto result = Base_SetGameProfile(&gameProfile);
    if(result.IsSuccessful())
    {
        // Implement the logic for character/world setup success.
    }
    else
    {
        // Implement the logic for character/world setup failure.
    }
}

6. Base SDK Cleanup

Call the Base_UnInitialize API to clean up the Base SDK and return the resources in use. You must run the Base SDK cleanup logic before the game exits.

• Call conditions
  • Base SDK cleanup must happen last, after other PC SDK cleanup. Cleaning up the Base SDK before other PC SDK cleanup may leave it not cleaned up properly.
  • After cleaning up the Base SDK, you can't use Base SDK features.
  • Base SDK cleanup must be called on the UI Thread.
  • It must run only once when the game exits.

• Sequence diagram

• Code example

#include "BaseSDK.h"

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

void Base_UnInitialize_Example()
{
    // If you used other SDKs, Base_UnInitialize() must be called last.
    // e.g., cleanup order
    // PCBang_UserLogOut();
    // PCBang_UnInitialize();
    // View_UnInitialize();
    // IAP_UnInitialize();
    // Base_UnInitialize();
    auto result = Base_UnInitialize();
    if(result.IsSuccessful())
    {
        // Implement the logic for Base SDK cleanup success.
    }
    else
    {
        // Implement the logic for Base SDK cleanup failure.
    }
}