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

부가서비스 연동하기

생성일
2024/03/14 23:52
태그
상위 항목
하위 항목
PC SDK는 부가서비스를 게임에 통합할 수 있도록 API를 제공합니다.
PC SDK가 지원하는 부가서비스로는 사용자정의 이벤트 로그, PC SDK 버전 조회, 과몰입방지 알림, 셧다운 알림, 추적 단서 조회가 있습니다.
게임은 게임내 사용자정의 이벤트(게임 로그)를 스토브 플랫폼으로 전송할 수 있습니다. 또한 게임은 현재 사용중인 PC SDK의 유의적 버전을 조회할 수 있습니다.
PC SDK의 유의적 버전 조회는 콜백이 아닌 리턴값으로 획득이 가능합니다.
과몰입방지 알림은 매시간 게임 과몰입에 대한 경고 문구를 콜백을 통해 전달합니다.
셧다운 알림은 만 18세 미만의 청소년이 부모에 의해 요일별 특정시간에 게임을 이용 할 수 없도록 제한을 하는 시스템으로써 요건이 충족되면 최대 4회에 걸쳐 알림을 콜백을 통해 전달합니다.

1. Callback 설정

부가서비스 API를 사용하여 PC SDK와 커뮤니케이션 하기 위하여, 게임에서는 아래 StovePCCallback 구조체의 콜백 포인터에 연결할 콜백함수를 정의해야 합니다.
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); // StashCustomEvent 처리가 완료됐을 때 호출되는 콜백 void(*OnStashCustomEvent)(const StovePCCustomEvent customEvent, int parameterSize, StovePCCustomEventParameter* parameter); // ADD 2.6.0 Start // 과몰입방지를 위해 매시간 호출되는 콜백 void(*OnOverImmersion)(const StovePCOverImmersion overImmersion); // 셧다운 제한시 호출되는 콜백 void(*OnShutdown)(const StovePCShutdown shutdown); // 2.6.0 End };
C++
복사
연동하기 2) Config, Callback 설정에서와 같이 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.OnAutoPopup = OnMyAutoPopup; /*전역에서 정의한 콜백함수*/ callback.OnManualPopup = OnMyManualPopup; /*전역에서 정의한 콜백함수*/ callback.OnNewsPopup = OnMyNewsPopup; /*전역에서 정의한 콜백함수*/ callback.OnCouponPopup = OnMyCouponPopup; /*전역에서 정의한 콜백함수*/ callback.OnCommunityPopup = OnMyCommunityPopup; /*전역에서 정의한 콜백함수*/ // 부가서비스 callback.OnStashCustomEvent = OnMyStashCustomEvent; /*전역에서 정의한 콜백함수*/ // ADD 2.6.0 Start callback.OnOverImmersion = OnMyOverImmersion; /*전역에서 정의한 콜백함수*/ callback.OnShutdown = OnMyShutdown; /*전역에서 정의한 콜백함수*/ // 2.6.0 End
C++
복사
OnStashCustomEvent 콜백을 반드시 구현할 필요는 없습니다.게임에서 사용자정의 이벤트 로그 기능을 사용할 경우만 연결하면 됩니다.
경고 OnOverImmersion 콜백은 법률에 의거 게임과몰입/중독 예방조치가 필요한 경우 반드시 구현하여야 합니다. OnShutdown 콜백은 법률에 의거 선택적 셧다운이 필요한 경우 반드시 구현하여야 합니다.

2. 사용자정의 이벤트 로깅

StovePC_StashCustomEvent 함수로 사용자정의 이벤트(게임 로그)를 로깅합니다.
// 입력 파라미터 // const char* name: 이벤트명 // const char* category1 : 1차 카테고리명 // const char* category2 : 2차 카테고리명 // const float simpleValue : 간단한 값 // const StovePCCustomEventParameter* params : 세부적인 파라미터 정보 // const int paramsSize : 세부적인 파라미터 정보 개수 StovePCResult result = StovePC_StashCustomEvent("EVENT_NAME", "CATEGORY1", "CATEGORY2", 1.0f, params, PARAMS_SIZE); if(result == StovePCResult::STOVE_PC_NO_ERROR) { /* 성공 처리 */ }
C++
복사
StovePC_StashCustomEvent 함수가 정상적으로 처리되면 OnStashCustomEvent 콜백이 호출됩니다.
콜백에 전달되는 StovePCCustomEvent 구조체에는 API 호출시 전달한 이벤트명, 1차 카테고리명, 2차 카테고리명, 간단한 값이 포함되어 있습니다.
콜백에 전달되는 StovePCCustomEventParameter 구조체에는 API 호출시 전달한 파라미터 정보가 포함되어 있습니다.
void OnStashCustomEvent(const StovePCCustomEvent customEvent, int parameterSize, StovePCCustomEventParameter* parameter) { // 모든 사용자정의 이벤트 정보 출력 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++
복사
주의사항 콜백파라미터 StovePCCustomEvent/StovePCCustomEventParameter 구조체의 유효한 범위는 콜백함수 스코프로 한정됩니다. PC SDK는 콜백함수 실행이 완료되는 즉시 내부에서 할당한 메모리를 해제합니다. 따라서 콜백함수 스코프 밖에서 StovePCCustomEvent/StovePCCustomEventParameter 구조체의 정보를 사용하기 위해 저장이 필요한 경우 반드시 깊은복사(Deep Copy)를 통해 사본을 생성하고, 사본에 대한 사용이 완료되면 메모리를 해제하여야 합니다.
StovePC_StashCustomEvent 함수가 실행중에 오류가 발생하면 OnError 콜백이 호출됩니다.

3. PC SDK 유의적 버전 얻기

StovePC_GetSDKVersion 함수로 현재 연동중인 PC SDK의 버전 정보를 조회합니다.
char* version = StovePC_GetSDKVersion(); if(0 != strcmp(version, "")) { /* 성공 처리 */ }
C++
복사

4. 게임 과몰입방지 

게임을 시작한 후 매시간마다 OnOverImmersion 콜백이 호출됩니다.
콜백에 전달되는 StovePCOverImmersion 구조체에는 메세지, 게임이용 경과시간, 메세지 최소 노출시간(초)이 포함되어 있습니다.
StovePCOverImmersion.message : 과몰입 메세지
StovePCOverImmersion.elapsedTimeInHours : 경과 시간
StovePCOverImmersion.minExposureTimeInSeconds : 메세지 최소 노출 시간(초단위)
메세지는 PC SDK에 설정된 언어를 기반으로 번역된 메세지가 전달 됩니다.
void OnOverImmersion(const StovePCOverImmersion overImmersion) { // 과몰입방지 정보 출력 printf("OnOverImmersion"); wprintf(L" - overImmersion.message : %s", overImmersion.message); printf(" - overImmersion.elapsedTimeInHours: %d", overImmersion.elapsedTimeInHours); printf(" - overImmersion.minExposureTimeInSeconds: %d", overImmersion.minExposureTimeInSeconds); }
Plain Text
복사
주의사항 콜백파라미터 StovePCOverImmersion 구조체의 유효한 범위는 콜백함수 스코프로 한정됩니다. PC SDK는 콜백함수 실행이 완료되는 즉시 내부에서 할당한 메모리를 해제합니다. 따라서 콜백함수 스코프 밖에서 StovePCOverImmersion 구조체의 정보를 사용하기 위해 저장이 필요한 경우 반드시 깊은복사(Deep Copy)를 통해 사본을 생성하고, 사본에 대한 사용이 완료되면 메모리를 해제하여야 합니다.
과몰입 메시지 안내 게임을 플레이한 지 1 시간이 지났습니다. 과도한 게임이용은 정상적인 일상생활에 지장을 줄 수 있습니다.

5. 셧다운 

게임을 시작한 후 선택적 셧다운 대상자에 한해 셧다운 시스템에 등록된 타임테이블에 의거하여 OnShutdown 콜백이 호출됩니다.
OnShutdown 콜백은 최대 4회 호출 될 수 있으며 호출되는 시점 및 게임에서 조치해야 하는 사항은 아래와 같습니다.
PCSDK 초기화 성공 후 셧다운 이벤트
10분전 셧다운 알림 : 10분뒤 로그아웃 된다는 알림만 표시
5분전 셧다운 알림 : 5분뒤 로그아웃 된다는 알림만 표시
1분전 셧다운 알림 : 1분뒤 로그아웃 된다는 알림만 표시
셧다운 알림 : 로그아웃 된다는 알림을 표시하고 사용자 확인시 즉시 게임 종료
콜백에 전달되는 StovePCShutdown 구조체에는 셧다운까지 남은 시간, 메세지, 메세지 노출시간(초)이 포함되어 있습니다.
StovePCShutdown.inadvanceTimeInMinutes : 사용자의 셧다운까지 남은 시간(분)으로써 0 인 경우 즉시 게임 종료
StovePCShutdown.message : 셧다운 알림 메세지
StovePCShutdown.exposureTimeInSeconds : 메세지 노출 시간(초)
void OnShutdown(const StovePCShutdown shutdown) { // 셧다운 정보 출력 printf("OnShutdown"); printf(" - shutdown.inadvanceTimeInMinutes: %d", shutdown.inadvanceTimeInMinutes); wprintf(L" - shutdown.message : %s", shutdown.message); printf(" - shutdown.exposureTimeInSeconds: %d", shutdown.exposureTimeInSeconds); }
Plain Text
복사
주의사항 콜백파라미터 StovePCShutdown 구조체의 유효한 범위는 콜백함수 스코프로 한정됩니다. PC SDK는 콜백함수 실행이 완료되는 즉시 내부에서 할당한 메모리를 해제합니다. 따라서 콜백함수 스코프 밖에서 StovePCShutdown 구조체의 정보를 사용하기 위해 저장이 필요한 경우 반드시 깊은복사(Deep Copy)를 통해 사본을 생성하고, 사본에 대한 사용이 완료되면 메모리를 해제하여야 합니다.
셧다운 메시지 안내 10분 : 회원님은 게임 시간 선택제 적용 대상으로 10 분 후 게임 이용이 제한됩니다. 5분 : 회원님은 게임 시간 선택제 적용 대상으로 5 분 후 게임 이용이 제한됩니다. 1분 : 회원님은 게임 시간 선택제 적용 대상으로 1 분 후 게임 이용이 제한됩니다. 0분 : 회원님은 게임 시간 선택제 적용 대상으로 게임 이용이 제한되어 게임을 종료합니다.

6. 추적 단서 조회 

StovePC.GetTraceHint 함수로 스토브 플랫폼 로그를 추적 하기 위한 일련의 단서를 조회합니다.
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 { /* 실패 처리 */ }
Plain Text
복사
StovePC_GetTraceHint 함수는 StovePCTraceHint 구조체를 리턴합니다.
리턴되는 StovePCTraceHint 구조체에는 세션 아이디 및 레퍼런스 세션 아이디 등이 포함되어 있습니다.
또한, 함수 호출에 대한 에러코드도 포함되어 있습니다