The PC SDK provides APIs to integrate additional services into games.
Additional services supported by PC SDK include custom event log, PC SDK version inquiry, over-immersion prevention notification, shutdown notification, tracking clue inquiry.
Games can send custom in-game events (game logs) to the Stove platform. Also, the game can query the semantic version of the PC SDK currently in use.
PC SDK semantic version inquiry can be obtained as a return value, not a callback.
The Over Immersion Prevention Alert delivers a warning phrase about over immersion in the game through a callback every hour.
Shutdown notification is a system that restricts children under the age of 18 from using the game at a specific time per day of the week by parents. When the requirements are met, notifications are delivered through callbacks up to 4 times.
1. Callback setting
In order to communicate with the PC SDK using the additional service API, the game must redefine the callback function connected to the UMyStovePCSDKObject class below.
UCLASS()
class HELLOSTOVE_API UMyStoveSDKObject : public UStoveSDKObject
{
GENERATED_BODY()
public:
//StovePCSDK Event
void OnInitComplete() final;
void OnError(FStoveError Error) final;
void OnToken(FStoveToken Token) final;
void OnUser(FStoveUser User) final;
void OnOwnership(int Size, FStoveOwnership* Ownerships) final;
//Callback called when StashCustomEvent processing is complete
void OnStashCustomEvent(FStoveCustomEvent CustomEvent, int ParameterSize, FStoveCustomEventParameter* Parameters) final;
// ADD 2.6.0 Start
// Callback that is called every hour to prevent over-immersion
void OnOverImmersion(FStoveOverImmersion OverImmersion) final;
// Callback to be called on shutdown limit
void OnShutdown(FStoveShutdown Shutdown) final;
// 2.6.0 End
}
Plain Text
복사
Link events by overriding the callback function of the 'UMyStoveSDKObject' class inherited from 'UStoveSDKObject' as in Connection 1) Config, Callback Settings.
/* In the case of using only the Ownership function,
In addition to the mandatory implementation callbacks OnError and OnInitComplete
Connect by implementing an additional OnOwnership callback.*/
void UMyStoveSDKObject::OnInitComplete()
{
// Process contents after successful initialization
}
void UMyStoveSDKObject::OnError(FStoveError Error)
{
// handling of errors
}
void UMyStoveSDKObject::OnOwnership(int Size, FStoveOwnership* Ownerships)
{
// Process details after checking ownership
}
void UMyStoveSDKObject::OnStashCustomEvent(FStoveCustomEvent CustomEvent, int ParameterSize, FStoveCustomEventParameter* Parameters)
{
// After sending the logs, check the delivered contents
}
// ADD 2.6.0 Start
void UMyStoveSDKObject::OnOverImmersion(FStoveOverImmersion OverImmersion)
{
// Callback that is called every hour to prevent over-immersion
}
void UMyStoveSDKObject::OnShutdown(FStoveShutdown Shutdown)
{
// Implement if selective shutdown is required by law.
}
// 2.6.0 End
Plain Text
복사
You are not required to implement the OnStashCustomEvent, OnOverImmersion, OnShutdown callbacks. You only need to connect if your game uses the custom event log feature.
Warning
The OnOverImmersion callback must be implemented in cases where game overimmersion/addiction precautions are required by law. The OnShutdown callback must be implemented if a selective shutdown is required by law.
2. Logging custom events
Log custom events (game logs) with UMyStoveSDKObject::StoveSDKStashCustomEvent function.
// input parameters
// const FString& Name: event name
// const FString& Category1: primary category name
// const FString& Category2 : 2nd category name
// const FString& SimpleValue : simple value
// const TArray<FStoveCustomEventParameter> Params: Detailed parameter information
// int paramsSize: Number of detailed parameter information
FStoveResult ErrorResult = UMyStoveSDKObject::StoveSDKStashCustomEvent("EVENT_NAME", "CATEGORY1", "CATEGORY2", 1.0f, params, PARAMS_SIZE);
if(ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
/* handle success */
}
Plain Text
복사
When the StoveSDKStashCustomEvent function is successfully processed, the OnStashCustomEvent callback is called.
The FStoveCustomEvent structure passed to the callback contains the event name passed when calling the API, the primary category name, the secondary category name, and a simple value.
The FStoveCustomEventParameter structure passed to the callback contains the parameter information passed when calling the API.
void UMyStoveSDKObject::OnStashCustomEvent(FStoveCustomEvent CustomEvent, int ParameterSize, FStoveCustomEventParameter* Parameters)
{
/*Add the 'walkthrough' codes here.*/
OnLog("[StashCustomEvent]");
OnLog(" - CustomEvent.Name : %s", *(CustomEvent.Name));
OnLog(" - CustomEvent.Category1 : %s", *(CustomEvent.Category1));
OnLog(" - CustomEvent.Category2 : %s", *(CustomEvent.Category2));
OnLog(" - CustomEvent.SimpleValue : %f", CustomEvent.SimpleValue);
for (int i = 0; i < ParameterSize; i++, Parameters++)
{
OnLog(" - Parameter[%d].Name : %s", i, *(Parameters->Name));
OnLog(" - Parameter[%d].Value : %s", i, *(Parameters->Value));
}
}
Plain Text
복사
Precautions
Callback Parameter The valid scope of FStoveCustomEvent/FStoveCustomEventParameter structure is limited to the callback function scope. PC SDK frees internally allocated memory as soon as callback function execution is completed.
Therefore, if you need to save the information of FStoveCustomEvent/FStoveCustomEventParameter structure outside the scope of the callback function, you must create a copy through deep copy, and when the use of the copy is complete, the memory must be freed.
3. Get PC SDK semantic version
Use the UMyStoveSDKObject::GetSDKVersion function to retrieve the version information of the PC SDK currently being integrated.
FString Version = UMyStoveSDKObject::StoveSDKGetSDKVersion();
if (Version.IsEmpty() == false)
{
/* handle success */
}
Plain Text
복사
4. Prevention of excessive immersion in games
The OnOverImmersion callback is called every hour after starting the game.
The FStoveOverImmersion structure passed to the callback contains the message, the elapsed time of using the game, and the minimum exposure time (in seconds) of the message.
The message is translated based on the language set in the PC SDK.
•
FStoveOverImmersion.Message: Overimmersion message
•
FStoveOverImmersion.ElapsedTimeInHours : elapsed time
•
FStoveOverImmersion.MinExposureTimeInSeconds : Minimum exposure time of message (in seconds)
void UMyStoveSDKObject::OnOverImmersion(FStoveOverImmersion OverImmersion)
{
OnLog("[OverImmersion]");
OnLog("- Message : %s", *(OverImmersion.Message));
OnLog("- ElapsedTimeInHours : %d", OverImmersion. ElapsedTimeInHours);
OnLog("- MinExposureTimeInSeconds : %d", OverImmersion.MinExposureTimeInSeconds);
// Guidance on preventing excessive immersion in games
}
Plain Text
복사
Guide to over-immersion messages
게임을 플레이한 지 1 시간이 지났습니다. 과도한 게임이용은 정상적인 일상생활에 지장을 줄 수 있습니다.
5. Shutdown
After starting the game, the OnShutdown callback is called based on the timetable registered in the shutdown system only for those subject to selective shutdown.
The OnShutdown callback can be called up to 4 times, and the time it is called and the actions to be taken in the game are as follows.
•
Shutdown event after successful PCSDK initialization
◦
Shutdown notification 10 minutes ago: Shows only notification that you will be logged out after 10 minutes
◦
Notification of shutdown 5 minutes ago: Shows only notification that you will be logged out after 5 minutes
◦
Shutdown notification 1 minute ago: Displays only notification that you will be logged out after 1 minute
◦
Shutdown Notification: Displays a notification that you will be logged out and ends the game immediately upon user confirmation
The FStoveShutdown structure passed to the callback contains the remaining time until shutdown, the message, and the message exposure time (seconds).
•
FStoveShutdown.InadvanceTimeInMinutes: The remaining time (minutes) until the user shuts down. If 0, the game ends immediately.
•
FStoveShutdown.Message : Shutdown notification message
•
FStoveShutdown.ExposureTimeInSeconds: message exposure time (seconds)
void UMyStoveSDKObject::OnShutdown(const FStoveShutdown Shutdown)
{
//print shutdown information
OnLog("[Shutdown]");
OnLog("- InAdvanceTimeInMinutes : %d", Shutdown. InAdvanceTimeInMinutes);
OnLog("- Message : %s", *(Shutdown.Message));
OnLog("- ExposureTimeInSeconds : %d", Shutdown. ExposureTimeInSeconds);
}
Plain Text
복사
Precautions
The valid scope of the callback parameter FStoveShutdown structure is limited to the scope of the callback function. PC SDK frees internally allocated memory as soon as callback function execution is completed. Therefore, if you need to save the information of the FStoveShutdown structure outside the scope of the callback function, you must create a copy through deep copy. When the use of the copy is complete, the memory must be freed.
Shutdown Message Information
10 minutes : 회원님은 게임 시간 선택제 적용 대상으로 10 분 후 게임 이용이 제한됩니다.
5 minutes : 회원님은 게임 시간 선택제 적용 대상으로 5 분 후 게임 이용이 제한됩니다.
1 minutes : 회원님은 게임 시간 선택제 적용 대상으로 1 분 후 게임 이용이 제한됩니다.
0 minutes : 회원님은 게임 시간 선택제 적용 대상으로 게임 이용이 제한되어 게임을 종료합니다.
6. Lookup Tracking Clues
The UMyStoveSDKObject::StoveSDKGetTraceHint function retrieves a set of clues for tracing the stove platform logs.
FStoveTraceHint TraceHint = UStoveSDKObject::StoveSDKGetTraceHint();
if (TraceHint.ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
OnLog("[GetTraceHint]");
OnLog(" - TraceHint.SessionId : %s", *(TraceHint.SessionId));
OnLog(" - TraceHint.RefSessionId : %s", *(TraceHint.RefSessionId));
OnLog(" - TraceHint.Uuid : %s", *(TraceHint.Uuid));
OnLog(" - TraceHint.ServiceProtocol : %s", *(TraceHint.ServiceProtocol));
OnLog(" - TraceHint.RefResourceType : %s", *(TraceHint.RefResourceType));
}
else
{
/* handle failure */
}
Plain Text
복사
The UStoveSDKObject::StoveSDKGetTraceHint function returns a FStoveTraceHint structure.
The returned FStoveTraceHint structure includes the session ID and reference session ID.
Also included are error codes for function calls.