Skip to content
스토브
마지막 업데이트

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.xmlGradle 좌표 17줄 → 4줄Android
5엔진 소스 · 게임 코드의 URL 수신 경로OnOpenURLwithOptions → OnOpenURLiOS

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 이상 플러그인으로 교체합니다.

  1. <Project>/Plugins/ 에서 SGS_ 로 시작하는 폴더를 모두 삭제합니다.
  2. 다운로드한 플러그인 폴더를 <Project>/Plugins/ 에 복사합니다. 사용하는 기능에 맞춰 고릅니다.
플러그인필요 여부
Stove항상 필요 — 나머지 플러그인이 모두 의존합니다
StoveProviders외부 로그인(Google · Facebook · Apple · Naver · Line · Steam · GPG)을 사용하는 경우
StoveIAP결제를 사용하는 경우
StovePush푸시를 사용하는 경우
  1. 같은 프로젝트를 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_ 로 시작하는 항목이 있으면 모두 삭제합니다.

json
/******************** 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 에서 복사한 플러그인을 등록합니다.

json
/********************* 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 를 확인합니다.

csharp
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 에서 고른 플러그인 이름을 넣습니다.

csharp
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 등)은 프로젝트마다 다를 수 있습니다.

groovy
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 기준 예시이며, 버전은 다운로드한 플러그인의 버전으로 적습니다.

groovy
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'
    /***********************************************/
}
플러그인좌표
Stovecom.stove:stove
StoveProviderscom.stove:stove-providers
StoveIAPcom.stove:stove-iap-google
StovePushcom.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.x3.0.0
SDK 가 사용하는 delegateFIOSCoreDelegates::OnOpenURLwithOptionsFIOSCoreDelegates::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 로 바꿉니다.

cpp
/******************** 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 — 패키지 이름이 유지됩니다.
  • AndroidManifest meta-data 키 — com.stove.* 키 이름이 그대로입니다.
  • iOS 프레임워크 설정 — 게임 프로젝트에서 지정할 것이 없습니다.

플러그인 대응표

AS-IS · 2.9.xTO-BE · 3.0.0
SGS_Base SGS_Log SGS_Auth SGS_AuthUI SGS_ViewStove ※
SGS_Auth_Google SGS_Auth_Facebook SGS_Auth_UApple SGS_Auth_Naver SGS_Auth_Line SGS_Auth_Steam SGS_Auth_GooglePlayGamesStoveProviders
SGS_IAP SGS_IAP_GoogleStoveIAP
SGS_Push SGS_Push_FirebaseStovePush
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. 사전 조건).



문의가 필요하신가요?