지원 프로그램
home
슬기로운 데모생활
home

게임지원서비스 연동하기

생성일
2024/03/14 22:25
태그
상위 항목
하위 항목
PC SDK는 스토브 플랫폼의 게임지원서비스를 게임에 통합할 수 있도록 API를 제공합니다. PC SDK가 지원하는 게임지원서비스로는 스탯, 업적, 리더보드가 있습니다. 각각의 서비스는 아래와 같이 정의합니다.
스탯 : 유저의 다양한 게임 Play Data를 수치로 기록해 주는 서비스
업적 : 게임 Play 도전 과제를 설정하고, 유저 별 달성 정보를 제공해 주는 서비스
리더보드 : 특정 게임 Play Data의 유저 랭킹 정보를 제공해 주는 서비스
PC SDK 게임지원서비스 API를 사용하기 위해서는 스튜디오를 통한 게임지원서비스의 메타데이터 등록이 선행되어야 합니다.
메타데이터 관리에 대한 내용은 게임지원서비스 스튜디오 가이드을 참고하시기 바랍니다.

1. Callback 설정

게임지원서비스 API를 사용하여 PC SDK와 커뮤니케이션 하기 위하여, 게임에서는 아래 StovePCCallbak 클래스의 콜백에 연결할 델리게이트 메서드를 정의해야 합니다.
public class StovePCCallback { public StovePCErrorDelegate OnError; public StovePCInitializationCompleteDelegate OnInitializationComplete; public StovePCTokenDelegate OnToken; public StovePCUserDelegate OnUser; public StovePCOwnershipDelegate OnOwnership; // GetStat 처리가 완료됐을 때 호출되는 콜백 public StovePCStatDelegate OnStat; // SetStat 처리가 완료됐을 때 호출되는 콜백 public StovePCSetStatDelegate OnSetStat; // GetAchievement 처리가 완료됐을 때 호출되는 콜백 public StovePCAchievementDelegate OnAchievement; // GetAllAchievement 처리가 완료됐을 때 호출되는 콜백 public StovePCAllAchievementDelegate OnAllAchievement; // GetRank 처리가 완료됐을 때 호출되는 콜백 public StovePCRankDelegate OnRank; }
Plain Text
복사
연동하기 메뉴의 2. Config, Callback 설정에서와 같이 StovePCCallback 클래스의 콜백에 델리게이드를 연결합니다.
// StovePCCallback 클래스 instance 생성 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), // 게임지원서비스 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
복사
OnStatOnSetStatOnAchievementOnAllAchievementOnRank 콜백을 반드시 구현할 필요는 없습니다.
게임에서 사용하는 게임지원서비스에 맞게 필요한 콜백 메서드만 구현하여 연결하면 됩니다.

2. 사용자 스탯 업데이트 하기

StovePC.SetStat 메서드로 로그인한 사용자의 해당 게임에 대한 특정 스탯을 업데이트 합니다.
// 입력 파라미터 // string statId : 스튜디오에서 등록한 스탯 식별자 // int statValue : 업데이트할 스탯값 StovePCResult result = StovePC.SetStat("STAT_ID", STAT_VALUE); if(result == StovePCResult.NoError) { // 성공 처리 }
Plain Text
복사
StovePC.SetStat 메서드가 정상적으로 처리되면 OnSetStat 콜백이 호출됩니다.
콜백에 전달되는 StovePCStatValue 구조체에는 현재 스탯값과 업데이트 상태를 나타내는 플래그 및 에러메세지가 포함되어 있습니다.
스탯값이 완전하게 반영되어 업데이트 되었다면 Updated 필드는 true, ErrorMessage 필드는 빈문자열이 포함되며, 스탯값이 부분적으로 업데이트 되었다면 Updated 필드는 true, ErrorMessage 필드는 "integer overflow" 와 같은 문자열이 포함됩니다.
예를들어 INCREMENT 유형 스탯의 현재값이 2,147,483,000라고 가정하고 StovePC.SetStat API를 통해 1,000을 합산하려 한다면 Int32 타입이 가질 수 있는 값의 범위를 벗어나게 되므로 업데이트를 요청한 값(1,000)의 일부만 반영되어 현재값이 Int32 타입의 최대값인 2,147,483,647로 업데이트 되는 경우 ErrorMessage 필드에 "integer overflow" 와 같은 문자열이 포함됩니다.
아래 표는 StovePCStatValue 구조체를 통해 얻을 수 있는 결과의 목록입니다.
스탯유형
Updated
ErrorMessage
결과
모든유형
True
""(빈문자열)
요청값이 현재값에 완전히 업데이트 됨
INCREMENT
True
"integer overflow"
저장 공간 초과로 부분(partial) 업데이트 됨
INCREMENT
False
"integer overflow"
저장 공간 초과로 업데이트 안됨
MIN
False
""(빈문자열)
요청값이 현재값보다 큼
MAX
False
""(빈문자열)
요청값이 현재값보다 작음
REPLACE
False
""(빈문자열)
요청값이 현재값과 동일함
private void OnSetStat(StovePCStatValue statValue) { // 스탯 업데이트 결과 정보 출력 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
복사
주의사항 콜백파라미터 StovePCStatValue 구조체의 유효한 범위는 콜백함수 스코프로 한정됩니다. PC SDK는 콜백함수 실행이 완료되는 즉시 내부에서 할당한 메모리를 해제합니다. 따라서 콜백함수 스코프 밖에서 StovePCStatValue 구조체의 정보를 사용하기 위해 저장이 필요한 경우 반드시 깊은복사(Deep Copy)를 통해 사본을 생성하고, 사본에 대한 사용이 완료되면 메모리를 해제하여야 합니다.
StovePC.SetStat 메서드가 실행중에 오류가 발생하면 OnError 콜백이 호출됩니다.
StovePCError 구조체의 ExternalError 필드를 통해 외부 오류를 확인할 수 있습니다.
ExternalError
설명
2000
Invalid Access
3000
Wrong API Usage
4000
Stats ID Not Found
9000
Service Error

3. 사용자 스탯 정보 얻기

StovePC.GetStat 메서드로 로그인한 사용자의 해당 게임에 대한 특정 스탯 정보를 조회합니다.
// 입력 파라미터 // string statId : 스튜디오에서 등록한 스탯 식별자 StovePCResult result = StovePC.GetStat("STAT_ID"); if(result == StovePCResult.NoError) { // 성공 처리 }
Plain Text
복사
StovePC.GetStat 메서드가 정상적으로 처리되면 OnStat 콜백이 호출됩니다.
콜백에 전달되는 StovePCStat 구조체에는 현재 스탯값이 포함되어 있습니다.
private void OnStat(StovePCStat stat) { // 스탯 정보 출력 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
복사
주의사항 콜백파라미터 StovePCStat 구조체의 유효한 범위는 콜백 스코프로 한정됩니다. PC SDK는 콜백 실행이 완료되는 즉시 내부에서 할당한 메모리를 해제합니다. 따라서 콜백 스코프 밖에서 StovePCStat 구조체의 정보를 사용하기 위해 저장이 필요한 경우 반드시 깊은복사(Deep Copy)를 통해 사본을 생성하고, 사본에 대한 사용이 완료되면 메모리를 해제하여야 합니다.
StovePC.GetStat 메서드가 실행중에 오류가 발생하면 OnError 콜백이 호출됩니다.
StovePCError 구조체의 ExternalError 필드를 통해 외부 오류를 확인할 수 있습니다.
ExternalError
설명
2000
Invalid Access
3000
Wrong API Usage
4000
Stats ID Not Found
9000
Service Error

4. 사용자 단일 업적 정보 얻기

StovePC.GetAchievement 메서드로 로그인한 사용자의 해당 게임에 대한 특정 단일 업적 정보를 조회합니다.
// 입력 파라미터 // string achievementId : 스튜디오에서 생성한 업적 식별자 StovePCResult result = StovePC.GetAchievement("ACHIEVEMENT_ID"); if(result == StovePCResult.NoError) { // 성공 처리 }
Plain Text
복사
StovePC.GetAchievement 메서드가 정상적으로 처리되면 OnAchievement 콜백이 호출됩니다.
콜백에 전달되는 StovePCAchievement 구조체에는 현재 업적값과 업적 달성 상태 및 업적의 메타정보가 포함되어 있습니다.
private void OnAchievement(StovePCAchievement achievement) { // 단일 업적 정보 출력 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
복사
주의사항 콜백파라미터 StovePCAchievement 구조체의 유효한 범위는 콜백 스코프로 한정됩니다. PC SDK는 콜백 실행이 완료되는 즉시 내부에서 할당한 메모리를 해제합니다. 따라서 콜백 스코프 밖에서 StovePCAchievement 구조체의 정보를 사용하기 위해 저장이 필요한 경우 반드시 깊은복사(Deep Copy)를 통해 사본을 생성하고, 사본에 대한 사용이 완료되면 메모리를 해제하여야 합니다.
StovePC.GetAchievement 메서드가 실행중에 오류가 발생하면 OnError 콜백이 호출됩니다.
StovePCError 구조체의 ExternalError 필드를 통해 외부 오류를 확인할 수 있습니다.
ExternalError
설명
1200
Not found achievement
9000
Service error

5. 사용자 전체 업적 정보 얻기

StovePC.GetAllAchievement 메서드로 로그인한 사용자의 해당 게임에 대한 모든 업적 정보를 조회합니다.
StovePCResult result = StovePC.GetAllAchievement(); if(result == StovePCResult.NoError) { // 성공 처리 }
Plain Text
복사
StovePC.GetAllAchievement 메서드가 정상적으로 처리되면 OnAllAchievement 콜백이 호출됩니다.
콜백에 전달되는 StovePCAchievement 구조체에는 현재 업적값과 업적 달성 상태 및 업적의 메타정보가 포함되어 있습니다.
private void OnAchievement(StovePCAchievement[] achievements) { // 모든 업적 정보 출력 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
복사
StovePC.GetAllAchievement 메서드가 실행중에 오류가 발생하면 OnError 콜백이 호출됩니다.
StovePCError 구조체의 ExternalError 필드를 통해 외부 오류를 확인할 수 있습니다.
ExternalError
설명
9000
Service error

6. 리더보드 랭킹 정보 얻기

StovePC.GetRank 메서드로 해당 게임에 대한 특정 리더보드의 순위 정보를 조회합니다.
// 입력 파라미터 // string leaderboardId : 스튜디오에서 생성한 리더보드 식별자 // uint pageIndex : 조회할 페이지 번호 (1 <= pageIndex) // uint pageSize : 조회할 순위의 개수 (1 <= pageSize <= 50) // bool includeMyRank : 조회결과에 로그인한 사용자의 순위를 포함할지 여부 StovePCResult result = StovePC.GetRank("LEADERBOARD_ID", PAGE_INDEX, PAGE_SIZE, INCLUDE_MY_RANK); if(result == StovePCResult.NoError) { // 성공 처리 }
Plain Text
복사
INCLUDE_MY_RANK:true로 요청하면 응답 데이터 리스트의 첫번째 데이터에 로그인한 유저의 랭킹 정보를 반환하고 이후 페이지 랭킹 데이터를 반환합니다.
StovePC.GetRank 메서드가 정상적으로 처리되면 OnRank 콜백이 호출됩니다.
콜백에 전달되는 StovePCRank 구조체에는 특정 사용자에 대한 점수 및 순위 정보가 포함됩니다.
// 콜백 파라미터 // uint rankTotalCount : 조회한 리더보드에 집계된 전체 순위 개수 private void OnRank(StovePCRank[] ranks, uint rankTotalCount) { // 순위 정보 출력 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
복사
StovePC.GetRank 메서드가 실행중에 오류가 발생하면 OnError 콜백이 호출됩니다.
StovePCError 구조체의 ExternalError 필드를 통해 외부 오류를 확인할 수 있습니다.
ExternalError
설명
1251
Invalid Parameter
1252
CannotFindData
3603
ErrorLeaderBoardNotFound
3631
ErrorMembershipAPI
500
External Server Error