1. RunCallback
It processes PC SDK’s API mostly unsynchronized not to disturb the game engine and game logic.
It loads the result of the API call on the PC SDK’s internal queue. It executes the registered callback when the game calls the RunCallback method to process the result of the API call. Usually, the RunCallback method’s call is input through a coroutine, and you can set the call cycle.
private IEnumerator RunCallback(float intervalSeconds)
{
WaitForSeconds wfs = new WaitForSeconds(intervalSeconds);
while (true)
{
StovePC.RunCallback();
yield return wfs;
}
}
Plain Text
복사
A coroutine is started via the MonoBehaviour.StartCoroutine method and is usually a PC SDK initialization. It starts with success and stops if PC SDK shutdown succeeds. There is a way to use a member variable to stop the RunCallback coroutine after the successful PC SDK shutdown.
private Coroutine runcallbackCoroutine;
Plain Text
복사
You can operate the runcallbackCoroutine declared as a member variable in the game project like a timer by using the StartCoroutine and StopCoroutine functions as shown in the code below.
public void ToggleRunCallback_ValueChanged(bool isOn)
{
if (isOn)
{
float intervalSeconds = 1f;
runcallbackCoroutine = StartCoroutine(RunCallback(intervalSeconds));
WriteLog("RunCallback Start");
}
else
{
if (runcallbackCoroutine != null)
{
StopCoroutine(runcallbackCoroutine);
runcallbackCoroutine = null;
WriteLog("RunCallback Stop");
}
}
}
Plain Text
복사
2. Config, Callback Settings
To initialize PC SDK, start with filling in the values for the StovePCConfig and StovePCCallback structures and call the StovePC.Initialize method.
Refer to the code below to fill in each field value within the StovePCConfig structure.
StovePCConfig config = new StovePCConfig
{
Env = "live",
AppKey = "YOUR_APP_KEY",
AppSecret = "YOUR_SECRET_KEY",
GameId = "YOUR_GAME_ID",
LogLevel = StovePCLogLevel.Dubug,
LogPath = ""
};
Plain Text
복사
You must change "YOUR_APP_KEY", "YOUR_SECRET_KEY", and "YOUR_GAME_ID" to data with the key-value issued by STOVE Studio. If you call the StovePC.Initialize method without logging in to the stove launcher, an error occurs. Run the stove launcher before logging in.
Interworking between the game and the PC SDK uses a C# delegate. You must define delegate methods connected to the callbacks of the StovePCCallback class below for games.
public class StovePCCallback
{
// Callback called when errors occur in StovePCSDK
public StovePCErrorDelegate OnError;
// Callback called when the PC SDK initialization is complete
public StovePCInitializationCompleteDelegate OnInitializationComplete;
// Callback called when the GetToken process is complete
public StovePCTokenDelegate OnToken;
// Callback called when the GetUser process is complete
public StovePCUserDelegate OnUser;
// Callback called when the GetOwnership process is complete
public StovePCOwnershipDelegate OnOwnership;
}
Plain Text
복사
Be careful so that the StovePCCallback object is maintained until it terminates PC SDK. The PC SDK cannot internally call a callback if you collect the StovePCCallback object as garbage.
To satisfy this condition, you can define the StovePCCallback class as a member variable. To satisfy this point, you can solve this by declaring the StovePCCallback class as a member variable of the game project class to prevent garbage collection.
private StovePCCallback callback;
Plain Text
복사
// StovePCCallback class instance created
this.callback = new StovePCCallback
{
OnError = new StovePCErrorDelegate(this.OnError),
OnInitializationComplete = new StovePCInitializationCompleteDelegate(this.OnInitializationComplete),
OnToken = new StovePCTokenDelegate(this.OnToken),
OnUser = new StovePCUserDelegate(this.OnUser),
OnOwnership = new StovePCOwnershipDelegate(this.OnOwnership)
};
Plain Text
복사
The OnError, OnInitializationComplete 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, OnInitializationComplete,
connect only the OnOwnership callback additionally.
*/
this.callback = new StovePCCallback
{
OnError = new StovePCErrorDelegate(this.OnError),
OnInitializationComplete = new StovePCInitializationCompleteDelegate(this.OnInitializationComplete),
OnOwnership = new StovePCOwnershipDelegate(this.OnOwnership)
};
Plain Text
복사
3. SDK Initialization
Call the StovePC.Initialize method to initialize PC SDK.
StovePCResult sdkResult = StovePC.Initialize(config, this.callback);
if (StovePCResult.NoError == sdkResult)
{
this.runCallbackCoroutine = StartCoroutine(RunCallback(0.5f);
// Call RunCallback periodically due to no initialization errors
}
else
{
// Quit the game due to initialization failure
}
Plain Text
복사
After the StovePC.Initialize method 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 StovePCResult.NoError. In case of failure, it returns the corresponding error code, and you need to quit the game.
If the returned value is StovePCResult.NoError, therefore, a 'success', regularly call the StovePC.RunCallback method.
StovePC.RunCallback function must be regularly called to call the connected callback usually. The callback response speed slows down if the call cycle is long, so it is better to maintain an appropriate call cycle. In the example code, we set the callback function to be called once per second.
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.Initialize function processes unsynchronized procedures, excluding the config and callback validity check.
It calls the OnInitializationComplete callback if the unsynchronized procedures are successful. It calls the OnError callback if an error occurs.
You can check the error code and message through the delivered StovePCError structure in case of an error.
private void OnInitializationComplete()
{
Debug.Log("PC SDK initialization success");
}
private void OnError(StovePCError error)
{
#region Log
StringBuilder sb = new StringBuilder();
sb.AppendLine("OnError");
sb.AppendFormat(" - error.FunctionType : {0}" + Environment.NewLine, error.FunctionType.ToString());
sb.AppendFormat(" - error.Result : {0}" + Environment.NewLine, (int)error.Result);
sb.AppendFormat(" - error.Message : {0}" + Environment.NewLine, error.Message);
sb.AppendFormat(" - error.ExternalError : {0}", error.ExternalError.ToString());
WriteLog(sb.ToString());
#endregionswitch (error.FunctionType)
{
case StovePCFunctionType.Initialize:
case StovePCFunctionType.GetUser:
case StovePCFunctionType.GetOwnership:
BeginQuitAppDueToError();
break;
}
}
private void BeginQuitAppDueToError()
{
#region Log
StringBuilder sb = new StringBuilder();
sb.AppendLine("BeginQuitAppDueToError");
sb.AppendFormat(" - nothing");
WriteLog(sb.ToString());
#endregion// 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, erase QuitApplication here and 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.
QuitApplication();
}
Plain Text
복사
You can use the StovePC.GetInitializationState method if there is a need to check the initialized status value of PC SDK before the OnInitializationComplete callback is received.
//After calling the StovePC.Initialize
while (StovePC.GetInitializationState() == StovePCInitializationState.Pending)
{
Thread.Sleep(500);
StovePC.RunCallback();
}
if (StovePC.GetInitializationState() == StovePCInitializationState.Complete)
{
// The OnInitializationComplete callback is called when initialization is complete
}
else
{
// OnError callback is called when initialization has failed
}
Plain Text
복사
Call after you've finished using the PC SDK to clean up resources in use. After you call the StovePC.Uninitialize method, the API of the PC SDK does not work. Before or after reaching the StovePC.Uninitialize method, you must stop the runcallbackCoroutine execution with the StopCoroutine function.
StovePCResult result = StovePC.Uninitialize();
if (result == StovePCResult.NoError)
{
// Processed as a success
}
Plain Text
복사
4. Cautions when integrating the SDK
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 OnInitializationComplete to receive normal results.
When setting the log level of the FStovePCConfig structure, enter the value StovePCLogLevel.Debug for the Debug build. For the official build, please set StovePCLogLevel.Error to prevent unnecessary log creation.
5. SDK Termination
Call after you've finished using the PC SDK to clean up resources in use. After you call the StovePC.Uninitialize method, the API of the PC SDK does not work. Before or after reaching the StovePC.Uninitialize method, you must stop the runcallbackCoroutine execution with the StopCoroutine function.
StovePCResult result = StovePC.Uninitialize();
if (result == StovePCResult.NoError)
{
// Processed as a success
}
Plain Text
복사
6. Acquiring User Information
Use the StovePC.GetUser function to retrieve the logged-in user information in [STOVE Launcher] (https://www.onstove.com/download).
StovePCResult result = StovePC.GetUser();
if (result == StovePCResult.NoError)
{
// Processed as a success
}
Plain Text
복사
The OnUser callback is called when the StovePC.GetUser function is processed properly.
You can know the user's memberNo, Nickname, Game User ID information through the StovePCUser structure passed to the callback.
private void OnUser(StovePCUser user)
{
// Display user information
StringBuilder sb = new StringBuilder();
sb.AppendLine("OnUser");
sb.AppendFormat(" - user.MemberNo : {0}" + Environment.NewLine, user.MemberNo.ToString());
sb.AppendFormat(" - user.Nickname : {0}" + Environment.NewLine, user.Nickname);
sb.AppendFormat(" - user.GameUserId : {0}", user.GameUserId);
Debug.Log(sb.ToString());
}
Plain Text
복사
7. Acquiring Token Information
Get token information of the user who logged in to STOVE launcher with StovePC.GetToken method.
StovePCResult result = StovePC.GetToken();
if (result == StovePCResult.NoError)
{
// Processed as a success
}
Plain Text
복사
The OnToken callback is called when the StovePC.GetToken function is processed properly.
It contains the token string in the StovePCToken structure delivered to the callback.
private void OnToken(StovePCToken token)
{
// Display token information
StringBuilder sb = new StringBuilder();
sb.AppendLine("OnToken");
sb.AppendFormat(" - token.AccessToken : {0}", token.AccessToken);
Debug.Log(sb.ToString());
}
Plain Text
복사
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 STOVE Store Support for technical support.
8. Acquiring Ownership Information
Use the StovePC.GetOwnership method to check if the user owns the game through purchase.
StovePCResult result = StovePC.GetOwnership();
if (result == StovePCResult.NoError)
{
// Processed as a success
}
Plain Text
복사
The OnOwnership callback is called when the StovePC.GetOwnership function is processed properly.
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 22 to 27 is unnecessary.
private void OnOwnership(StovePCOwnership[] ownerships)
{
bool owned = false;
foreach(var ownership in ownerships)
{
// [LOGIN_USER_MEMBER_NO] StovePCUser structure’s MemberNo
// [OwnershipCode] 1: Having the ownership, 2: Ownership removed (Cancelling the purchase)
if (ownership.MemberNo != LOGIN_USER_MEMBER_NO ||
ownership.OwnershipCode != 1)
{
continue;
}
// [GameCode] 3: Package game, 4: DEMO
if (ownership.GameId == "YOUR_GAME_ID" &&
ownership.GameCode == 3)
{
owned = true; // Set ownership verification variable to true
}
// Required only for games selling DLC
if (ownership.GameId == "YOUR_DLC_ID" &&
ownership.GameCode == 5)
{
//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
}
}
Plain Text
복사
•
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."
•
Please add the log about the result of the ownership call after <GetOwnership Success>. (output_log.txt or Player.log)
For example :
Success: The user has ownership.
Failure: The user has no ownership
Plain Text
복사
•
Log File Activation Guide: https://docs.unity3d.com/530/Documentation/Manual/LogFiles.html(opens new window)
9. Set language
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. OnInitializationComplete).
StovePCResult result = StovePC.SetLanguage("LANGUAGE_CODE");
if (result == StovePCResult.NoError)
{
// handle success
}
Plain Text
복사
10. 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.
string translated = StovePC.TranslateLanguage("STRING_ID");
Plain Text
복사
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.