PC SDK provides API 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 define a callback function to connect to the callback pointer of the StovePCCallback structure below.
struct StovePCCallback
{
void(*OnError)(const StovePCError error);
void(*OnInitComplete)();
void(*OnToken)(const StovePCToken token);
void(*OnUser)(const StovePCUser user);
void(*OnOwnership)(int size, StovePCOwnership* ownership);
void(*OnAutoPopup)(int size, StovePCAutoPopup* autoPopup, int headerSize, StovePCPopupRequestHeader* header);
void(*OnManualPopup)(int size, StovePCManualPopup* manualPopup, int headerSize, StovePCPopupRequestHeader* header);
void(*OnNewsPopup)(StovePCNewsPopup newsPopup, int headerSize, StovePCPopupRequestHeader* header);
void(*OnCouponPopup)(StovePCCouponPopup couponPopup, int headerSize, StovePCPopupRequestHeader* header);
void(*OnCommunityPopup)(StovePCCommunityPopup communityPopup, int cookieSize, StovePCPopupRequestCookie* cookie);
// Callback called when StashCustomEvent processing is complete
void(*OnStashCustomEvent)(const StovePCCustomEvent customEvent, int parameterSize, StovePCCustomEventParameter* parameter);
// ADD 2.6.0 Start
// Callback that is called every hour to prevent over-immersion
void(*OnOverImmersion)(const StovePCOverImmersion overImmersion);
// Callback to be called on shutdown limit
void(*OnShutdown)(const StovePCShutdown shutdown);
// 2.6.0 End
};
C++
복사
Connect the callback function to the callback pointer of the StovePCCallback structure as in Connection 2) Config, Callback Settings.
// Create StovePCCallback structure instance
StovePCCallback callback;
// Initialize all function pointers to NULL
memset(&callback, 0, sizeof(StovePCCallback));
// Link implemented function pointers
callback.OnError = OnMyErrorCallback; /* Callback function defined globally */
callback.OnInitComplete = OnMyInitCompleteCallback; /* Callback function defined globally */
callback.OnToken = OnMyTokenCallback; /* Callback function defined globally */
callback.OnUser = OnMyUserInfoCallback; /* Callback function defined globally */
callback.OnOwnership = OnMyOwnershipCallback; /* Callback function defined globally */
// pop-up
callback.OnAutoPopup = OnMyAutoPopup; /* Callback function defined globally */
callback.OnManualPopup = OnMyManualPopup; /* Callback function defined globally */
callback.OnNewsPopup = OnMyNewsPopup; /* Callback function defined globally */
callback.OnCouponPopup = OnMyCouponPopup; /* Callback function defined globally */
callback.OnCommunityPopup = OnMyCommunityPopup; /* Callback function defined globally */
// Extra service
callback.OnStashCustomEvent = OnMyStashCustomEvent; /* Callback function defined globally */
// ADD 2.6.0 Start
callback.OnOverImmersion = OnMyOverImmersion; /* Callback function defined globally */
callback.OnShutdown = OnMyShutdown; /* Callback function defined globally */
// 2.6.0 End
C++
복사
You don't have to implement the OnStashCustomEvent callback. You only need to hook it up if your game uses the custom event logging feature.
Warning
The OnOverImmersion callback must be implemented if legally required to prevent overimmersion/addiction to games.
The OnShutdown callback must be implemented if a selective shutdown is required by law.
2. Logging custom events
Log custom events (game logs) with StovePC_StashCustomEvent function.
// input parameters
// const char* name: event name
// const char* category1 : primary category name
// const char* category2: 2nd category name
// const float simpleValue : simple value
// const StovePCCustomEventParameter* params: Detailed parameter information
// const int paramsSize: Number of detailed parameter information
StovePCResult result = StovePC_StashCustomEvent("EVENT_NAME", "CATEGORY1", "CATEGORY2", 1.0f, params, PARAMS_SIZE);
if(result == StovePCResult::STOVE_PC_NO_ERROR)
{
/* handle success */
}
C++
복사
When the StovePC_StashCustomEvent function is successfully processed, the OnStashCustomEvent callback is called.
The StovePCCustomEvent structure passed to the callback contains the event name, primary category name, secondary category name, and simple values passed when calling the API.
The StovePCCustomEventParameter structure passed to the callback contains the parameter information passed when calling the API.
void OnStashCustomEvent(const StovePCCustomEvent customEvent, int parameterSize, StovePCCustomEventParameter* parameter)
{
// Print all user-defined event information
printf("OnStashCustomEvent");
printf(" - customEvent.name : %s", customEvent.name);
printf(" - customEvent.category1 : %s", customEvent.category1);
printf(" - customEvent.category2: %s", customEvent.category2);
printf(" - customEvent.simpleValue: %f", customEvent.simpleValue);
printf(" - parameter size : %d", parameterSize);
for (int i = 0; i < parameterSize; i++, parameter++)
{
printf(" - parameter[%d].name : %s", i, parameter->name);
printf(" - parameter[%d].value : %s", i, parameter->value);
}
}
C++
복사
Precautions
Callback Parameter The valid scope of the StovePCCustomEvent/StovePCCustomEventParameter 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 saving is necessary to use the information of StovePCCustomEvent/StovePCCustomEventParameter structure outside the scope of the callback function, a copy must be created through deep copy, and
When the use of the copy is complete, the memory must be freed.
If an error occurs while running the StovePC_StashCustomEvent function, the OnError callback is called.
3. Get PC SDK semantic version
Use the StovePC_GetSDKVersion function to retrieve the version information of the currently interlocking PC SDK.
char* version = StovePC_GetSDKVersion();
if(0 != strcmp(version, ""))
{
/* handle success */
}
C++
복사
4. Prevention of excessive immersion in games 2.6.0
The OnOverImmersion callback is called every hour after starting the game.
The StovePCOverImmersion 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.
•
StovePCOverImmersion.message : Overimmersion message
•
StovePCOverImmersion.elapsedTimeInHours : Elapsed time
•
StovePCOverImmersion.minExposureTimeInSeconds : Minimum exposure time of message (in seconds)
The message is translated based on the language set in the PC SDK.
void OnOverImmersion(const StovePCOverImmersion overImmersion)
{
// output excessive immersion prevention information
printf("OnOverImmersion");
wprintf(L" - overImmersion.message : %s", overImmersion.message);
printf(" - overImmersion.elapsedTimeInHours: %d", overImmersion.elapsedTimeInHours);
printf(" - overImmersion.minExposureTimeInSeconds: %d", overImmersion.minExposureTimeInSeconds);
}
Plain Text
복사
Precautions
The valid scope of the callback parameter StovePCOverImmersion 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 information in the StovePCOverImmersion structure outside the scope of the callback function. You must create a copy through deep copy, and release the memory when the use of the copy is complete.
Guide to over-immersion messages
게임을 플레이한 지 1 시간이 지났습니다. 과도한 게임이용은 정상적인 일상생활에 지장을 줄 수 있습니다.
5. Shut down
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 StovePCShutdown structure passed to the callback contains the remaining time until shutdown, the message, and the message exposure time (seconds).
•
StovePCShutdown.inadvanceTimeInMinutes: The remaining time (minutes) until the user shuts down. If 0, the game ends immediately.
•
StovePCShutdown.message : Shutdown notification message
•
StovePCShutdown.exposureTimeInSeconds: message exposure time (seconds)
void OnShutdown(const StovePCShutdown shutdown)
{
// print shutdown information
printf("OnShutdown");
printf(" - shutdown.inadvanceTimeInMinutes: %d", shutdown.inadvanceTimeInMinutes);
wprintf(L" - shutdown.message : %s", shutdown.message);
printf(" - shutdown.exposureTimeInSeconds: %d", shutdown.exposureTimeInSeconds);
}
Plain Text
복사
Precautions
The valid scope of the callback parameter StovePCShutdown 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 store the information in the StovePCShutdown structure outside the scope of the callback function. You must create a copy through deep copy, and release the memory when the use of the copy is complete.
Shutdown Message Information
10 minutes : 회원님은 게임 시간 선택제 적용 대상으로 10 분 후 게임 이용이 제한됩니다.
5 minutes : 회원님은 게임 시간 선택제 적용 대상으로 5 분 후 게임 이용이 제한됩니다.
1 minutes : 회원님은 게임 시간 선택제 적용 대상으로 1 분 후 게임 이용이 제한됩니다.
0 minutes : 회원님은 게임 시간 선택제 적용 대상으로 게임 이용이 제한되어 게임을 종료합니다.
6. Tracking clue search
Retrieve a set of clues for tracing stove platform logs with StovePC.GetTraceHint function.
StovePCTraceHint traceHint = StovePC_GetTraceHint();
if (traceHint.result == StovePCResult::STOVE_PC_NO_ERROR)
{
printf("GetTraceHint");
printf(" - traceHint.sessionId : %s", traceHint.sessionId);
printf(" - traceHint.refSessionId : %s", traceHint.refSessionId);
printf(" - traceHint.uuid : %s", traceHint.uuid);
printf(" - traceHint.serviceProtocol : %s", traceHint.serviceProtocol);
printf(" - traceHint.refResourceType : %s", traceHint.refResourceType);
}
else
{
/* handle failure */
}
Plain Text
복사
The StovePC_GetTraceHint function returns a StovePCTraceHint structure.
The returned StovePCTraceHint structure includes the session ID and reference session ID.
Also, error codes for function calls are included.