PC SDK provides API to integrate the Stove platform’s game support service into the game. The game support service supported by the PC SDK includes stats, achievements, and leaderboards. Each service is defined as follows:
•
Stats: A service that records the user’s various gameplay data in numerical terms
•
Achievements: A service that sets gameplay challenges and provides user-specific achievement information
•
Leaderboard: A service that provides user ranking information of specific gameplay data
To use the API for PC SDK game support service, you need to first conduct metadata registration for game support services through the studio.
1. Callback Settings
To communicate with the PC SDK using the game support service API, you must define a class callback delegation method in the game to connect to the callback of the StovePCCallback class below.
public class StovePCCallback
{
public StovePCErrorDelegate OnError;
public StovePCInitializationCompleteDelegate OnInitializationComplete;
public StovePCTokenDelegate OnToken;
public StovePCUserDelegate OnUser;
public StovePCOwnershipDelegate OnOwnership;
// It calls the callback when you have completed GetStat.
public StovePCStatDelegate OnStat;
// It calls the callback when you have completed SetStat.
public StovePCSetStatDelegate OnSetStat;
// It calls the callback when you have completed GetAchievement.
public StovePCAchievementDelegate OnAchievement;
// It calls the callback when you have completed GetAllAchievement.
public StovePCAllAchievementDelegate OnAllAchievement;
// It calls the callback when you have completed GetRank.
public StovePCRankDelegate OnRank;
}
Plain Text
복사
Connect the callback delegation to the callback of the StovePCCallback class as in Integration 2) Config, Callback Settings.
// Create instance of the StovePCCallback class
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),
// Game support service
OnStat = new StovePCStatDelegate(this.OnStat),
OnSetStat = new StovePCSetStatDelegate(this.OnSetStat),
OnAchievement = new StovePCAchievementDelegate(this.OnAchievement),
OnAllAchievement = new StovePCAllAchievementDelegate(this.OnAllAchievement),
OnRank = new StovePCRankDelegate(this.OnRank)
};
Plain Text
복사
You do not need to implement callbacks other than OnStat, OnSetStat, OnAchievement, OnAllAchievement, and OnRank.
You only need to implement and connect the callback methods required for the game support service used by the game.
2. Update User Stats
Update specific stats in the game for a logged-in user with the StovePC.SetStat method.
// Input parameters
// string statId : Stat identifier registered in the studio
// int statValue : Stat value to be updated
StovePCResult result = StovePC.SetStat("STAT_ID", STAT_VALUE);
if(result == StovePCResult.NoError)
{
// Processed as a success
}
Plain Text
복사
When the StovePC.SetStat function is processed properly, the OnSetStat callback is called.
The StovePCStatValue structure delivered to the callback contains a flag indicating the current stat value, update status, and error messages.
Suppose it fully reflects and updates the stat value. In that case, the Updated field will contain ‘true’, and the ErrorMessage field will have an empty string. If the stat value is partially updated, the Updated field will contain ‘true’. The ErrorMessage field will contain a string such as “integer overflow”.
For example, you are assuming that the current stat value of the INCREMENT type is 2,147,483,000. You try to add 1,000 through the StovePC.SetStat API. It will become out of range of the values that the Int32 type can have. When it updates to 2,147,483,647, the maximum value of the Int32 type, reflecting only part of the value (1,000), the ErrorMessage field will contain a string such as “integer overflow”.
The table below lists the results that can obtain through the StovePCStatValue structure.
Stat Type | Updated | ErrorMessage | Result |
All Types | True | “”(Empty string) | Requested value is fully updated to current value |
INCREMENT | True | "integer overflow" | Storage space exceeded, partial update |
INCREMENT | False | "integer overflow" | Storage space exceeded, no update |
MIN | False | “”(Empty string) | Requested value larger than current value |
MAX | False | “”(Empty string) | Requested value smaller than current value |
REPLACE | False | “”(Empty string) | Requested value same as current value |
private void OnSetStat(StovePCStatValue statValue)
{
// Display stat update result information
StringBuilder sb = new StringBuilder();
sb.AppendLine("OnSetStat");
sb.AppendFormat(" - statValue.CurrentValue : {0}" + Environment.NewLine, statValue.CurrentValue.ToString());
sb.AppendFormat(" - statValue.Updated : {0}" + Environment.NewLine, statValue.Updated.ToString());
sb.AppendFormat(" - statValue.ErrorMessage : {0}", statValue.ErrorMessage);
Debug.Log(sb.ToString());
}
Plain Text
복사
When the StovePC.SetStat method is running, if an error occurs, the OnError callback is called.
You can check for external errors through the ExternalError field of the StovePCError structure.
ExternalError | Description |
2000 | Invalid Access |
3000 | Wrong API Usage |
4000 | Stats ID Not Found |
9000 | Service Error |
3. Get User Stat Information
Use the StovePC.GetStat function to retrieve specific game stat information for a logged-in user.
// Input parameters
// string statId : Stat identifier registered in the studio
StovePCResult result = StovePC.GetStat("STAT_ID");
if(result == StovePCResult.NoError)
{
// Processed as a success
}
Plain Text
복사
1234567
When the StovePC.GetStat method is processed correctly, it calls the OnStat callback.
The StovePCStat structure delivered to the callback contains the current stat value.
private void OnStat(StovePCStat stat)
{
// Display stat info
StringBuilder sb = new StringBuilder();
sb.AppendLine("OnStat");
sb.AppendFormat(" - stat.StatFullId.GameId : {0}" + Environment.NewLine, stat.StatFullId.GameId);
sb.AppendFormat(" - stat.StatFullId.StatId : {0}" + Environment.NewLine, stat.StatFullId.StatId);
sb.AppendFormat(" - stat.MemberNo : {0}" + Environment.NewLine, stat.MemberNo.ToString());
sb.AppendFormat(" - stat.CurrentValue : {0}" + Environment.NewLine, stat.CurrentValue.ToString());
sb.AppendFormat(" - stat.UpdatedAt : {0}", stat.UpdatedAt.ToString());
Debug.Log(sb.ToString());
}
Plain Text
복사
12345678910111213
If an error occurs while the StovePC.GetStat method is running, if an error occurs, the OnError callback is called.
You can check for external errors through the ExternalError field of the StovePCError structure.
ExternalError | Description |
2000 | Invalid Access |
3000 | Wrong API Usage |
4000 | Stats ID Not Found |
9000 | Service Error |
#4) Get User Single Achievement Information
Use the StovePC.GetAchievement method to retrieve specific game single achievement information for a logged-in user.
// Input parameters
// string achievementId : Achievement identifier created in the studio
StovePCResult result = StovePC.GetAchievement("ACHIEVEMENT_ID");
if(result == StovePCResult.NoError)
{
// Processed as a success
}
Plain Text
복사
1234567
When the StovePC.GetAchievement method is processed correctly, it calls the OnAchievement callback.
The StovePCAchievement structure delivered to the callback contains the current achievement value, status, and achievement metadata.
private void OnAchievement(StovePCAchievement achievement)
{
// Display single achievement information
StringBuilder sb = new StringBuilder();
sb.AppendLine("OnAchievement");
sb.AppendFormat(" - achievement.AchievementId : {0}" + Environment.NewLine, achievement.AchievementId);
sb.AppendFormat(" - achievement.Name : {0}" + Environment.NewLine, achievement.Name);
sb.AppendFormat(" - achievement.Description : {0}" + Environment.NewLine, achievement.Description);
sb.AppendFormat(" - achievement.DefaultImage : {0}" + Environment.NewLine, achievement.DefaultImage);
sb.AppendFormat(" - achievement.AchievedImage : {0}" + Environment.NewLine, achievement.AchievedImage);
sb.AppendFormat(" - achievement.Condition.GoalValue : {0}" + Environment.NewLine, achievement.Condition.GoalValue.ToString());
sb.AppendFormat(" - achievement.Condition.ValueOperation : {0}" + Environment.NewLine, achievement.Condition.ValueOperation);
sb.AppendFormat(" - achievement.Condition.Type : {0}" + Environment.NewLine, achievement.Condition.Type);
sb.AppendFormat(" - achievement.Value : {0}" + Environment.NewLine, achievement.Value.ToString());
sb.AppendFormat(" - achievement.Status : {0}", achievement.Status);
Debug.Log(sb.ToString());
}
Plain Text
복사
123456789101112131415161718
If an error occurs while the StovePC.GetAchievement method is running, if an error occurs, the OnError callback is called.
You can check for external errors through the ExternalError field of the StovePCError structure.
ExternalError | Description |
1200 | Not found achievement |
9000 | Service error |
#5) Get All User Achievement Information
Use the StovePC.GetAllAchievement method to retrieve specific game single achievement information for a logged-in user.
StovePCResult result = StovePC.GetAllAchievement();
if(result == StovePCResult.NoError)
{
// Processed as a success
}
Plain Text
복사
12345
When the StovePC.GetAllAchievement method is processed correctly, it calls the OnAllAchievement callback.
The StovePCAchievement structure delivered to the callback contains the current achievement value, status, and achievement metadata.
private void OnAchievement(StovePCAchievement[] achievements)
{
// Display all achievement information
StringBuilder sb = new StringBuilder();
sb.AppendLine("OnAllAchievement");
sb.AppendFormat(" - achievements.Length : {0}" + Environment.NewLine, achievements.Length);
for (int i = 0; i < achievements.Length; i++)
{
sb.AppendFormat(" - achievements[{0}].AchievementId : {1}" + Environment.NewLine, i, achievements[i].AchievementId);
sb.AppendFormat(" - achievements[{0}].Name : {1}" + Environment.NewLine, i, achievements[i].Name);
sb.AppendFormat(" - achievements[{0}].Description : {1}" + Environment.NewLine, i, achievements[i].Description);
sb.AppendFormat(" - achievements[{0}].DefaultImage : {1}" + Environment.NewLine, i, achievements[i].DefaultImage);
sb.AppendFormat(" - achievements[{0}].AchievedImage : {1}" + Environment.NewLine, i, achievements[i].AchievedImage);
sb.AppendFormat(" - achievements[{0}].Condition.GoalValue : {1}" + Environment.NewLine, i, achievements[i].Condition.GoalValue.ToString());
sb.AppendFormat(" - achievements[{0}].Condition.ValueOperation : {1}" + Environment.NewLine, i, achievements[i].Condition.ValueOperation);
sb.AppendFormat(" - achievements[{0}].Condition.Type : {1}" + Environment.NewLine, i, achievements[i].Condition.Type);
sb.AppendFormat(" - achievements[{0}].Value : {1}" + Environment.NewLine, i, achievements[i].Value.ToString());
sb.AppendFormat(" - achievements[{0}].Status : {1}", i, achievements[i].Status);
if (i < achievements.Length - 1)
sb.AppendFormat(Environment.NewLine);
}
Debug.Log(sb.ToString());
}
Plain Text
복사
1234567891011121314151617181920212223242526
If an error occurs while the StovePC.GetAchievement method is running, the OnError callback is called.
You can check for external errors through the ExternalError field of the StovePCError structure.
ExternalError | Description |
9000 | Service error |
#6) Get Leaderboard Ranking Information
Use the StovePC.GetRank method to retrieve the ranking information of a specific game leaderboard.
// Input parameters
// string leaderboardId : Leaderboard identifier created in the studio
// uint pageIndex : Page number to search (1 <= pageIndex)
// uint pageSize : Number of ranks to search (1 <= pageSize <= 50)
// bool includeMyRank : Include rank of logged-in users in search results
StovePCResult result = StovePC.GetRank("LEADERBOARD_ID", PAGE_INDEX, PAGE_SIZE, INCLUDE_MY_RANK);
if(result == StovePCResult.NoError)
{
// Processed as a success
}
Plain Text
복사
12345678910
INCLUDE_MY_RANK:true
Plain Text
복사
When the StovePC.GetRank method is processed correctly, it calls the OnRank callback.
The StovePCRank structure delivered to the callback contains score and rank information for a specific user.
// Callback parameters
// uint rankTotalCount : Total number of rankings aggregated in the searched leaderboard
private void OnRank(StovePCRank[] ranks, uint rankTotalCount)
{
// Display Ranking Information
StringBuilder sb = new StringBuilder();
sb.AppendLine("OnRank");
sb.AppendFormat(" - ranks.Length : {0}" + Environment.NewLine, ranks.Length);
for (int i = 0; i < ranks.Length; i++)
{
sb.AppendFormat(" - ranks[{0}].MemberNo : {1}" + Environment.NewLine, i, ranks[i].MemberNo.ToString());
sb.AppendFormat(" - ranks[{0}].Score : {1}" + Environment.NewLine, i, ranks[i].Score.ToString());
sb.AppendFormat(" - ranks[{0}].Rank : {1}" + Environment.NewLine, i, ranks[i].Rank.ToString());
sb.AppendFormat(" - ranks[{0}].Nickname : {1}" + Environment.NewLine, i, ranks[i].Nickname);
sb.AppendFormat(" - ranks[{0}].ProfileImage : {1}" + Environment.NewLine, i, ranks[i].ProfileImage);
}
sb.AppendFormat(" - rankTotalCount : {0}", rankTotalCount);
Debug.Log(sb.ToString());
}
Plain Text
복사
12345678910111213141516171819202122
If an error occurs while the StovePC.GetRank method is running, it calls the OnError callback.
You can check for external errors through the ExternalError field of the StovePCError structure.
ExternalError | Description |
1251 | Invalid Parameter |
1252 | CannotFindData |
3603 | ErrorLeaderBoardNotFound |
3631 | ErrorMembershipAPI |
500 | External Server Error |
