- 마지막 업데이트
Mobile SDK 3.0.0 마이그레이션 가이드 - Unreal
01. 개요
이 가이드는 Unreal 프로젝트의 Mobile SDK 를 2.9.x 에서 3.0.0 으로 올리는 방법을 설명합니다.
적용 대상: Unreal 로 Mobile SDK 를 연동한 게임
적용 범위: Mobile SDK 2.9.x → 3.0.0 / iOS · Android
3.0.0 에서 SDK 플러그인 16개가 4개로 통합되면서, 플러그인 이름 · 모듈 이름 · Android Gradle 좌표가 변경되었습니다.
플러그인 폴더 교체 + 빌드 구성 파일 3개 수정이 기본이고, iOS 는 엔진의 URL 수신 경로 정리가 함께 필요합니다.
⚠️ 이 가이드는 2.9.x 가 이미 연동된 상태를 가정합니다.
신규 연동이라면 처음부터 3.0.0 기준으로 연동하면 되므로 이 문서는 필요하지 않습니다.
| # | 대상 | 무엇을 | 플랫폼 |
|---|---|---|---|
| 1 | <Project>/Plugins/ | 기존 SGS_* 폴더 삭제 → 새 플러그인 복사 | 공통 |
| 2 | <Project>.uproject | 기존 SGS_* 항목 삭제 → 신규 플러그인 등록 | 공통 |
| 3 | 게임 모듈 .Build.cs | 의존 모듈 16개 → 4개 | 공통 |
| 4 | <Project>_APL.xml | Gradle 좌표 17줄 → 4줄 | Android |
| 5 | 엔진 소스 · 게임 코드의 URL 수신 경로 | OnOpenURLwithOptions → OnOpenURL | iOS |
02. 사전 조건
- SDK 배포본: Mobile SDK 3.0.0 이상 Unreal 플러그인 다운로드
- 기존 연동: Mobile SDK 2.9.x 가 연동되어 빌드가 성공하는 상태
- 빌드 환경: iOS 패키징과 Android 빌드를 모두 수행할 수 있는 환경
- iOS 최소 지원 버전: 15.0 이상 —
Config/DefaultEngine.ini의MinimumiOSVersion이IOS_15이상 - 엔진 소스 수정 권한 (iOS): 2.9.x 연동 시 적용한 커스텀 엔진을 수정하고 다시 빌드할 수 있는 환경 — Step.5 에서 필요합니다
⚠️ 3.0.0 의 iOS 프레임워크는 iOS 15.0 이상을 지원합니다.
MinimumiOSVersion이IOS_13·IOS_14이면 패키징은 성공하지만, iOS 13 · 14 기기에서 앱이 실행되지 않습니다.
03. 절차
Step.1 플러그인 폴더 교체
프로젝트의 SDK 플러그인을 3.0.0 이상 플러그인으로 교체합니다.
<Project>/Plugins/에서SGS_로 시작하는 폴더를 모두 삭제합니다.- 다운로드한 플러그인 폴더를
<Project>/Plugins/에 복사합니다. 사용하는 기능에 맞춰 고릅니다.
| 플러그인 | 필요 여부 |
|---|---|
Stove | 항상 필요 — 나머지 플러그인이 모두 의존합니다 |
StoveProviders | 외부 로그인(Google · Facebook · Apple · Naver · Line · Steam · GPG)을 사용하는 경우 |
StoveIAP | 결제를 사용하는 경우 |
StovePush | 푸시를 사용하는 경우 |
- 같은 프로젝트를 2.9.x 로 빌드한 적이 있다면
<Project>/Binaries/와<Project>/Intermediate/를 삭제합니다.
⚠️ 기존
SGS_*폴더가 남아 있으면 iOS 에서 중복 심볼 링커 에러가 발생합니다. 덮어쓰지 말고 삭제한 뒤 복사하십시오.
⚠️ 2.9.x 빌드 산출물이 남아 있으면 iOS 패키지에 2.9.x 리소스 번들(
SGS*Resources.bundle)이 함께 포함됩니다. 빌드는 성공하므로 3번을 건너뛰지 마십시오.
확인:
Plugins/아래에SGS_로 시작하는 폴더가 없고, 위 표에서 고른 플러그인 폴더가 있습니다.
Step.2 .uproject 의 플러그인 목록 정리
<Project>.uproject 를 열고 "Plugins" 배열에 SGS_ 로 시작하는 항목이 있으면 모두 삭제합니다.
/******************** remove ********************/
{ "Name": "SGS_Base", "Enabled": true },
{ "Name": "SGS_Auth", "Enabled": true },
{ "Name": "SGS_AuthUI", "Enabled": true },
{ "Name": "SGS_Log", "Enabled": true },
{ "Name": "SGS_View", "Enabled": true },
{ "Name": "SGS_Auth_Google", "Enabled": true },
{ "Name": "SGS_Auth_Facebook", "Enabled": true },
{ "Name": "SGS_Auth_UApple", "Enabled": true },
{ "Name": "SGS_Auth_Naver", "Enabled": true },
{ "Name": "SGS_Auth_Line", "Enabled": true },
{ "Name": "SGS_Auth_Steam", "Enabled": true },
{ "Name": "SGS_Auth_GooglePlayGames", "Enabled": true },
{ "Name": "SGS_IAP", "Enabled": true },
{ "Name": "SGS_IAP_Google", "Enabled": true },
{ "Name": "SGS_Push", "Enabled": true },
{ "Name": "SGS_Push_Firebase", "Enabled": true }
/***********************************************/
그 자리에 Step.1 에서 복사한 플러그인을 등록합니다.
/********************* add **********************/
{ "Name": "Stove", "Enabled": true },
{ "Name": "StoveProviders", "Enabled": true },
{ "Name": "StoveIAP", "Enabled": true },
{ "Name": "StovePush", "Enabled": true }
/***********************************************/
예외 처리
"Plugins"배열에SGS_항목이 없는 경우: 삭제할 것이 없습니다. 프로젝트Plugins/폴더의 플러그인은 등록하지 않아도 기본으로 활성화되므로, 신규 항목 등록도 생략할 수 있습니다.
💡 Tip 1: 배열의 마지막 항목 뒤에는 쉼표를 붙이지 않고, 그 외 항목 뒤에는 반드시 붙입니다. 쉼표가 빠지면 빌드 시작 시
JsonReaderException: '{' is invalid after a value가 출력됩니다.
💡 Tip 2:
"Enabled": false로 남겨두지 마십시오. 3.0.0 에는 해당 플러그인 폴더가 없어 목록만 불필요하게 남습니다.
확인: 파일 안에
SGS_문자열이 하나도 남아 있지 않습니다.
Step.3 게임 모듈 .Build.cs 의 의존 모듈 교체
게임 모듈이 참조하는 SDK 모듈 이름을 새 플러그인 이름으로 바꿉니다.
Source/<Project>/<Project>.Build.cs 의 PublicDependencyModuleNames 를 확인합니다.
PublicDependencyModuleNames.AddRange(new string[] {
"Core", "CoreUObject", "Engine", "InputCore",
/******************** remove ********************/
"SGS_Base", "SGS_Log", "SGS_Auth", "SGS_AuthUI", "SGS_View",
"SGS_IAP", "SGS_IAP_Google", "SGS_Push", "SGS_Push_Firebase",
"SGS_Auth_Google", "SGS_Auth_Facebook", "SGS_Auth_UApple",
"SGS_Auth_Naver", "SGS_Auth_Line", "SGS_Auth_Steam",
"SGS_Auth_GooglePlayGames"
/***********************************************/
});
remove 구간을 지우고 Step.1 에서 고른 플러그인 이름을 넣습니다.
PublicDependencyModuleNames.AddRange(new string[] {
"Core", "CoreUObject", "Engine", "InputCore",
/********************* add **********************/
"Stove", "StoveProviders", "StoveIAP", "StovePush"
/***********************************************/
});
"Core"등 엔진 모듈은 그대로 둡니다.PublicAdditionalFrameworks는 수정하지 않습니다. iOS 프레임워크 링크는 SDK 플러그인이 처리합니다.
⚠️ Step.1 에서 복사하지 않은 플러그인은 넣지 마십시오.
없는 모듈 이름이 있으면 빌드 시작 단계에서Could not find definition for module로 중단됩니다.
확인: 파일 안에
SGS_문자열이 하나도 남아 있지 않습니다.
Step.4 <Project>_APL.xml 의 Gradle 좌표 교체 (Android)
Android 빌드에 주입되는 SDK 의존성 좌표를 3.0.0 좌표로 바꿉니다.
Source/<Project>/<Project>_APL.xml 의 buildGradleAdditions → dependencies 블록에서 com.stove: 로 시작하는 줄을 모두 지웁니다. 지울 줄의 버전(2.9.0 · 2.9.1 등)은 프로젝트마다 다를 수 있습니다.
dependencies {
/******************** remove ********************/
implementation 'com.stove:base:2.9.x'
implementation 'com.stove:log:2.9.x'
implementation 'com.stove:auth:2.9.x'
implementation 'com.stove:gamingservices:2.9.x'
implementation 'com.stove:auth-facebook:2.9.x'
implementation 'com.stove:auth-google:2.9.x'
implementation 'com.stove:auth-apple:2.9.x'
implementation 'com.stove:auth-naver:2.9.x'
implementation 'com.stove:auth-googleplaygames:2.9.x'
implementation 'com.stove:auth-line:2.9.x'
implementation 'com.stove:auth-steam:2.9.x'
implementation 'com.stove:auth-ui:2.9.x'
implementation 'com.stove:iap:2.9.x'
implementation 'com.stove:iap-google:2.9.x'
implementation 'com.stove:push:2.9.x'
implementation 'com.stove:push-firebase:2.9.x'
implementation 'com.stove:view:2.9.x'
/***********************************************/
}
그 자리에 Step.1 에서 고른 플러그인에 해당하는 좌표를 넣습니다. 아래는 3.0.0 기준 예시이며, 버전은 다운로드한 플러그인의 버전으로 적습니다.
dependencies {
/********************* add **********************/
// 예시: 3.0.0 기준 — 다운로드한 플러그인의 버전으로 바꿉니다
implementation 'com.stove:stove:3.0.0'
implementation 'com.stove:stove-providers:3.0.0'
implementation 'com.stove:stove-iap-google:3.0.0'
implementation 'com.stove:stove-push-firebase:3.0.0'
/***********************************************/
}
| 플러그인 | 좌표 |
|---|---|
Stove | com.stove:stove |
StoveProviders | com.stove:stove-providers |
StoveIAP | com.stove:stove-iap-google |
StovePush | com.stove:stove-push-firebase |
예외 처리
- Android 를 빌드하지 않는 경우: 이 단계는 건너뜁니다.
_APL.xml을 게임이 별도로 관리하는 경우: 파일 위치가 달라도dependencies블록의com.stove:*좌표를 같은 규칙으로 바꾸면 됩니다.
⚠️
com.google.android.gms:play-services-games-v2:19.0.0줄은 그대로 둡니다.
게임 로그인(GPG)에 필요한 구글 의존성이라,com.stove:*를 지울 때 함께 지우면 GPG 로그인이 실패합니다.
💡 Tip:
com.stove:stove-iap·com.stove:stove-push는 적지 않아도 됩니다.stove-iap-google·stove-push-firebase가 의존성으로 함께 가져옵니다.
확인:
com.stove:로 시작하는 좌표가 Step.1 에서 고른 플러그인 수와 같고,2.9버전이 하나도 없으며,play-services-games-v2줄이 남아 있습니다.
Step.5 iOS URL 수신 경로 정리 (엔진 · 게임 코드)
외부 로그인과 STOVE 앱 간 인증 후 게임으로 돌아오는 URL 을 3.0.0 SDK 가 받을 수 있도록 엔진과 게임 코드를 정리합니다.
2.9.x 와 3.0.0 은 URL 을 받는 엔진 delegate 가 다릅니다.
| 2.9.x | 3.0.0 | |
|---|---|---|
| SDK 가 사용하는 delegate | FIOSCoreDelegates::OnOpenURLwithOptions | FIOSCoreDelegates::OnOpenURL |
| 엔진 요구사항 | 8) LSSupportsOpeningDocumentsInPlace 사용 패치 | 8) 패치 없음 |
SceneDelegate 적용 절차
SceneDelegate 는 Apple 정책에 따라 2027년 4월부터 AppStore에 제출되는 모든 서비스에 필수적으로 요구됩니다.
① 엔진 — 8) 패치 제거
2.9.x 연동 시 개발 환경 설정 8) LSSupportsOpeningDocumentsInPlace 사용 에 따라 엔진의 IOSAppDelegate.h · IOSAppDelegate.cpp 에 추가한 코드 — OnOpenURLwithOptions · savedOpenUrlWithOptionsParameters · application:openURL:options: — 를 모두 제거합니다.
② 엔진 — SceneDelegate 대응 업데이트 적용
개발 환경 설정의 iOS Unreal UISceneDelegate 대응 업데이트 를 STOVE SDK 3.0.0 이상 기준으로 적용합니다. 이 문서의 절차로 OnOpenURL 전달 경로가 구성됩니다.
③ 게임 코드 — OnOpenURLwithOptions 바인딩 교체
게임 코드에서 FIOSCoreDelegates::OnOpenURLwithOptions 에 바인딩한 곳(딥링크 처리 등)이 있으면 OnOpenURL 로 바꿉니다.
/******************** remove ********************/
static void OnOpenURLwithOptions(UIApplication* application, NSURL* url, NSDictionary* options)
{
// 게임 처리
}
FIOSCoreDelegates::OnOpenURLwithOptions.AddStatic(&OnOpenURLwithOptions);
/***********************************************/
/********************* add **********************/
static void OnOpenURL(UIApplication* application, NSURL* url, NSString* sourceApplication, id annotation)
{
// 게임 처리 (본문은 그대로)
}
FIOSCoreDelegates::OnOpenURL.AddStatic(&OnOpenURL);
/***********************************************/
⚠️ 8) 패치를 그대로 두면 빌드는 성공하지만 외부 로그인 후 게임으로 돌아와도 로그인이 완료되지 않습니다.
8) 패치가 추가한application:openURL:options:가 있으면 iOS 가OnOpenURL경로를 호출하지 않아, 3.0.0 SDK 가 URL 을 받지 못합니다. 빌드에서는 드러나지 않습니다.
⚠️ ① 을 적용한 뒤 ③ 을 빠뜨리면 컴파일에 실패합니다. 패치를 제거한 엔진에는
OnOpenURLwithOptions가 없습니다.
💡 Tip: SDK 의 URL 전달은
Stove플러그인이 처리합니다. 게임 코드에서SGSApplicationDelegate를 직접 호출할 필요가 없습니다.
확인: 엔진 소스와 게임 코드에서
OnOpenURLwithOptions를 검색했을 때 결과가 없습니다.
SceneDelegate 를 당장 적용하기 어려운 경우
위 ① ~ ③ 은 SceneDelegate 를 적용하는 절차입니다. 당장 적용하기 어렵다면 ① ~ ③ 을 진행하기 전에 개발팀에 문의해 주십시오. 프로젝트 상황에 맞는 적용 방법을 안내합니다.
Step.6 빌드 확인
iOS 와 Android 를 모두 빌드해 마이그레이션이 완료되었는지 확인합니다.
Step.1 ~ Step.3 에서 수정한 파일은 iOS 와 Android 가 함께 사용합니다. 한 플랫폼만 빌드하면 다른 플랫폼의 문제를 발견하지 못할 수 있으므로, 반드시 두 플랫폼 모두 빌드해 주십시오.
-
Plugins/의SGS_폴더와 2.9.x 빌드 산출물(Binaries/·Intermediate/) 삭제 -
.uproject·.Build.cs에SGS_문자열 없음 -
_APL.xml의com.stove:좌표가 Step.1 에서 고른 플러그인과 일치,2.9버전 좌표 없음 - (iOS)
MinimumiOSVersion을IOS_15이상으로 설정 - (iOS) 엔진 소스와 게임 코드에
OnOpenURLwithOptions없음 - iOS 패키징 성공 (중복 심볼 링커 에러 없음)
- Android 빌드 성공
Step.7 실기기 확인
⚠️ 빌드 성공으로 끝내지 마십시오.
iOS 의 URL 수신 경로(Step.5)와 최소 지원 버전은 빌드에서 드러나지 않습니다.
양 플랫폼에서 아래 항목을 수행하십시오.
- 로그인 → 게임 진입
- 외부 로그인(Google · Apple · Naver 등) 후 앱 복귀 (iOS) — Step.5 를 검증하는 유일한 경로
- 결제 (
StoveIAP사용 시) - 푸시 수신 (
StovePush사용 시)
항목별 절차와 실패 시 의심할 지점은 별도 문서 Mobile SDK 3.0.0 실기기 스모크 체크리스트(Unreal) 에 있습니다. 플랫폼당 20분 정도 걸립니다.
04. 참고
⚠️ 주의사항
- 기존
SGS_*플러그인 폴더는 삭제합니다. 남아 있으면 iOS 에서 중복 심볼 링커 에러가 발생합니다.play-services-games-v2줄은 삭제하지 마십시오. 삭제하면 GPG 로그인이 실패합니다.- iOS 는 8) 엔진 패치를 제거합니다. 남아 있으면 외부 로그인 후 앱으로 돌아와도 로그인이 완료되지 않습니다.
💡 고치지 않아도 되는 것
- 헤더
#include—Auth.h·User.h·GoogleProvider.h등 파일 이름이 그대로입니다. 단, 모듈 헤더(SGS_Base.h·SGS_Auth.h등SGS_*.h)는 3.0.0 에 없으므로 include 하고 있다면 삭제하십시오.- SDK 호출 코드 —
stove::함수 시그니처가 동일합니다. 로그인 · 연동 · 결제 · 푸시 호출부를 그대로 둡니다.- Java
import— 패키지 이름이 유지됩니다.AndroidManifestmeta-data 키 —com.stove.*키 이름이 그대로입니다.- iOS 프레임워크 설정 — 게임 프로젝트에서 지정할 것이 없습니다.
플러그인 대응표
| AS-IS · 2.9.x | TO-BE · 3.0.0 |
|---|---|
SGS_Base SGS_Log SGS_Auth SGS_AuthUI SGS_View | Stove ※ |
SGS_Auth_Google SGS_Auth_Facebook SGS_Auth_UApple SGS_Auth_Naver SGS_Auth_Line SGS_Auth_Steam SGS_Auth_GooglePlayGames | StoveProviders |
SGS_IAP SGS_IAP_Google | StoveIAP |
SGS_Push SGS_Push_Firebase | StovePush |
SGS_GamingServices | 제거 (대체 플러그인 없음) |
※ SGS_Log 의 게임 로그(GameLog)는 Stove 에 포함되지 않습니다. 게임 로그를 사용한다면 개발팀에 문의해 주십시오.
빌드가 실패하면
| 증상 | 원인 |
|---|---|
JsonReaderException: '{' is invalid after a value | .uproject 의 "Plugins" 배열에서 쉼표가 빠진 경우입니다(Step.2 Tip 1). |
Unable to find plugin '...' | .uproject 에 등록한 플러그인 폴더가 Plugins/ 에 없는 경우입니다(Step.1). |
Could not find definition for module '...' | .Build.cs 에 Step.1 에서 복사하지 않은 플러그인 이름이 있는 경우입니다(Step.3). |
| 중복 심볼 링커 에러 (iOS) | 기존 SGS_* 플러그인 폴더가 프로젝트에 남아 있는 경우입니다. 폴더째 삭제하십시오(Step.1). |
no member named 'OnOpenURLwithOptions' (iOS) | 엔진에서 8) 패치를 제거했지만 게임 코드에 바인딩이 남은 경우입니다(Step.5 ③). |
| Gradle 의존성 해석 실패 (Android) | 좌표 이름 또는 버전이 3.0.0 표기와 다른 경우입니다. Step.4 의 좌표 표와 비교하십시오. |
| 외부 로그인 후 앱으로 돌아와도 로그인이 완료되지 않음 (iOS) | 엔진에 8) 패치가 남아 있는 경우입니다(Step.5 ①). |
| iOS 13 · 14 기기에서 앱이 실행되지 않음 | MinimumiOSVersion 이 IOS_15 미만인 경우입니다(02. 사전 조건). |
- 개발자센터 이용/스마일게이트 퍼블리싱 게임 관련: stove.developers@smilegate.com
- 스토브 스토어 입점/스토브 스튜디오 관련: store.support@smilegate.com