1. Config, Callback Settings
To initialize PC SDK, start with filling in the values for the StovePCConfig and StovePCCallback structures, and calling the StovePC_Init function.
Refer to the code below to fill in each field values within the StovePCConfig structure.
StovePCConfig config{"live",
"YOUR_APP_KEY",
"YOUR_SECRET_KEY",
"YOUR_GAME_ID",
StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG,
""};
C++
복사
Refer to the StovePCDefine.h file for details regarding the StovePCConfig structure.
Communication between the game and the PC SDK uses callback functions connected to the StovePCCallback structure. In the game code, you need to define the function pointer to connect to the callback pointer of the StovePCCallback structure below in advance. The pointer of the specified function should be connected.
struct StovePCCallback
{
/// Callback for StovePCSDK errors
void(*OnError)(const StovePCError error);
/// Callback for completing PC SDK initialization
void(*OnInitComplete)();
/// Callback for completing GetToken process
void(*OnToken)(const StovePCToken token);
/// Callback for completing GetUser process
void(*OnUser)(const StovePCUser user);
/// Callback for completing GetOwnership process
void(*OnOwnership)(int size, StovePCOwnership* ownership);
};
C++
복사
NULL initialization is required before using the StovePCCallback structure’s instance.
/* Create StovePCCallback structure instance*/
StovePCCallback callback;
/* Initialize all function pointers to NULL*/
memset(&callback, 0, sizeof(StovePCCallback));
/* Connect configured function pointers*/
callback.OnError = OnMyErrorCallback;
callback.OnInitComplete = OnMyInitCompleteCallback;
callback.OnToken = OnMyTokenCallback;
callback.OnUser = OnMyUserInfoCallback;
callback.OnOwnership = OnMyOwnershipCallback;
C++
복사
The OnError, OnInitComplete and OnOwnership callback functions must work together. You can integrate the rest of the callback functions only when necessary. For example, suppose you only use the Ownership function. In that case, you can implement it as shown below.
/*When only the ownership feature is being used,
only the OnOwnership callback is essential
On top of the essential callbacks, OnError and OnInitcomplte.*/
callback.OnError = OnMyErrorCallback;
callback.OnInitComplete = OnMyInitCompleteCallback;
callback.OnOwnership = OnMyOwnershipCallback;
C++
복사
2. SDK Initialization
When you complete StovePCConfig and StovePCCallback structure initialization and callback function connection, call the StovePC_Init function to initialize PC SDK.
StovePCResult result = StovePC_Init(config, callback);
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*StovePCSDK init success.
Call StovePC_RunCallback at regular intervals using timers, etc.*/
}
C++
복사
After the StovePC_Init function checks only the config and callback validity, it immediately returns the type value of the StovePCResult enum.
In case of success, it returns a value of STOVE_PC_NO_ERROR. In case of failure, it returns the corresponding error code, and you need to quit the game. Check the StovePCResult enum in the StovePCDefine.h file for a complete list of error codes.
If the returned value is STOVE_PC_NO_ERROR, therefore, a 'success', regularly call the StovePC_RunCallback function.
StovePC_RunCallback function must be regularly called to normally call the connected callback.
The callback response speed slows down if the call cycle is long, so it is better to maintain an appropriate call cycle. The example code in this guide sets the call period to 0.5 seconds.
Please be sure to write your code to call the StovePC_RunCallback function and other callback functions that work with the PCSDK from the main thread.
The StovePC_Init function processes unsynchronized procedures excluding the config and callback validity check.
The OnInitComplete callback is called if the unsynchronized procedures are successful, and the OnError callback is called if an error occurs.
In case of an error, the error code and message can be checked through the delivered StovePCError structure.
void OnInitComplete()
{
printf("pc sdk init success");
}
void OnError(const StovePCError error)
{
switch (Error.functionType)
{
case STOVE_PC_INIT:
case STOVE_PC_GET_USER:
case STOVE_PC_GET_OWNERSHIP:
QuitApplicationDueToError();
break;
}
}
void QuitApplicationDueToError()
{
// After showing the user a message about app outage rather than stopping it immediately
// Depending on user action (e.g. clicking the exit button), you may want to terminate the app.
// If so, implement your own logic.
// Recommended messages for required pre-task errors are as follows.
// Korean: The required pre-task failed to operate and the game has been terminated.
// Other Languages: The required pre-task fails and exits the game.
OnStoveLog("QuitApplicationDueToError");
OnStoveLog("QuitApplicationDueToError");
exit(0)
}
C++
복사
You can use the StovePC_GetInitState function if there is a need to check the initialized status value of PC SDK before the OnInitComplete callback is received.
/*After calling the StovePC_Init...*/
while(StovePC_GetInitState()
== StovePCInitState::STOVE_PC_INIT_PENDING)
{
sleep(500ms);
StovePC_RunCallback();
}
if (StovePC_GetInitState()
== StovePCInitState::STOVE_PC_INIT_COMPLETE)
{
/* Initialization Complete
OnInitComplete callback is called*/
}
else
{
/* Initialization failed
OnError callback is called*/
}
C++
복사
3. Cautions when synchronizing the SDK
When setting the log level of the StovePCConfig structure, set it as StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG value when testing, and set it as StovePCLogLevel::STOVE_PC_LOG_LEVEL_ERROR value at the time of official release.
Call the GetToken, GetUser, or GetOwnership functions before PC SDK initialization is complete. You may not receive the results usually. In other words, after the OnInitComplete callback is normally received, the GetToken, GetUser, and GetOwnership functions must be called to receive the result normally.
4. SDK Termination
After using PC SDK, call the StovePC_UnInit function to clean up resources in use.
StovePCResult result = StovePC_UnInit();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Processed as a success*/
}
...
C++
복사
5. Acquiring User Information
Use the StovePC_GetUser function to retrieve the logged-in user information in STOVE Launcher.
StovePCResult result = StovePC_GetUser();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Processed as a success*/
}
C++
복사
If the StovePC_GetUser function is normally processed, the OnUser callback is called.
The member no, nickname, Game User ID information can be viewed through the StovePCUser structure delivered by the callback.
We describe the StovePCUser structure in the StovePCDefine.h file.
void OnUser(const StovePCUser user)
{
/*Display User Information*/
printf("User Info(memberNo = %I64d, nickname = %S, gameUserId = %s)",
user.memberNo, user.nickname, user.gameUserId);
}
C++
복사
6. Acquiring Token Information
With the StovePC_GetToken function, you can check the token information of the user who has logged into the STOVE launcher.
StovePCResult result = StovePC_GetToken();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Processed as a success*/
}
C++
복사
If the StovePC_GetToken function is normally processed, the OnToken callback is called.
The StovePCToken structure delivered by the callback includes the token string.
void OnToken(const StovePCToken token)
{
/*Display Token Information*/
printf("Token : %s", token.accessToken);
}
C++
복사
What is a token?
It is the access token of the logged-in user in STOVE Launcher, and the game server passes this access token to the stove authentication server to validate the logged-in user. For a detailed explanation of Access Token, please get in touch with store.support@smilegate.com for technical support.
7. Acquiring Ownership Information
The StovePC_GetOwnership function lets you check whether the user has purchased and owns the game.
StovePCResult result = StovePC_GetOwnership();
if (result == STOVE_PC_NO_ERROR)
{
/*Processed as a success*/
/*Ownership information is delivered as the OnOwnership callback.*/
}
C++
복사
If the StovePC_GetOwnership function is normally processed, the OnOwnership callback is called.
For details on the StovePCOwnership structure, which is a parameter of the OnOwnership callback, refer to the StovePCDefine.h file.
The sample below is a code that checks if the game has been purchased through the OnOwnership callback. If the game is without DLC, the confirmation code for lines 20 to 23 is unnecessary.
void OnOwnership(int size, StovePCOwnership* ownership)
{
bool owned = false;
StovePCOwnership* data = ownership;
for (int i = 0; i < size; i++, data++)
{
if ((data->memberNo != LOGIN_USER_MEMBER_NO /*StovePCUser structure's memberNo*/)
|| (data->ownershipCode != 1 /*1:Ownership acquired, 2:Ownership disabled(in case the purchase has been canceled)*/))
{
continue;
}
if (0 == wcscmp(L"YOUR_GAME_ID", data->gameId) && data->gameCode == 3 /* 3: BASIC, 4: DEMO*/)
{
owned = true; // Set ownership verification variable to true
}
/*Necessary only if it is a game that has DLCs*/
if (0 == wcscmp(L"YOUR_DLC_ID", data->gameId) && data->gameCode == 5 /* 5: DLC*/)
{
/*Process for users who have purchased YOUR_DLC_ID(DLC)*/
}
}
if(owned)
{
// Write game entry logic after ownership verification is usually completed
}
else
{
// After ownership verification fails, end the game and write an error message display logic
}
}
C++
복사
•
After running the game exe, users who own the game can play.
•
Users who don't own the game cannot play, and please show the following message.
◦
"Please log in to STOVE Client with the account that has purchased the game."
8. Language Settings
Set the language with StovePC_SetLanguage function.
When initializing the PC SDK, the language is set as default using the system language (operating system language).
To explicitly set the system language (operating system language), enter "system" as a parameter.
To set a specific language, call the StovePC_SetLanguage function after successful initialization (e.g. OnInitComplete).
StovePCResult result = StovePC_SetLanguage("LANGUAGE_CODE");
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
/* handle success */
}
C++
복사
9. Language translation
Translate languages with StovePC_TranslateLanguage function.
PC SDK provides a translation for a specific string based on the set language information.
A specific string is managed as a String ID managed by the PC SDK.
If the game directly implements the PC SDK popup UI, the string displayed in the UI must display the translated string through the StovePC_TranslateLanguage function.
wchar_t* translated = StovePC_TranslateLanguage("STRING_ID");
C++
복사
Precautions
Returns an English translation if there is no translation of a specific string for the language set in the PC SDK.
For exceptions or unsupported string IDs, the input parameter (string ID) is returned as it is.
