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

게임지원서비스 연동하기

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

1. Callback 설정

게임지원서비스 API를 사용하여 PC SDK와 커뮤니케이션 하기 위하여, 게임에서는 아래 StovePCCallbak 구조체의 콜백 포인터에 연결할 콜백함수를 정의해야 합니다.
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); // GetStat 처리가 완료됐을 때 호출되는 콜백 void(*OnStat)(const StovePCStat stat); // SetStat 처리가 완료됐을 때 호출되는 콜백 void(*OnSetStat)(const StovePCStatValue statValue); // GetAchievement 처리가 완료됐을 때 호출되는 콜백 void(*OnAchievement)(StovePCAchievement achievement); // GetAllAchievement 처리가 완료됐을 때 호출되는 콜백 void(*OnAllAchievement)(int size, StovePCAchievement* achievement); // GetRank API 호출시 응답받는 콜백 함수 포인터 void(*OnRank)(int size, StovePCRank* rank, unsigned int rankTotalCount); };
C++
복사
연동하기 1) Config, Callbak 설정에서와 같이 StovePCCallback 구조체의 콜백 포인터에 콜백함수를 연결합니다.
// StovePCCallback 구조체 instance 생성 StovePCCallback callback; // 모든 함수 포인터를 NULL로 초기화 memset(&callback, 0, sizeof(StovePCCallback)); // 구현한 함수 포인터를 연결 callback.OnError = OnMyErrorCallback; /*전역에서 정의한 콜백함수*/ callback.OnInitComplete = OnMyInitCompleteCallback; /*전역에서 정의한 콜백함수*/ callback.OnToken = OnMyTokenCallback; /*전역에서 정의한 콜백함수*/ callback.OnUser = OnMyUserInfoCallback; /*전역에서 정의한 콜백함수*/ callback.OnOwnership = OnMyOwnershipCallback; /*전역에서 정의한 콜백함수*/ // 게임지원서비스 callback.OnStat = OnMyStat; /*전역에서 정의한 콜백함수*/ callback.OnSetStat = OnMySetStat; /*전역에서 정의한 콜백함수*/ callback.OnAchievement = OnMyAchievement; /*전역에서 정의한 콜백함수*/ callback.OnAllAchievement = OnMyAllAchievement; /*전역에서 정의한 콜백함수*/ callback.OnRank = OnMyRank; /*전역에서 정의한 콜백함수*/
C++
복사
OnStatOnSetStatOnAchievementOnAllAchievementOnRank 콜백함수를 반드시 구현할 필요는 없습니다.
게임에서 사용하는 게임지원서비스에 맞게 필요한 콜백함수만 구현하여 연결하면 됩니다.

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

StovePC_SetStat 함수로 로그인한 사용자의 해당 게임에 대한 특정 스탯을 업데이트 합니다.
// 입력 파라미터 // const char* statId : 스튜디오에서 등록한 스탯 식별자 // const int statValue : 업데이트할 스탯값 StovePCResult result = StovePC_SetStat("STAT_ID", STAT_VALUE); if(result == StovePCResult::STOVE_PC_NO_ERROR) { /* 성공 처리 */ }
C++
복사
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
Fasle
""(빈문자열)
요청값이 현재값과 동일함
void OnSetStat(const StovePCStatValue statValue) { // 스탯 업데이트 결과 정보 출력 printf("OnSetStat"); printf(" - statValue.currentValue : %d", statValue.currentValue); printf(" - statValue.updated : %s", statValue.updated ? "true" : "false"); printf(" - statValue.errorMessage : %s", statValue.errorMessage); }
C++
복사
StovePC_SetStat 함수가 실행 중에 오류가 발생하면 OnError 콜백이 호출됩니다.
StovePCError 구조체의 ExternalError 필드를 통해 외부 오류를 확인할 수 있습니다.
ExternalError
설명
2000
Invalid Access
3000
Wrong API Usage
4000
Stats ID Not Found
9000
Service Error

3. 사용자 스탯 정보 얻기

StovePC_GetStat 함수로 로그인한 사용자의 해당 게임에 대한 특정 스탯 정보를 조회합니다.
// 입력 파라미터 // const char* statId : 스튜디오에서 등록한 스탯 식별자 StovePCResult result = StovePC_GetStat("STAT_ID"); if(result == StovePCResult::STOVE_PC_NO_ERROR) { /* 성공 처리 */ }
C++
복사
StovePC_GetStat 함수가 정상적으로 처리되면 OnStat 콜백이 호출됩니다.
콜백에 전달되는 StovePCStat 구조체에는 현재 스탯값이 포함되어 있습니다.
void OnStat(const StovePCStat stat) { // 스탯 정보 출력 printf("OnStat"); wprintf(L" - stat.statFullId.gameId : %s", stat.statFullId.gameId); printf(" - stat.statFullId.statId : %s", stat.statFullId.statId); printf(" - stat.memberNo : %llu", stat.memberNo); printf(" - stat.currentValue : %d", stat.currentValue); printf(" - stat.updatedAt : %llu", stat.updatedAt); }
C++
복사
StovePC_GetStat 함수가 실행 중에 오류가 발생하면 OnError 콜백이 호출됩니다.
StovePCError 구조체의 ExternalError 필드를 통해 외부 오류를 확인할 수 있습니다.
ExternalError
설명
2000
Invalid Access
3000
Wrong API Usage
4000
Stats ID Not Found
9000
Service Error

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

StovePC_GetAchievement 함수로 로그인한 사용자의 해당 게임에 대한 특정 단일 업적 정보를 조회합니다.
// 입력 파라미터 // const char* achievementId : 스튜디오에서 생성한 업적 식별자 StovePCResult result = StovePC_GetAchievement("ACHIEVEMENT_ID"); if(result == StovePCResult::STOVE_PC_NO_ERROR) { /* 성공 처리 */ }
C++
복사
StovePC_GetAchievement 함수가 정상적으로 처리되면 OnAchievement 콜백이 호출됩니다.
콜백에 전달되는 StovePCAchievement 구조체에는 현재 업적값과 업적 달성 상태 및 업적의 메타정보가 포함되어 있습니다.
void OnAchievement(const StovePCAchievement achievement) { // 단일 업적 정보 출력 printf("OnAchievement"); printf(" - achievement.achievementId : %s", achievement.achievementId); wprintf(L" - achievement.name : %s", achievement.name); wprintf(L" - achievement.description : %s", achievement.description); wprintf(L" - achievement.defaultImage : %s", achievement.defaultImage); wprintf(L" - achievement.achievedImage : %s", achievement.achievedImage); printf(" - achievement.condition.goalValue : %d", achievement.condition.goalValue); printf(" - achievement.condition.valueOperation : %s", achievement.condition.valueOperation); printf(" - achievement.condition.type : %s", achievement.condition.type); printf(" - achievement.value : %d", achievement.value); printf(" - achievement.status : %s", achievement.status); }
C++
복사
StovePC_GetAchievement 함수가 실행 중에 오류가 발생하면 OnError 콜백이 호출됩니다.
StovePCError 구조체의 ExternalError 필드를 통해 외부 오류를 확인할 수 있습니다.
ExternalError
설명
1200
Not found achievement
9000
Service Error

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

StovePC_GetAllAchievement 함수로 로그인한 사용자의 해당 게임에 대한 모든 업적 정보를 조회합니다.
StovePCResult result = StovePC_GetAllAchievement(); if(result == StovePCResult::STOVE_PC_NO_ERROR) { /* 성공 처리 */ }
C++
복사
StovePC_GetAllAchievement 함수가 정상적으로 처리되면 OnAllAchievement 콜백이 호출됩니다.
콜백에 전달되는 StovePCAchievement 구조체에는 현재 업적값과 업적 달성 상태 및 업적의 메타정보가 포함되어 있습니다.
void OnAllAchievement(int size, StovePCAchievement* achievements) { // 모든 업적 정보 출력 printf("OnAllAchievement"); printf(" - achievements size : %d", size); for (int i = 0; i < size; i++, achievements++) { printf(" - achievements[%d].achievementId : %s", i, achievements->achievementId); wprintf(L" - achievements[%d].name : %s", i, achievements->name); wprintf(L" - achievements[%d].description : %s", i, achievements->description); wprintf(L" - achievements[%d].defaultImage : %s", i, achievements->defaultImage); wprintf(L" - achievements[%d].achievedImage : %s", i, achievements->achievedImage); printf(" - achievements[%d].condition.goalValue : %d", i, achievements->condition.goalValue); printf(" - achievements[%d].condition.valueOperation : %s", i, achievements->condition.valueOperation); printf(" - achievements[%d].condition.type : %s", i, achievements->condition.type); printf(" - achievements[%d].value : %d", i, achievements->value); printf(" - achievements[%d].status : %s", i, achievements->status); } }
C++
복사
주의사항 콜백파라미터 StovePCAchievement 구조체의 유효한 범위는 콜백 스코프로 한정됩니다. PC SDK는 콜백 실행이 완료되는 즉시 내부에서 할당한 메모리를 해제합니다. 따라서 콜백 스코프 밖에서 StovePCAchievement 구조체의 정보를 사용하기 위해 저장이 필요한 경우 반드시 깊은복사(Deep Copy)를 통해 사본을 생성하고, 사본에 대한 사용이 완료되면 메모리를 해제하여야 합니다.
StovePC_GetAllAchievement 함수가 실행 중에 오류가 발생하면 OnError 콜백이 호출됩니다.
StovePCError 구조체의 ExternalError 필드를 통해 외부 오류를 확인할 수 있습니다.
ExternalError
설명
9000
Service Error

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

StovePC_GetRank 함수로 해당 게임에 대한 특정 리더보드의 순위 정보를 조회합니다.
// 입력 파라미터 // const char* leaderboardId : 스튜디오에서 생성한 리더보드 식별자 // const unsigned int pageIndex : 조회할 페이지 번호 (1 <= pageIndex) // const unsigned int pageSize : 조회할 순위의 개수 (1 <= pageSize <= 50) // const bool includeMyRank : 조회결과에 로그인한 사용자의 순위를 포함할지 여부 StovePCResult result = StovePC_GetRank("LEADERBOARD_ID", PAGE_INDEX, PAGE_SIZE, INCLUDE_MY_RANK); if(result == StovePCResult::STOVE_PC_NO_ERROR) { /* 성공 처리 */ }
C++
복사
StovePC_GetRank 함수가 정상적으로 처리되면 OnRank 콜백이 호출됩니다.
콜백에 전달되는 StovePCRank 구조체에는 특정 사용자에 대한 점수 및 순위 정보가 포함됩니다.
// 콜백 파라미터 // unsigned int rankTotalCount : 조회한 리더보드에 집계된 전체 순위 개수 void OnRank(int size, StovePCRank* ranks, unsigned int rankTotalCount) { // 순위 정보 출력 printf("OnRank"); printf(" - ranks.Length : %d", size); for (int i = 0; i < size; i++, ranks++) { printf(" - ranks[%d].memberNo : %llu", i, ranks->memberNo); printf(" - ranks[%d].score : %d", i, ranks->score); printf(" - ranks[%d].rank : %u", i, ranks->rank); wprintf(L" - ranks[%d].nickname : %s", i, ranks->nickname); wprintf(L" - ranks[%d].profileImage : %s", i, ranks->profileImage); } printf(" - rankTotalCount : %u", rankTotalCount); }
C++
복사
주의사항 콜백파라미터 StovePCRank 구조체 배열의 유효한 범위는 콜백함수 스코프로 한정됩니다. PC SDK는 콜백함수 실행이 완료되는 즉시 내부에서 할당한 메모리를 해제합니다. 따라서 콜백함수 스코프 밖에서 StovePCRank 구조체 배열의 정보를 사용하기 위해 저장이 필요한 경우 반드시 깊은복사(Deep Copy)를 통해 사본을 생성하고, 사본에 대한 사용이 완료되면 메모리를 해제하여야 합니다.
StovePC_GetRank 함수가 실행 중에 오류가 발생하면 OnError 콜백이 호출됩니다.
StovePCError 구조체의 ExternalError 필드를 통해 외부 오류를 확인할 수 있습니다.
ExternalError
설명
1251
Invalid Parameter
1252
CannotFindData
3603
ErrorLeaderBoardNotFound
3631
ErrorMembershipAPI
500
External Server Error