PC SDK는 부가서비스를 게임에 통합할 수 있도록 API를 제공합니다.
PC SDK가 지원하는 부가서비스로는 사용자정의 이벤트 로그, PC SDK 버전 조회, 과몰입방지 알림, 셧다운 알림, 추적단서 조회가 있습니다.
게임은 게임내 사용자정의 이벤트(게임 로그)를 스토브 플랫폼으로 전송할 수 있습니다. 또한 게임은 현재 사용중인 PC SDK의 유의적 버전을 조회할 수 있습니다.
PC SDK의 유의적 버전 조회는 콜백이 아닌 리턴값으로 획득이 가능합니다.
과몰입방지 알림은 매시간 게임 과몰입에 대한 경고 문구를 콜백을 통해 전달합니다.
셧다운 알림은 만 18세 미만의 청소년이 부모에 의해 요일별 특정시간에 게임을 이용 할 수 없도록 제한을 하는 시스템으로써 요건이 충족되면 최대 4회에 걸쳐 알림을 콜백을 통해 전달합니다.
1. Callback 설정
부가서비스 API를 사용하여 PC SDK와 커뮤니케이션 하기 위하여, 게임에서는 아래 UMyStovePCSDKObject 클래스의 연결된 콜백함수를 재정의해야 합니다.
UCLASS()
class HELLOSTOVE_API UMyStoveSDKObject : public UStoveSDKObject
{
GENERATED_BODY()
public:
//StovePCSDK Event
void OnInitComplete() final;
void OnError(FStoveError Error) final;
void OnToken(FStoveToken Token) final;
void OnUser(FStoveUser User) final;
void OnOwnership(int Size, FStoveOwnership* Ownerships) final;
// FetchTermsAgreement 처리가 완료됐을 때 호출되는 콜백
void OnFetchTermsAgreement(FStoveFetchTermsAgreement TermsAgreement) final;
//StashCustomEvent 처리가 완료됐을 때 호출되는 콜백
void OnStashCustomEvent(FStoveCustomEvent CustomEvent, int ParameterSize, FStoveCustomEventParameter* Parameters) final;
// ADD 2.6.0 Start
// 과몰입방지를 위해 매시간 호출되는 콜백
void OnOverImmersion(FStoveOverImmersion OverImmersion) final;
// 셧다운 제한시 호출되는 콜백
void OnShutdown(FStoveShutdown Shutdown) final;
// 2.6.0 End
}
Plain Text
복사
연동하기 1) Config, Callback 설정에서와 같이 UStoveSDKObject를 상속받은 'UMyStoveSDKObject'클래스의 콜백함수를 재정의하여 이벤트를 연결합니다.
/*소유권(Ownership) 기능만 사용하는 경우는,
필수 구현 콜백인 OnError, OnInitComplete외에
OnOwnership 콜백만 추가로 구현해서 연결합니다.*/
void UMyStoveSDKObject::OnInitComplete()
{
// 초기화 성공 후 처리내용
}
void UMyStoveSDKObject::OnError(FStoveError Error)
{
// 에러에 대한 처리내용
}
void UMyStoveSDKObject::OnOwnership(int Size, FStoveOwnership* Ownerships)
{
// 소유권 조회 후 처리내용
}
void UMyStoveSDKObject::OnStashCustomEvent(FStoveCustomEvent CustomEvent, int ParameterSize, FStoveCustomEventParameter* Parameters)
{
// 로그전송 후 전달된 내용 확인
}
// ADD 2.6.0 Start
void UMyStoveSDKObject::OnOverImmersion(FStoveOverImmersion OverImmersion)
{
// 과몰입방지를 위해 매시간 호출되는 콜백
}
void UMyStoveSDKObject::OnShutdown(FStoveShutdown Shutdown)
{
// 법률에 의거 선택적 셧다운이 필요한 경우 구현 합니다.
}
// 2.6.0 End
Plain Text
복사
OnStashCustomEvent, OnOverImmersion, OnShutdown 콜백을 반드시 구현할 필요는 없습니다. 게임에서 사용자정의 이벤트 로그 기능을 사용할 경우만 연결하면 됩니다.
경고
OnOverImmersion 콜백은 법률에 의거 게임과몰입/중독 예방조치가 필요한 경우 반드시 구현하여야 합니다. OnShutdown 콜백은 법률에 의거 선택적 셧다운이 필요한 경우 반드시 구현하여야 합니다.
2. 사용자정의 이벤트 로깅
UMyStoveSDKObject::StoveSDKStashCustomEvent 함수로 사용자정의 이벤트(게임 로그)를 로깅합니다.
// 입력 파라미터
// const FString& Name: 이벤트명
// const FString& Category1 : 1차 카테고리명
// const FString& Category2 : 2차 카테고리명
// const FString& SimpleValue : 간단한 값
// const TArray<FStoveCustomEventParameter> Params : 세부적인 파라미터 정보
// int paramsSize : 세부적인 파라미터 정보 개수
FStoveResult ErrorResult = UMyStoveSDKObject::StoveSDKStashCustomEvent("EVENT_NAME", "CATEGORY1", "CATEGORY2", 1.0f, params, PARAMS_SIZE);
if(ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
/* 성공 처리 */
}
Plain Text
복사
StoveSDKStashCustomEvent 함수가 정상적으로 처리되면 OnStashCustomEvent 콜백이 호출됩니다.
콜백에 전달되는 FStoveCustomEvent 구조체에는 API 호출시 전달한 이벤트명, 1차 카테고리명, 2차 카테고리명, 간단한 값이 포함되어 있습니다.
콜백에 전달되는 FStoveCustomEventParameter 구조체에는 API 호출시 전달한 파라미터 정보가 포함되어 있습니다.
void UMyStoveSDKObject::OnStashCustomEvent(FStoveCustomEvent CustomEvent, int ParameterSize, FStoveCustomEventParameter* Parameters)
{
/*Add the 'walkthrough' codes here.*/
OnLog("[StashCustomEvent]");
OnLog(" - CustomEvent.Name : %s", *(CustomEvent.Name));
OnLog(" - CustomEvent.Category1 : %s", *(CustomEvent.Category1));
OnLog(" - CustomEvent.Category2 : %s", *(CustomEvent.Category2));
OnLog(" - CustomEvent.SimpleValue : %f", CustomEvent.SimpleValue);
for (int i = 0; i < ParameterSize; i++, Parameters++)
{
OnLog(" - Parameter[%d].Name : %s", i, *(Parameters->Name));
OnLog(" - Parameter[%d].Value : %s", i, *(Parameters->Value));
}
}
Plain Text
복사
주의사항
콜백파라미터 FStoveCustomEvent/FStoveCustomEventParameter 구조체의 유효한 범위는 콜백함수 스코프로 한정됩니다.
PC SDK는 콜백함수 실행이 완료되는 즉시 내부에서 할당한 메모리를 해제합니다.
따라서 콜백함수 스코프 밖에서 FStoveCustomEvent/FStoveCustomEventParameter 구조체의 정보를 사용하기 위해
저장이 필요한 경우 반드시 깊은복사(Deep Copy)를 통해 사본을 생성하고,
사본에 대한 사용이 완료되면 메모리를 해제하여야 합니다.
3. PC SDK 유의적 버전 얻기
UMyStoveSDKObject::GetSDKVersion 함수로 현재 연동중인 PC SDK의 버전 정보를 조회합니다.
FString Version = UMyStoveSDKObject::StoveSDKGetSDKVersion();
if (Version.IsEmpty() == false)
{
/* 성공 처리 */
}
Plain Text
복사
4. 게임 과몰입방지
게임을 시작한 후 매시간마다 OnOverImmersion 콜백이 호출됩니다.
콜백에 전달되는 FStoveOverImmersion 구조체에는 메세지, 게임이용 경과시간, 메세지 최소 노출시간(초)이 포함되어 있습니다.
메세지는 PC SDK에 설정된 언어를 기반으로 번역된 메세지가 전달 됩니다.
•
FStoveOverImmersion.Message : 과몰입 메세지
•
FStoveOverImmersion.ElapsedTimeInHours : 경과 시간
•
FStoveOverImmersion.MinExposureTimeInSeconds : 메세지 최소 노출 시간(초단위)
void UMyStoveSDKObject::OnOverImmersion(FStoveOverImmersion OverImmersion)
{
OnLog("[OverImmersion]");
OnLog("- Message : %s", *(OverImmersion.Message));
OnLog("- ElapsedTimeInHours : %d", OverImmersion.ElapsedTimeInHours);
OnLog("- MinExposureTimeInSeconds : %d", OverImmersion.MinExposureTimeInSeconds);
// 게임에서 과몰입 방지에 대한 안내
}
Plain Text
복사
과몰입 메시지 안내
게임을 플레이한 지 1 시간이 지났습니다. 과도한 게임이용은 정상적인 일상생활에 지장을 줄 수 있습니다.
5. 셧다운
게임을 시작한 후 선택적 셧다운 대상자에 한해 셧다운 시스템에 등록된 타임테이블에 의거하여 OnShutdown 콜백이 호출됩니다.
OnShutdown 콜백은 최대 4회 호출 될 수 있으며 호출되는 시점 및 게임에서 조치해야 하는 사항은 아래와 같습니다.
•
PCSDK 초기화 성공 후 셧다운 이벤트
◦
10분전 셧다운 알림 : 10분뒤 로그아웃 된다는 알림만 표시
◦
5분전 셧다운 알림 : 5분뒤 로그아웃 된다는 알림만 표시
◦
1분전 셧다운 알림 : 1분뒤 로그아웃 된다는 알림만 표시
◦
셧다운 알림 : 로그아웃 된다는 알림을 표시하고 사용자 확인시 즉시 게임 종료
콜백에 전달되는 FStoveShutdown 구조체에는 셧다운까지 남은 시간, 메세지, 메세지 노출시간(초)이 포함되어 있습니다.
•
FStoveShutdown.InadvanceTimeInMinutes : 사용자의 셧다운까지 남은 시간(분)으로써 0 인 경우 즉시 게임 종료
•
FStoveShutdown.Message : 셧다운 알림 메세지
•
FStoveShutdown.ExposureTimeInSeconds : 메세지 노출 시간(초)
void UMyStoveSDKObject::OnShutdown(const FStoveShutdown Shutdown)
{
//셧다운 정보 출력
OnLog("[Shutdown]");
OnLog("- InAdvanceTimeInMinutes : %d", Shutdown.InAdvanceTimeInMinutes);
OnLog("- Message : %s", *(Shutdown.Message));
OnLog("- ExposureTimeInSeconds : %d", Shutdown.ExposureTimeInSeconds);
}
Plain Text
복사
주의사항
콜백파라미터 FStoveShutdown 구조체의 유효한 범위는 콜백함수 스코프로 한정됩니다.
PC SDK는 콜백함수 실행이 완료되는 즉시 내부에서 할당한 메모리를 해제합니다.
따라서 콜백함수 스코프 밖에서 FStoveShutdown 구조체의 정보를 사용하기 위해 저장이 필요한 경우 반드시 깊은복사(Deep Copy)를 통해 사본을 생성하고,
사본에 대한 사용이 완료되면 메모리를 해제하여야 합니다.
셧다운 메시지 안내
10분 : 회원님은 게임 시간 선택제 적용 대상으로 10 분 후 게임 이용이 제한됩니다.
5분 : 회원님은 게임 시간 선택제 적용 대상으로 5 분 후 게임 이용이 제한됩니다.
1분 : 회원님은 게임 시간 선택제 적용 대상으로 1 분 후 게임 이용이 제한됩니다.
0분 : 회원님은 게임 시간 선택제 적용 대상으로 게임 이용이 제한되어 게임을 종료합니다.
6. 추적 단서 조회
UMyStoveSDKObject::StoveSDKGetTraceHint 함수로 스토브 플랫폼 로그를 추적 하기 위한 일련의 단서를 조회합니다.
FStoveTraceHint TraceHint = UStoveSDKObject::StoveSDKGetTraceHint();
if (TraceHint.ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
OnLog("[GetTraceHint]");
OnLog(" - TraceHint.SessionId : %s", *(TraceHint.SessionId));
OnLog(" - TraceHint.RefSessionId : %s", *(TraceHint.RefSessionId));
OnLog(" - TraceHint.Uuid : %s", *(TraceHint.Uuid));
OnLog(" - TraceHint.ServiceProtocol : %s", *(TraceHint.ServiceProtocol));
OnLog(" - TraceHint.RefResourceType : %s", *(TraceHint.RefResourceType));
}
else
{
/* 실패 처리 */
}
Plain Text
복사
UStoveSDKObject::StoveSDKGetTraceHint 함수는 FStoveTraceHint 구조체를 리턴합니다.
리턴되는 FStoveTraceHint 구조체에는 세션 아이디 및 레퍼런스 세션 아이디 등이 포함되어 있습니다.
또한, 함수 호출에 대한 에러코드도 포함되어 있습니다.