•
StovePCSDK_Unreal uses Unreal Engine's UStoveSDKObject class which is an UObject type class. Here, we have redefined the data types, interfaces, and callback functions of the StovePCSDK library. Before integrating, use after inheriting the defined UStoveSDKObject of Plugin and configuring UMyStoveSDKObject in the game engine.
•
Prefix
There is a rule with Unreal Engine that the prefix U is added to the classes that inherit the UObject type.
We call the interface imported from the inherited UObject to the Plugin through Super.
•
SuperThe keyword provided by Unreal to call an inherited parent's function is Super.
FStoveResult UMyStoveSDKObject::StoveSDKInit(const FStoveConfig& fConfig)
{
FStoveResult fResult = Super::StoveSDKInit(fConfig);
}
C++
복사
For the Plugin environment configuration, refer to the Configuring the project environment, categories 1 to 3, in PC SDK Unreal Walkthrough
1. Config, Callback Settings
Suppose you wish to initialize the PC SDK. In that case, you must fill the FStoveConfig values and call the UStoveSDKObject::StoveSDKInit function of the inherited Actor.
Refer to the code below and fill in the field values of the FStoveConfig structures.
FStoveConfig fConfig{"LIVE",
"YOUR_APP_KEY",
"YOUR_SECRET_KEY",
"YOUR_GAME_ID",
StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG,
""};
C++
복사
For the description of the FStoveConfig structure, refer to the StoveSDKStruct.h file in the Plugins\StoveSDKPlugin\Source\StoveSDKPlugin\Public folder.
To call the API of the PC SDK in the game project and check the result, you need to use the callback function. The callback function used in the game project is as follows.
//StovePCSDK Callback
public:
void OnError(FStoveError Error) final;
void OnInitComplete() final;
void OnToken(FStoveToken Token) final;
void OnUser(FStoveUser User) final;
void OnOwnership(int Size, FStoveOwnership* Ownerships) final;
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 by defining it in the game project, as shown below.
/*As for when only using the Ownership function,
apart from the essential callbacks OnError, OnInitcomplte,
connect only the OnOwnership callback additionally.*/
void UMyStoveSDKObject::OnInitComplete()
{
// Process detail after successful initialization
}
void UMyStoveSDKObject::OnError(FStoveError Error)
{
// Process detail of the error
}
void UMyStoveSDKObject::OnOwnership(int Size, FStoveOwnership* Ownerships)
{
// Process detail after the viewing ownership
}
C++
복사
2. SDK Initialization
Before using the API of PC SDK, enter the initialization code as shown below in the UMyStoveSDKObject::StoveSDKInit function of MyStoveSDKObject.cpp for initialization.
FStoveResult UMyStoveSDKObject::StoveSDKInit(const FStoveConfig& Config)
{
FStoveResult ErrorResult = Super::StoveSDKInit(Config);
if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*StovePCSDK init Success*/
}
}
C++
복사
The UMyStoveSDKObject::StoveSDKInit function immediately returns the FStovePCResult enum type value after checking only the validity of config and callback.
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. For the entire list of error codes, refer to the StovePCDefine.h file.
The UMyStoveSDKObject::StoveSDKInit function handles other operations asynchronously, except config and callback validation.
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.
When you have completed the asynchronous operation, it calls the UMyStoveSDKObject::OnInitComplete callback. And it calls UMyStoveSDKObject::OnError callback when there is an error.
If an error occurs during initialization, you can check the error code and message through the StovePCError structure passed to the UMyStoveSDKObject::OnError function. The fError.result.result value of the StovePCError structure parameter is the same as the StovePCResult enum. So you can infer the error condition from the error code.
void UMyStoveSDKObject::OnInitComplete()
{
OnLog("[OnInitComplete]");
}
void UMyStoveSDKObject::OnError(const FStoveError& Error)
{
switch (Error.FunctionType)
{
case STOVE_PC_INIT:
case STOVE_PC_GET_USER:
case STOVE_PC_GET_OWNERSHIP:
QuitApplicationDueToError();
break;
}
}
void UMyStoveSDKObject::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");
FGenericPlatformMisc::RequestExit(false);
}
C++
복사
Before the UMyStoveSDKObject::OnInitComplete callback comes, if it is necessary to view the initialization state value of the PC SDK, you can use the UMyStoveSDKObject::GetInitState function.
/*After calling StovePC.Init..*/
while (Super::GetInitState().state
== StovePCInitState::STOVE_PC_INIT_PENDING)
{
FPlatformProcess::Sleep(0.5f);
RunCallback();
}
if (Super::GetInitState().state
== StovePCInitState::STOVE_PC_INIT_COMPLETE)
{
/*Initialization Complete
OnInitComplete callback is called*/
return FStoveResult{STOVE_PC_NO_ERROR};
}
else
{
/*Initialization failed
OnError callback is called*/
return FStoveResult{ STOVE_PC_NO_ERROR };;
}
C++
복사
3. Cautions when integrating the SDK
When setting the log level of the FStovePCConfig structure, which is a parameter of the StoveSDKInit function, enter the value StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG for the Debug build. For the official build, please set StovePCLogLevel::STOVE_PC_LOG_LEVEL_ERROR to prevent unnecessary log creation.
If the GetToken, GetUser, GetOwnership methods are called before initialization is complete, it may not return normal results. In other words, you must call the GetToken, GetUser, GetOwnership methods after receiving the callback of OnInitComplete to receive normal results.
4. SDK Termination
After using the PC SDK, call the StoveSDKUnInit function to clean up the resources in use. After reaching the StoveSDKUnInit function, the API of PC SDK does not work.
FStoveResult UMyStoveSDKObject::StoveSDKUnInit()
{
FStoveResult ErrorResult = Super::StoveSDKUnInit();
if (ErorrResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Success Process*/
}
return ErrorResult;
}
C++
복사
5/ Receive user information
Use the UMyStoveSDKObject::StoveSDKGetUser function to retrieve the logged-in user information in [STOVE Launcher] (https://www.onstove.com/download).
FStoveResult UMyStoveSDKObject::StoveSDKGetUser()
{
FStoveResult ErrorResult = Super::StoveSDKGetUser();
if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Success Process*/
}
return ErrorResult;
}
C++
복사
The UMyStoveSDKObject::OnUser callback is called when the UMyStoveSDKObject::StoveSDKGetUser function is processed properly.
You can know the user's memberNo, Nickname, Game User ID information through the StovePCUser structure passed to the callback.
void UMyStoveSDKObject::OnUser(FStoveUser User)
{
/*User Information Output*/
OnLog("[User]");
OnLog("MemberNo : %u", User.MemberNo);
OnLog("Nickname : %s", *(User.Nickname));
OnLog("GameUserId: %s", *(User.GameUserId));
}
C++
복사
6. Get Token Information
Get token information of the user who logged in to STOVE launcher with UMyStoveSDKObject::StoveSDKGetToken function.
FStoveResult UMyStoveSDKObject::StoveSDKGetToken()
{
FStoveResult ErrorResult = Super::StoveSDKGetToken();
if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Success Process*/
}
return ErrorResult;
}
C++
복사
The UMyStoveSDKObject::OnToken callback is called when the UMyStoveSDKObject::StoveSDKGetToken function is processed properly.
It contains the token string in the StovePCToken structure delivered to the callback.
void UMyStoveSDKObject::OnToken(FStoveToken Token)
{
/*Token Information Output*/
OnLog("AccessToken : %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. Get ownership information
With the UMyStoveSDKObject::StoveSDKGetOwnership function, you can inquire whether the user of the STOVE launcher has purchased and owns a game registered in STOVE Studio.
FStoveResult UMyStoveSDKObject::StoveSDKGetOwnership()
{
FStoveResult Result = Super::StoveSDKGetOwnership();
if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*Success Process*/
/*It delivers information about ownership to the OnOwnership callback.*/
}
return ErrorResult;
}
C++
복사
The UMyStoveSDKObject::OnOwnership callback is called when the UMyStoveSDKObject::StoveSDKGetOwnership function is processed properly.
For detailed information on the StovePCOwnership structure, refer to the StovePCDefine.h file.
Below is an example code that determines the purchase status of a game in the OnOwnership callback. If the game is without DLC, the confirmation code for lines 20 to 23 is unnecessary.
void UMyStoveSDKObject::OnOwnership(int size, FStoveOwnership* Ownership)
{
bool owned = false;
FStoveOwnership* data = fOwnership;
for (int i = 0; i < size; i++, data++)
{
if ((data->MemberNo != LOGIN_USER_MEMBER_NO /* StovePCUser Structural memberNo*/)
|| (data->OwnershipCode != 1 /* 1: Having the ownership, 2: Ownership removed (Cancelling the purchase)*/))
{
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
}
/*Required only for games selling DLC*/
if (0 == wcscmp(L"YOUR_DLC_ID", *(data->GameId)) && data->GameCode == 5 /* 5: DLC*/)
{
/*User owns YOUR_DLC_ID(DLC). allow DLC play*/
}
}
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++
복사
•
You can play the game after logging in to the STOVE launcher with the account that purchased the game (with ownership).
•
After logging in to the STOVE launcher with an account that does not own the game, the following guide message (example) is output when you execute the exe and then terminate the game.
◦
"Please log in to STOVE Client with the account that has purchased the game."
You don't need an account with game ownership to test the ownership feature.
8. Language translation
Translate languages with UMyStoveSDKObject::StoveSDKTranslateLanguage 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 implements the PC SDK popup UI directly, the string displayed in the UI must display the translated string through the UMyStoveSDKObject::StoveSDKTranslateLanguage function.
FString Translated=UMyStoveSDKObject::StoveSDKTranslateLanguage("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.