•
StovePCSDK_Unreal은 언리얼 엔진의 UObject 타입의 클래스인 UStoveSDKObject클래스를 사용합니다. 여기에는 StovePCSDK 라이브러리의 데이터 타입과 인터페이스 및 콜백함수가 재정의 되어 있습니다. 연동하기 전 Plugin의 정의된 UStoveSDKObject를 상속받아 게임 프로젝트 내에 UMyStoveSDKObject를 구성한 후 사용해야 합니다.
•
Prefix
UMyStoveSDKObject의 Prefix는 Unreal Engine 내에서 UObject 타입을 상속받은 클래스에 접두사 U를 붙이는 규칙을 그대로 따랐습니다.
상속받은 UObject에서 Plugin에 Import된 인터페이스를 Super를 통해 호출합니다.
•
Super상속받은 부모의 함수를 호출하기 위해 언리얼에서 제공하는 키워드는 Super 입니다.
FStoveResult UStoveSDKObject::StoveSDKInit(const FStoveConfig Config)
{
FStoveResult ErrorResult = Super::StoveSDKInit(Config);
return ErrorResult;
}
C++
복사
1. Config, Callback 설정
PC SDK를 초기화하기 위해서는, 먼저 FStoveConfig 구조체에 값을 채운 뒤, 상속받은 Actor의 UStoveSDKObject::StoveSDKInit 함수를 호출합니다.
아래 코드를 참고하여 FStoveConfig 구조체의 각 필드 값을 채웁니다.
FStoveConfig Config{"LIVE",
"YOUR_APP_KEY",
"YOUR_SECRET_KEY",
"YOUR_GAME_ID",
StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG,
""}; // Logpath
C++
복사
주의사항
PCSDK 로그경로는 절대적경로로 설정해야 합니다. ex) C:\Program Files\{Your Game Folder}\Logs 마지막에 "\"는 추가하지 않습니다. PCSDK 에서 "StovePCSDK.log" 파일명을 자동으로 추가합니다.
만약 "" 빈문자열로 경로를 설정하게 되면 PCSDK는 자동적으로 게임실행파일 폴더 또는 PCSDK DLL 이 위치한 폴더의 경로로 로그가 생성됩니다.
로그레벨 설정시 SANDBOX환경은 StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG 값으로 설정하고, LIVE환경은 StovePCLogLevel::STOVE_PC_LOG_LEVEL_ERROR 값으로 설정하기 바랍니다.
FStoveConfig 구조체 에 대한 설명은 Plugins\StoveSDKPlugin\Source\StoveSDKPlugin\Public폴더의 StoveSDKStruct.h 파일을 참고하세요.
게임 프로젝트에서 PC SDK의 API를 호출하고 그 결과를 확인하기 위해서는 콜백함수를 사용해야 합니다. 게임 프로젝트에서는 사용하게 되는 콜백함수는 아래와 같습니다.
{
//StovePCSDK Callback
public:
void OnError(FStoveError Error) final;
void OnInitComplete() final;
void OnToken(FStoveToken Token) final;
void OnUser(FStoveUser User) final;
void OnOwnership(int Size, FStoveOwnership* Ownerships) final;
}
C++
복사
필수적으로 연동해야 하는 OnError, OnInitComplete 및 OnOwnership 콜백함수 외의 나머지 콜백함수는 필요 시에만 연동을 하면 됩니다. 예를 들어, 소유권(Ownership) 기능만 사용하는 경우, 아래와 같이 게임 프로젝트에 정의해서 구현하면 됩니다.
/*소유권(Ownership) 기능만 사용하는 경우는,
필수 구현 콜백인 OnError, OnInitcomplte외에
OnOwnership 콜백만 추가로 구현해서 연결합니다.*/
void UMyStoveSDKObject::OnInitComplete()
{
// 초기화 성공 후 처리내용
}
void UMyStoveSDKObject::OnError(FStoveError Error)
{
// 에러에 대한 처리내용
}
void UMyStoveSDKObject::OnOwnership(int Size, FStoveOwnership* Ownerships)
{
// 소유권 조회 후 처리내용
}
C++
복사
2. SDK 초기화
PC SDK의 API를 사용하기 전에 초기화를 위해 MyStoveSDKObject.cpp의 UMyStoveSDKObject::StoveSDKInit 함수에 아래 코드와 같이 초기화 코드를 입력합니다.
FStoveResult UMyStoveSDKObject::StoveSDKInit(const FStoveConfig& Config)
{
FStoveResult ErrorResult = Super::StoveSDKInit(Config);
if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*StovePCSDK init 성공*/
}
}
C++
복사
UMyStoveSDKObject::StoveSDKInit함수는 config와 callback의 유효성 여부만 확인한 후, 즉시 FStovePCResult enum 타입 값을 반환합니다. 성공한 경우, STOVE_PC_NO_ERROR 값이 반환됩니다. 실패한 경우는 해당 에러 코드를 반환하며 게임 종료를 처리해야 합니다. 전체 에러 코드 목록은 StovePCDefine.h 파일의 StovePCResult enum을 확인하면 됩니다.
StovePC_RunCallback 함수를 비롯하여 PCSDK와 연동되는 Callback함수들은 반드시 메인스레드에서 호출하도록 코드를 작성해주시기 바랍니다.
UMyStoveSDKObject::StoveSDKInit함수 내에서 config와 callback 유효성 확인이 진행되고, 그 외의 작업은 PC SDK에서 비동기로 처리됩니다. PC SDK의 비동기 작업이 성공적으로 완료된 경우, UMyStoveSDKObject::OnInitComplete 콜백이 호출되며, 에러가 발생한 경우는 UMyStoveSDKObject::OnError 콜백이 호출됩니다. 만약 초기화 시에 에러가 발생한 경우 UMyStoveSDKObject::OnError 함수에 전달된 StovePCError 구조체를 통해 에러 코드, 메시지 등을 확인할 수 있습니다. StovePCError 구조체 파라미터의 fError.result.result 값은 StovePCResult enum과 동일하여 에러코드로 에러상황을 유추 할 수 있습니다.
void UMyStoveSDKObject::OnInitComplete()
{
OnLog("[OnInitComplete]");
}
void UMyStoveSDKObject::OnError(const FStoveError& Error)
{
switch (Error.FunctionType)
{
case STOVE_PC_INIT:
case STOVE_PC_GET_USER:
case STOVE_PC_GET_OWNERSHIP:
QuitApplicationDueToError();
break;
}
}
void UMyStoveSDKObject::QuitApplicationDueToError()
{
// 어쩌면 당신은 즉시 앱을 중단하기보다는 사용자에게 앱 중단에 대한 메시지를 보여준 후
// 사용자 액션(e.g. 종료 버튼 클릭)에 따라 앱을 중단하고 싶어 할지도 모릅니다.
// 그렇다면 여기에 당신만의 로직을 구현하십시오.
// 권장하는 필수 사전 작업 오류에 대한 메시지는 아래와 같습니다.
// 한국어 : 필수 사전 작업이 실패하여 게임을 종료합니다.
// 그 외 언어 : The required pre-task fails and exits the game.
OnStoveLog("QuitApplicationDueToError");
FGenericPlatformMisc::RequestExit(false);
}
C++
복사
UMyStoveSDKObject::OnInitComplete 콜백이 오기 전, PC SDK의 초기화 상태 값을 조회할 필요가 있는 경우, UMyStoveSDKObject::GetInitState 함수를 사용할 수 있습니다.
/*StovePC_Init 호출 후...*/
while (Super::GetInitState().State
== StovePCInitState::STOVE_PC_INIT_PENDING)
{
FPlatformProcess::Sleep(0.5f);
RunCallback();
}
if (Super::GetInitState().State
== StovePCInitState::STOVE_PC_INIT_COMPLETE)
{
/*초기화 완료
OnInitComplete 콜백이 호출됨*/
return FStoveResult{STOVE_PC_NO_ERROR};
}
else
{
/*초기화 실패
OnError 콜백이 호출됨*/
}
C++
복사
3. SDK 연동시 주의사항
StoveSDKInit 함수의 파라미터인 FStovePCConfig 구조체의 로그레벨 설정시 Debug 빌드 시에는 StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG 값을 입력하고, 정식 빌드에는 StovePCLogLevel::STOVE_PC_LOG_LEVEL_ERROR 값으로 설정하여 불필요한 로그가 생성되는 것을 방지해 주시기 바랍니다.
PC SDK 초기화가 완료되기 전에 GetToken, GetUser, GetOwnership 메서드를 호출하면 정상적으로 결과를 받지 못할 수 있습니다. 즉, PC SDK초기화 완료를 의미하는 OnInitComplete 콜백함수가 호출된 이후에 PC SDK의 GetToken, GetUser, GetOwnership 함수를 호출해야 정상적으로 결과값을 받을 수 있습니다.
4. SDK 종료
PC SDK 사용이 끝난 뒤에 StoveSDKUnInit함수를 호출하여 사용중인 리소스를 정리합니다. StoveSDKUnInit함수가 호출된 후에는 PC SDK의 API가 동작하지 않습니다.
FStoveResult UMyStoveSDKObject::StoveSDKUnInit()
{
FStoveResult ErrorResult = Super::StoveSDKUnInit();
if (ErorrResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*성공 처리*/
}
return ErrorResult;
}
C++
복사
5. 사용자 정보 얻기
FStoveResult UMyStoveSDKObject::StoveSDKGetUser()
{
FStoveResult ErrorResult = Super::StoveSDKGetUser();
if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*성공 처리*/
}
return ErrorResult;
}
C++
복사
UMyStoveSDKObject::StoveSDKGetUser 함수가 에러없이 실행되면 UMyStoveSDKObject::OnUser 콜백이 호출됩니다.
콜백에 전달되는 StovePCUser 구조체를 통해 사용자의 멤버넘버, 닉네임, 게임사용자아이디 정보들를 알 수 있습니다.
void UMyStoveSDKObject::OnUser(FStoveUser User)
{
/*사용자 정보 출력*/
OnLog("[User]");
OnLog("MemberNo : %u", User.MemberNo);
OnLog("Nickname : %s", *(User.Nickname));
OnLog("GameUserId: %s", *(User.GameUserId));
}
C++
복사
6. 토큰 정보 얻기
UMyStoveSDKObject::StoveSDKGetToken 함수로 STOVE 런처에 로그인한 사용자의 토큰 정보를 얻어 옵니다.
FStoveResult UMyStoveSDKObject::StoveSDKGetToken()
{
FStoveResult ErrorResult = Super::StoveSDKGetToken();
if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
/*성공 처리*/
}
return ErrorResult;
}
C++
복사
UMyStoveSDKObject::StoveSDKGetToken 함수가 정상적으로 처리되면 UMyStoveSDKObject::OnToken 콜백이 호출됩니다.
콜백에 전달되는 StovePCToken 구조체에는 토큰 문자열이 포함되어 있습니다.
void UMyStoveSDKObject::OnToken(FStoveToken Token)
{
/*토큰 정보 출력*/
OnLog("AccessToken : %s", *(Token.AccessToken));
}
C++
복사
토큰이란?
STOVE 런처에 로그인된 사용자의 엑세스토큰(Access Token)으로 게임서버가 이 엑세스토큰을 스토브 인증서버로 전달해서 로그인한 사용자의 유효성 검증을 수행할 수 있습니다. 엑세스토큰에 대한 상세한 설명은 store.support@smilegate.com로 문의 부탁드립니다.
7. 소유권 정보 얻기
UMyStoveSDKObject::StoveSDKGetOwnership함수로 STOVE 런처의 사용자가 STOVE Studio에 등록된 게임을 구매해서 소유하고 있는지 여부를 조회할 수 있습니다.
UMyStoveSDKObject::StoveSDKGetOwnership함수가 정상적으로 처리되면 UMyStoveSDKObject::OnOwnership 콜백이 호출됩니다.
StovePCOwnership 구조체에 대한 세부 정보는 StovePCDefine.h 파일을 참고하세요.
아래는 OnOwnership 콜백에서 게임 구매 여부를 판단하는 예시 코드입니다. DLC가 없는 게임인 경우, 20~23 line의 확인 코드는 불필요합니다.
void UMyStoveSDKObject::OnOwnership(int size, FStoveOwnership* Ownership)
{
bool owned = false;
FStoveOwnership* data = Ownership;
for (int i = 0; i < size; i++, data++)
{
if ((data->MemberNo != LOGIN_USER_MEMBER_NO /*StovePCUser 구조체의 memberNo*/)
|| (data->OwnershipCode != 1 /*1:소유권 획득, 2:소유권 해제(구매 취소한 경우)*/))
{
continue;
}
if (0 == wcscmp(L"YOUR_GAME_ID", *(data->GameId)) && data->GameCode == 3 /* // [GameCode] 3: BASIC 게임, 4: DEMO*/)
{
owned = true; // 소유권 확인 변수 true로 설정
}
/*DLC를 판매하는 게임일 때만 필요*/
if (0 == wcscmp(L"YOUR_DLC_ID", *(data->GameId)) && data->GameCode == 5 /* 5: DLC*/)
{
/*YOUR_DLC_ID(DLC ID) 소유권이 있기에 DLC 플레이 허용*/
}
}
if(owned)
{
// 소유권 검증이 정상적으로 완료된 이후 게임진입 로직 작성
}
else
{
// 소유권 검증실패 후 게임을 종료하고 에러메세지 표출 로직 작성
}
}
C++
복사
•
게임을 구매한 계정(소유권 보유)으로 STOVE 런처에 로그인한 후 게임을 플레이를 할 수 있습니다.
•
게임 소유권이 없는 계정으로 STOVE 런처에 로그인한 후 exe 실행 시 아래 안내 메시지(예시)를 출력한 후 게임을 종료합니다.
◦
한국어 외의 OS : "Please log in to STOVE Client with the account that has purchased the game."
◦
한국어 : "게임을 구매한 계정으로 STOVE 클라이언트에 로그인하시기 바랍니다."
8. 언어 설정
UMyStoveSDKObject::StoveSDKSetLanguage 함수로 언어를 설정합니다.
PC SDK는 초기화시 시스템 언어(운영체제 언어)를 이용하여 언어를 기본으로 설정합니다.
명시적으로 시스템 언어(운영체제 언어)를 설정하려면 파라미터로 system을 입력합니다.
특정 언어를 설정하기 위해서는 초기화 성공 이후(e.g. OnInitComplete) UMyStoveSDKObject::StoveSDKSetLanguage 함수를 호출합니다.
FStoveResult UMyStoveSDKObject::StoveSDKSetLanguage(const FString& Language)
{
FStoveResult ErrorResult = Super::StoveSDKSetLanguage(Language);
if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
{
// 성공처리
}
return ErrorResult;
}
C++
복사
9. 언어 번역
UMyStoveSDKObject::StoveSDKTranslateLanguage 함수로 언어를 번역합니다.
PC SDK는 설정된 언어 정보를 기반으로 특정 문자열에 대한 번역본을 제공합니다.
특정 문자열은 PC SDK 에서 관리하는 문자열 아이디(String Id)로 관리됩니다.
게임에서 PC SDK 팝업 UI 를 직접 구현하는 경우 UI에 표시되는 문자열은 UMyStoveSDKObject::StoveSDKTranslateLanguage 함수를 통해 번역된 문자열을 표시해야 합니다.
FString Translated=UMyStoveSDKObject::StoveSDKTranslateLanguage("STRING_ID");
C++
복사
주의사항
PC SDK에 설정된 언어에 대해 특정 문자열의 번역본이 없는 경우 영어 번역본을 리턴하며,
예외 발생 또는 지원하지 않는 문자열 아이디에 대해서는 입력 파라미터(문자열 아이디)를 그대로 리턴합니다.