- Cập nhật lần cuối
Mobile SDK 3.0.0 Migration Guide - Unreal
01. Overview
This guide explains how to upgrade the Mobile SDK in your Unreal project from 2.9.x to 3.0.0.
Target Audience: Games integrated with the Mobile SDK using Unreal
Scope: Mobile SDK 2.9.x → 3.0.0 / iOS · Android
In 3.0.0, 16 SDK plugins have been consolidated into 4, resulting in changes to plugin names, module names, and Android Gradle coordinates.
Replacing the plugin folder + modifying 3 build configuration files is the standard procedure, and for iOS, cleaning up the engine's URL receiving path is also required.
⚠️ This guide assumes that 2.9.x is already integrated.
If this is a new integration, you can start directly with 3.0.0, so this document is not needed.
| # | Target | What to do | Platform |
|---|---|---|---|
| 1 | <Project>/Plugins/ | Existing SGS_* folder deletion → Copy new plugins | Common |
| 2 | <Project>.uproject | Delete existing SGS_* entries → Register new plugins | Common |
| 3 | Game module .Build.cs | Dependency modules 16 → 4 | Common |
| 4 | <Project>_APL.xml | Gradle coordinates 17 lines → 4 lines | Android |
| 5 | Engine source · Game code URL receiving path | OnOpenURLwithOptions → OnOpenURL | iOS |
02. Prerequisites
- SDK Distribution: Download the Mobile SDK 3.0.0 or higher Unreal plugin
- Existing Integration: Mobile SDK 2.9.x is integrated and building successfully
- Build Environment: Environment capable of performing both iOS packaging and Android builds
- iOS Minimum Supported Version: 15.0 or higher —
Config/DefaultEngine.iniofMinimumiOSVersionisIOS_15or higher - Engine Source Modification Permission (iOS): Environment where you can modify and rebuild the custom engine applied during 2.9.x integration — Required in Step 5
⚠️ The 3.0.0 iOS framework supports iOS 15.0 or higher.
MinimumiOSVersionisIOS_13·IOS_14, packaging will succeed, but the app will not run on iOS 13 · 14 devices.
03. Procedure
Step.1 Replace Plugin Folder
Replace the project's SDK plugins with 3.0.0 or higher plugins.
- Delete all folders starting with
<Project>/Plugins/inSGS_. - Copy the downloaded plugin folders to
<Project>/Plugins/. Select them according to the features you use.
| Plugin | Necessity |
|---|---|
Stove | Always required — All other plugins depend on it |
StoveProviders | If using external login (Google · Facebook · Apple · Naver · Line · Steam · GPG) |
StoveIAP | If using payments |
StovePush | If using push notifications |
- If you have ever built the same project with 2.9.x, delete
<Project>/Binaries/and<Project>/Intermediate/.
⚠️ If the existing
SGS_*folder remains, a duplicate symbol linker error will occur on iOS. Do not overwrite; delete it before copying.
⚠️ If 2.9.x build artifacts remain, the 2.9.x resource bundle (
SGS*Resources.bundle) will be included in the iOS package. The build will succeed, so do not skip step 3.
Verification: Under
Plugins/, there are no folders starting withSGS_, and the plugin folders selected in the table above are present.
Step.2 Clean up plugin list in .uproject
<Project>.uproject Open and if there are any items starting with "Plugins" in the SGS_ array, delete them all.
/******************** 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 }
/***********************************************/
Register the plugins copied in Step 1 in their place.
/********************* add **********************/
{ "Name": "Stove", "Enabled": true },
{ "Name": "StoveProviders", "Enabled": true },
{ "Name": "StoveIAP", "Enabled": true },
{ "Name": "StovePush", "Enabled": true }
/***********************************************/
Exception Handling
- If there is no
"Plugins"item in theSGS_array: There is nothing to delete. Since plugins in the projectPlugins/folder are enabled by default even if not registered, you can also skip registering new items.
💡 Tip 1: Do not add a comma after the last item in the array, but always add one after other items. If a comma is missing,
JsonReaderException: '{' is invalid after a valuewill be displayed when starting the build.
💡 Tip 2: Do not leave
"Enabled": false. Since that plugin folder does not exist in 3.0.0, the list will remain unnecessarily.
Verification: There are no
SGS_strings left in the file.
Step.3 Replace dependency modules in game module .Build.cs
Change the SDK module names referenced by the game module to the new plugin names.
Source/<Project>/<Project>.Build.cs Check the PublicDependencyModuleNames of ```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` .
Clear the ```csharp
PublicDependencyModuleNames.AddRange(new string[] {
"Core", "CoreUObject", "Engine", "InputCore",
/********************* add **********************/
"Stove", "StoveProviders", "StoveIAP", "StovePush"
/***********************************************/
});
section and insert the plugin name selected in Step 1.
"Core"
- Leave engine modules like
PublicAdditionalFrameworksas they are. - Do not modify
Could not find definition for module. iOS framework linking is handled by the SDK plugin.
⚠️ Do not include plugins that were not copied in Step 1.
If there is a non-existent module name, it will stop withSGS_at the build start stage.
Verification: There are no
<Project>_APL.xmlstrings left in the file.
Step.4 Replace Gradle coordinates in Source/<Project>/<Project>_APL.xml of buildGradleAdditions → dependencies in the block, com.stove: delete all lines starting with . The version of the lines to delete (2.9.0 · 2.9.1, etc.) may vary by project.
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'
/***********************************************/
}
In that place, insert the coordinates corresponding to the plugin selected in Step 1. Below is an example based on 3.0.0; write the version as the version of the downloaded plugin.
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'
/***********************************************/
}
| Plugin | Coordinates |
|---|---|
Stove | com.stove:stove |
StoveProviders | com.stove:stove-providers |
StoveIAP | com.stove:stove-iap-google |
StovePush | com.stove:stove-push-firebase |
Exception Handling
- If you are not building for Android: Skip this step.
- If the game manages
_APL.xmlseparately: Even if the file location is different, you can change thedependenciescoordinates in thecom.stove:*block using the same rules.
⚠️ Leave the
com.google.android.gms:play-services-games-v2:19.0.0line as is.
It is a Google dependency required for game login (GPG), so if you delete it when deletingcom.stove:*, GPG login will fail.
💡 Tip: You do not need to write
com.stove:stove-iap·com.stove:stove-push.stove-iap-google·stove-push-firebasewill bring them in as dependencies.
Check: The coordinates starting with
com.stove:are equal to the number of plugins selected in Step 1, there are no2.9versions, and theplay-services-games-v2line remains.
Step.5 iOS URL Reception Path Cleanup (Engine · Game Code)
Clean up the engine and game code so that the 3.0.0 SDK can receive the URL that returns to the game after external login and authentication between the STOVE app.
2.9.x and 3.0.0 have different engine delegates for receiving URLs.
| 2.9.x | 3.0.0 | |
|---|---|---|
| Delegate used by SDK | FIOSCoreDelegates::OnOpenURLwithOptions | FIOSCoreDelegates::OnOpenURL |
| Engine requirements | 8) LSSupportsOpeningDocumentsInPlace 사용 patch | 8) No patch |
SceneDelegate Application Procedure
SceneDelegate is mandatory for all services submitted to the App Store starting April 2027, in accordance with Apple policy.
① Engine — 8) Remove patch
When integrating 2.9.x, follow the development environment settings 8) LSSupportsOpeningDocumentsInPlace 사용 to remove all code added to the engine's IOSAppDelegate.h · IOSAppDelegate.cpp — specifically OnOpenURLwithOptions · savedOpenUrlWithOptionsParameters · application:openURL:options: —.
② Engine — Apply SceneDelegate support update
Apply the iOS Unreal UISceneDelegate 대응 업데이트 in the development environment settings based on STOVE SDK 3.0.0 or higher. The procedure in this document configures the OnOpenURL delivery path.
③ Game Code — Replace OnOpenURLwithOptions binding
If there are any bindings to FIOSCoreDelegates::OnOpenURLwithOptions in your game code (e.g., deeplink handling), replace them with 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);
/***********************************************/
⚠️ If you leave the 8) patch, the build will succeed, but login will not complete after returning to the game from external login.
If theapplication:openURL:options:added by the 8) patch remains, iOS will not call theOnOpenURLpath, preventing the 3.0.0 SDK from receiving the URL. This will not be apparent during the build.
⚠️ If you apply ① but skip ③, compilation will fail. The engine with the patch removed does not contain
OnOpenURLwithOptions.
💡 Tip: SDK URL delivery is handled by the
Stoveplugin. You do not need to callSGSApplicationDelegatedirectly in your game code.
Verification: Searching for
OnOpenURLwithOptionsin the engine source and game code should yield no results.
If SceneDelegate cannot be applied immediately
The steps ① ~ ③ above are for applying SceneDelegate. If you cannot apply them immediately, please contact the development team before proceeding with ① ~ ③. We will guide you through the application method suitable for your project's situation.
Step.6 Build Verification
Build both iOS and Android to verify that the migration is complete.
The files modified in Step.1 ~ Step.3 are used by both iOS and Android. Since building only one platform may not reveal issues on the other, please be sure to build both platforms.
-
Plugins/'sSGS_folder and 2.9.x build outputs (Binaries/·Intermediate/) deleted - No
.uproject·.Build.csstrings inSGS_ -
_APL.xml'scom.stove:coordinates match the plugin selected in Step.1, no2.9version coordinates - (iOS) Set
MinimumiOSVersiontoIOS_15or higher - (iOS) No
OnOpenURLwithOptionsin engine source and game code - iOS packaging successful (no duplicate symbol linker errors)
- Android build successful
Step.7 Device Verification
⚠️ Do not stop at a successful build.
The iOS URL reception path (Step.5) and minimum supported version are not revealed in the build.
Perform the following items on both platforms:
- Login → Enter game
- Return to app after external login (Google · Apple · Naver, etc.) (iOS) — The only way to verify Step.5
- Payment (if using
StoveIAP) - Push notification reception (if using
StovePush)
Procedures for each item and points to suspect in case of failure are in the separate document Mobile SDK 3.0.0 실기기 스모크 체크리스트(Unreal) . It takes about 20 minutes per platform.
04. Reference
⚠️ Precautions
- Delete the existing
SGS_*plugin folder. If it remains, duplicate symbol linker errors will occur on iOS.- Do not delete the
play-services-games-v2line. If deleted, GPG login will fail.- For iOS, remove the 8) engine patch. If it remains, login will not complete even after returning to the app following external login.
💡 Things that do not need to be fixed
- Header
#include— File names likeAuth.h·User.h·GoogleProvider.hremain the same. However, module headers (SGS_Base.h·SGS_Auth.hetc.SGS_*.h) do not exist in 3.0.0, so delete them if you are including them.- SDK call code — The
stove::function signature is identical. Keep the login · integration · payment · push call parts as they are.- Java
import— Package name is maintained.AndroidManifestmeta-data key —com.stove.*The key name remains the same.- iOS Framework Settings — There is nothing to specify in the game project.
Plugin Mapping Table
| 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 | Removed (No replacement plugin) |
※ SGS_Log game logs (GameLog) are not included in Stove. If you use game logs, please contact the development team.
If the build fails
| Symptom | Cause |
|---|---|
JsonReaderException: '{' is invalid after a value | .uproject 's "Plugins" array is missing a comma (Step.2 Tip 1). |
Unable to find plugin '...' | .uproject The plugin folder registered in Plugins/ does not exist in Could not find definition for module '...' (Step.1). |
.Build.cs | SGS_* contains a plugin name that was not copied in Step.1 (Step.3). |
| Duplicate symbol linker error (iOS) | The existing no member named 'OnOpenURLwithOptions' plugin folder remains in the project. Please delete the entire folder (Step.1). |
MinimumiOSVersion (iOS) | The 8) patch was removed from the engine, but bindings remain in the game code (Step.5 ③). |
| Gradle dependency resolution failure (Android) | The coordinate name or version differs from the 3.0.0 notation. Please compare it with the coordinate table in Step.4. |
| Login does not complete after returning to the app from external login (iOS) | The 8) patch remains in the engine (Step.5 ①). |
| App does not run on iOS 13 · 14 devices | IOS_15 is less than |
- Developers Center Usage / Smilegate Publishing Games: stove.developers@smilegate.com
- STOVE Store Onboarding / STOVE Studio: store.support@smilegate.com