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

연동하기

생성일
2024/03/14 22:24
태그
상위 항목
하위 항목

1. RunCallback

PC SDK의 API는 게임엔진 및 게임로직에 방해가 되지 않도록 대부분 비동기로 수행됩니다. API 호출에 대한 결과는 PC SDK 내부의 큐에 적재되며 게임이 API 호출에 대한 결과를 처리하려 할 때 RunCallback 메서드를 호출함으로써 등록한 콜백이 실행됩니다. 보통 RunCallback 메서드의 호출은 코루틴을 이용하여 작성하며 호출 주기는 설정이 가능 합니다.
private IEnumerator RunCallback(float intervalSeconds) { WaitForSeconds wfs = new WaitForSeconds(intervalSeconds); while (true) { StovePC.RunCallback(); yield return wfs; } }
Plain Text
복사
코루틴은 MonoBehaviour.StartCoroutine 메서드를 통해 시작하며 일반적으로 PC SDK 초기화가 성공하면 시작하고 PC SDK 종료가 성공하면 중지합니다.
PC SDK 종료 성공 후 RunCallback 코루틴의 중지를 위해 멤버 변수를 이용하는 방법이 있습니다.
private Coroutine runcallbackCoroutine;
Plain Text
복사
게임프로젝트에 멤버변수로 선언된 runcallbackCoroutine을 아래 코드와 같이 StartCoroutine함수와 StopCoroutine함수를 사용해 타이머처럼 동작시킬 수 있습니다.
public void ToggleRunCallback_ValueChanged(bool isOn) { if (isOn) { float intervalSeconds = 1f; runcallbackCoroutine = StartCoroutine(RunCallback(intervalSeconds)); WriteLog("RunCallback Start"); } else { if (runcallbackCoroutine != null) { StopCoroutine(runcallbackCoroutine); runcallbackCoroutine = null; WriteLog("RunCallback Stop"); } } }
Plain Text
복사

2. Config, Callback 설정

PC SDK를 초기화하기 위해서는, 먼저 StovePCConfig와 StovePCCallback 구조체에 값을 채운 뒤, StovePC.Initialize 메서드를 호출합니다. 아래 코드를 참고하여 멤버변수를 이용하여 StovePCConfig 구조체의 각 필드 값을 채웁니다. 해당 멤버변수는 유니티 에디터의 인스펙터를 통해 값을 설정합니다.
[SerializeField] private string env; [SerializeField] private string appKey; [SerializeField] private string appSecret; [SerializeField] private string gameId; [SerializeField] private StovePCLogLevel logLevel; [SerializeField] string logPath; StovePCConfig config = new StovePCConfig { Env = env, AppKey = appKey, AppSecret = appSecret, GameId = gameId, LogLevel = logLevel, LogPath = logPath };
Plain Text
복사
"YOUR_APP_KEY", "YOUR_SECRET_KEY", "YOUR_GAME_ID"는 스토브 스튜디오에서 발급 받은 키값으로 데이터로 변경해야 됩니다.
스토브 런처에 로그인 하지 않은 상태로 StovePC.Initialize 메서드를 호출하면 에러가 발생하니 사전에 스토브 런처를 실행하고 로그인합니다.
주의사항 PC SDK 로그경로는 절대적경로로 설정해야 합니다. ex) C:\Program Files\{Your Game Folder}\Logs 마지막에 "\"는 추가하지 않습니다. PCSDK 에서 "StovePCSDK.log" 파일명을 자동으로 추가합니다. 만약 "" 빈문자열로 경로를 설정하게 되면 PC SDK는 자동적으로 게임실행파일 폴더 또는 PC SDK DLL 이 위치한 폴더의 경로로 로그가 생성됩니다. 게임과 PC SDK간의 연동은 C# 델리게이트(Delegate)을 사용합니다. 게임에서는 아래 StovePCCallback 클래스의 콜백에 연결할 델리게이트 메서드를 정의해야 합니다.
public class StovePCCallback { // StovePCSDK 에서 에러발생시 호출되는 콜백 public StovePCErrorDelegate OnError; // PC SDK 초기화가 완료됐을 때 호출되는 콜백 public StovePCInitializationCompleteDelegate OnInitializationComplete; // GetToken 처리가 완료됐을 때 호출되는 콜백 public StovePCTokenDelegate OnToken; // GetUser 처리가 완료됐을 때 호출되는 콜백 public StovePCUserDelegate OnUser; // GetOwnership 처리가 완료됐을 때 호출되는 콜백 public StovePCOwnershipDelegate OnOwnership; }
Plain Text
복사
여기서 주의할 점이 있는데 StovePCCallback 객체는 PC SDK가 종료될 때까지 보존되어야 합니다. 그 이유는 StovePCCallback 객체가 가비지 컬렉팅이 되면 PC SDK 내부에서는 콜백을 호출 할 수 없기 때문입니다.
이 점을 충족시키기 위해 StovePCCallback 클래스를 게임프로젝트 클래스의 멤버변수로 선언해서 가비지 컬렉팅이 되지 않도록 하여 해결할 수 있습니다.
private StovePCCallback callback;
Plain Text
복사
// 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) };
Plain Text
복사
필수적으로 연동해야 하는 OnErrorOnInitializationComplete, OnOwnership 콜백함수 외의 나머지 콜백함수는 필요 시에만 연동을 하면 됩니다. 예를 들어, 소유권(Ownership) 기능만 사용하는 경우, 아래와 같이 델리게이트 메소드로 연결하면 됩니다.
/* 소유권(Ownership) 기능만 사용하는 경우는, 필수 구현 콜백인 OnError, OnInitializationComplete 외에 OnOwnership 콜백만 추가로 구현해서 연결합니다. */ this.callback = new StovePCCallback { OnError = new StovePCErrorDelegate(this.OnError), OnInitializationComplete = new StovePCInitializationCompleteDelegate(this.OnInitializationComplete), OnOwnership = new StovePCOwnershipDelegate(this.OnOwnership) };
Plain Text
복사

3. SDK 초기화

PC SDK를 초기화하기 위해 StovePC.Initialize 메서드를 호출합니다.
StovePCResult sdkResult = StovePC.Initialize(config, this.callback); if (StovePCResult.NoError == sdkResult) { this.runCallbackCoroutine = StartCoroutine(RunCallback(0.5f)); // 초기화 오류가 없어 RunCallback 주기적 호출 } else { // 초기화 실패로 게임 종료 }
Plain Text
복사
StovePC.Initialize 메서드는 config와 callback의 유효성 여부만 확인한 후, 즉시 StovePCResult enum 타입 값을 반환합니다.
성공한 경우, StovePCResult.NoError 값이 반환됩니다. 실패한 경우는 해당 에러 코드를 반환하며 게임 종료를 처리해야 합니다.
반환값이 StovePCResult.NoError, 즉 '성공'인 경우, StovePC.RunCallback 메서드를 주기적으로 호출해 줍니다.
StovePC.RunCallback 메서드를 주기적으로 호출해야만, 연결된 콜백이 정상적으로 호출됩니다.
호출 주기가 길면 콜백의 응답 속도도 느려지게 되므로, 적당한 호출 주기를 유지하는 것이 좋습니다. 예제코드에서는 1초에 한번 콜백함수가 호출되는 것으로 설정했습니다.
StovePC_RunCallback 함수를 비롯하여 PCSDK와 연동되는 Callback함수들은 반드시 메인스레드에서 호출하도록 코드를 작성해주시기 바랍니다.
StovePC.Initialize 메서드는 config와 callback 유효성 확인을 제외한, 그 외의 작업을 비동기로 처리합니다.
비동기 작업이 성공적으로 완료된 경우, OnInitializationComplete 콜백이 호출되며, 에러가 발생한 경우는 OnError 콜백이 호출됩니다.
에러가 발생한 경우, 전달된 StovePCError 구조체를 통해 에러 코드, 메시지 등을 확인할 수 있습니다.
private void OnInitializationComplete() { Debug.Log("PC SDK initialization success"); } private void OnError(StovePCError error) { #region Log StringBuilder sb = new StringBuilder(); sb.AppendLine("OnError"); sb.AppendFormat(" - error.FunctionType : {0}" + Environment.NewLine, error.FunctionType.ToString()); sb.AppendFormat(" - error.Result : {0}" + Environment.NewLine, (int)error.Result); sb.AppendFormat(" - error.Message : {0}" + Environment.NewLine, error.Message); sb.AppendFormat(" - error.ExternalError : {0}", error.ExternalError.ToString()); WriteLog(sb.ToString()); #endregionswitch (error.FunctionType) { case StovePCFunctionType.Initialize: case StovePCFunctionType.GetUser: case StovePCFunctionType.GetOwnership: BeginQuitAppDueToError(); break; } } private void BeginQuitAppDueToError() { #region Log StringBuilder sb = new StringBuilder(); sb.AppendLine("BeginQuitAppDueToError"); sb.AppendFormat(" - nothing"); WriteLog(sb.ToString()); #endregion// 어쩌면 당신은 즉시 앱을 중단하기보다는 사용자에게 앱 중단에 대한 메시지를 보여준 후 // 사용자 액션(e.g. 종료 버튼 클릭)에 따라 앱을 중단하고 싶어 할지도 모릅니다. // 그렇다면 여기에 QuitApplication을 지우고 당신만의 로직을 구현하십시오. // 권장하는 필수 사전 작업 오류에 대한 메시지는 아래와 같습니다. // 한국어 : 필수 사전 작업이 실패하여 게임을 종료합니다. // 그 외 언어 : The required pre-task fails and exits the game. QuitApplication(); }
Plain Text
복사
OnInitializationComplete 콜백이 오기 전, PC SDK의 초기화 상태 값을 조회할 필요가 있는 경우, StovePC.GetInitializationState 함수를 사용할 수 있습니다.`
// StovePC.Initialize 호출 후... while (StovePC.GetInitializationState() == StovePCInitializationState.Pending) { Thread.Sleep(500); StovePC.RunCallback(); } if (StovePC.GetInitializationState() == StovePCInitializationState.Complete) { // 초기화 완료 OnInitializationComplete 콜백이 호출됨 } else { // 초기화 실패 OnError 콜백이 호출됨 }
Plain Text
복사

4. SDK 연동시 주의사항

초기화가 완료되기 전에 GetTokenGetUserGetOwnership 메서드를 호출하면 정상적으로 결과를 받지 못할 수 있습니다. 즉, OnInitializationComplete 콜백이 정상적으로 수신된 이후에 GetTokenGetUserGetOwnership 메서드를 호출해야 정상적으로 결과를 받을 수 있습니다.
StovePCConfig 구조체의 로그레벨 설정시 PC SDK 테스트 시에는 StovePCLogLevel.Debug 값을 입력하고, 정식 빌드에는 StovePCLogLevel.Error 값으로 설정하여 불필요한 로그가 생성되는 것을 방지해 주시기 바랍니다.

5. SDK 종료

PC SDK 사용이 끝난 뒤에 호출하여 사용중인 리소스를 정리합니다. StovePC.Uninitialize 메서드가 호출된 후에는 PC SDK의 API가 동작하지 않습니다. StovePC.Uninitialize 메서드 호출 전 또는 후에 반드시 StopCoroutine함수로 runcallbackCoroutine 코루틴 실행을 중지시켜야 합니다.
StovePCResult result = StovePC.Uninitialize(); if (result == StovePCResult.NoError) { // 성공 처리 }
Plain Text
복사

6. 사용자 정보 얻기

StovePC.GetUser 메서드로 스토브 런처 (opens new window)에 로그인한 사용자 정보를 확인 할 수 있습니다.
StovePCResult result = StovePC.GetUser(); if (result == StovePCResult.NoError) { // 성공 처리 }
Plain Text
복사
StovePC.GetUser 메서드가 정상적으로 처리되면 OnUser 콜백이 호출됩니다.
콜백에 전달되는 StovePCUser 구조체를 통해 사용자의 member_no (스토브 고유 회원번호), 닉네임, guid (스토브의 게임 별 고유 회원번호, 게임 약관 동의시에 발급) 정보들를 알 수 있습니다.
private void OnUser(StovePCUser user) { // 사용자 정보 출력 StringBuilder sb = new StringBuilder(); sb.AppendLine("OnUser"); sb.AppendFormat(" - user.MemberNo : {0}" + Environment.NewLine, user.MemberNo.ToString()); sb.AppendFormat(" - user.Nickname : {0}" + Environment.NewLine, user.Nickname); sb.AppendFormat(" - user.GameUserId : {0}", user.GameUserId); Debug.Log(sb.ToString()); }
Plain Text
복사

7. 토큰 정보 얻기

StovePC.GetToken 메서드로 스토브 런처에 로그인한 사용자의 토큰 정보를 얻어 옵니다.
StovePCResult result = StovePC.GetToken(); if (result == StovePCResult.NoError) { // 성공 처리 }
Plain Text
복사
StovePC.GetToken 메서드가 정상적으로 처리되면 OnToken 콜백이 호출됩니다.
콜백에 전달되는 StovePCToken 구조체에는 토큰 문자열이 포함되어 있습니다.
private void OnToken(StovePCToken token) { // 토큰 정보 출력 StringBuilder sb = new StringBuilder(); sb.AppendLine("OnToken"); sb.AppendFormat(" - token.AccessToken : {0}", token.AccessToken); Debug.Log(sb.ToString()); }
Plain Text
복사
토큰이란? STOVE 런처에 로그인된 사용자의 엑세스 토큰(Access Token)으로 게임서버가 이 엑세스토큰을 스토브 인증서버로 전달해서 로그인한 사용자의 유효성 검증을 수행할 수 있습니다. 엑세스토큰에 대한 상세한 설명은 스토브 스토어로 문의 부탁드립니다.

8. 소유권 정보 얻기

StovePC.GetOwnership 메서드로 스토브 런처 사용자가 해당 게임을 구매해서 소유하고 있는지 여부를 조회합니다.
StovePCResult result = StovePC.GetOwnership(); if (result == StovePCResult.NoError) { // 성공 처리 }
Plain Text
복사
StovePC.GetOwnership 메서드가 정상적으로 처리되면 OnOwnership 콜백이 호출됩니다.
아래는 OnOwnership 콜백에서 게임 구매 여부를 판단하는 예시 코드입니다.
DLC가 없는 게임인 경우, 22~27 line의 확인 코드는 불필요합니다.
private void OnOwnership(StovePCOwnership[] ownerships) { bool owned = false; foreach(var ownership in ownerships) { // [LOGIN_USER_MEMBER_NO] StovePCUser 구조체의 MemberNo // [OwnershipCode] 1: 소유권 획득, 2: 소유권 해제(구매 취소한 경우) if (ownership.MemberNo != LOGIN_USER_MEMBER_NO || ownership.OwnershipCode != 1) { continue; } // [GameCode] 3: BASIC 게임, 4: DEMO if (ownership.GameId == "YOUR_GAME_ID" && ownership.GameCode == 3) { owned = true; // 소유권 확인 변수 true로 설정 } // DLC를 판매하는 게임일 때만 필요 if (ownership.GameId == "YOUR_DLC_ID" && ownership.GameCode == 5) { // YOUR_DLC_ID(DLC) 소유권이 있기에 DLC 플레이 허용 } } if(owned) { // 소유권 검증이 정상적으로 완료 된 이후 게임진입 로직 작성 } else { // 소유권 검증실패 후 게임을 종료하고 에러메세지 표출 로직 작성 } }
Plain Text
복사
게임을 구매한 계정(소유권 보유)으로 STOVE 클라이언트에 로그인한 후 게임을 플레이를 할 수 있습니다.
게임 소유권이 없는 계정으로 STOVE 클라이언트에 로그인한 후 exe 실행 시 아래 안내 메시지(예시)를 출력한 후 게임을 종료합니다.
한국어 외의 OS : Please log in to STOVE Client with the account that has purchased the game
한국어 : 게임을 구매한 계정으로 STOVE 클라이언트에 로그인하시기 바랍니다
게임 소유권이 있는 계정이 없어도 소유권 기능을 테스트할 수 있으며, 자세한 방법은 여기를 확인하시기 바랍니다.
또한 소유권 (Ownership) 호출 <GetOwnership Success> 후에 output_log.txt 혹은 Player.log에 아래와 같은 로그 추가 부탁 드립니다.
예시 : 성공: 소유권이 있는 유저입니다. 실패: 소유권이 없는 유저입니다.
Plain Text
복사

9. 언어 설정

StovePC.SetLanguage 함수로 언어를 설정합니다.
PC SDK는 초기화시 시스템 언어(운영체제 언어)를 이용하여 언어를 기본으로 설정합니다.
명시적으로 시스템 언어(운영체제 언어)를 설정하려면 파라미터로 system을 입력합니다.
특정언어를 설정하기 위해서는 초기화 성공 이후(e.g. OnInitializationComplete) StovePC.SetLanguage 함수를 호출합니다.
StovePCResult result = StovePC.SetLanguage("LANGUAGE_CODE"); if (result == StovePCResult.NoError) { // 성공 처리 }
Plain Text
복사

10. 언어 번역

StovePC.TranslateLanguage 함수로 언어를 번역합니다.
PC SDK는 설정된 언어 정보를 기반으로 특정 문자열에 대한 번역본을 제공합니다.
특정 문자열은 PC SDK 에서 관리하는 문자열 아이디(String ID)로 관리됩니다.
게임에서 PC SDK 팝업 UI 를 직접 구현하는 경우 UI에 표시되는 문자열은 StovePC.TranslateLanguage 함수를 통해 번역된 문자열을 표시해야 합니다.
string translated = StovePC.TranslateLanguage("STRING_ID");
Plain Text
복사
주의사항 PC SDK에 설정된 언어에 대해 특정 문자열의 번역본이 없는 경우 영어 번역본을 리턴하며, 예외 발생 또는 지원하지 않는 문자열 아이디에 대해서는 입력 파라미터(문자열 아이디)를 그대로 리턴합니다.