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

};

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

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.

<aside> 💡 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.

</aside>

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 */
}

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);
     }
}