Skip to content
Stove
Last Updated

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.

#TargetWhat to doPlatform
1<Project>/Plugins/Existing SGS_* folder deletion → Copy new pluginsCommon
2<Project>.uprojectDelete existing SGS_* entries → Register new pluginsCommon
3Game module .Build.csDependency modules 16 → 4Common
4<Project>_APL.xmlGradle coordinates 17 lines → 4 linesAndroid
5Engine source · Game code URL receiving pathOnOpenURLwithOptions → OnOpenURLiOS

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.ini of MinimumiOSVersion is IOS_15 or 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.
MinimumiOSVersion is IOS_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.

  1. Delete all folders starting with <Project>/Plugins/ in SGS_ .
  2. Copy the downloaded plugin folders to <Project>/Plugins/ . Select them according to the features you use.
PluginNecessity
StoveAlways required — All other plugins depend on it
StoveProvidersIf using external login (Google · Facebook · Apple · Naver · Line · Steam · GPG)
StoveIAPIf using payments
StovePushIf using push notifications
  1. 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 with SGS_ , 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.

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 }
/***********************************************/

Register the plugins copied in Step 1 in their place.

json
/********************* 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 the SGS_ array: There is nothing to delete. Since plugins in the project Plugins/ 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 value will 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"
/
***************************/
});

text

`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 PublicAdditionalFrameworks as 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 with SGS_ at the build start stage.

Verification: There are no <Project>_APL.xml strings 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.

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'
    /***********************************************/
}

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.

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'
    /***********************************************/
}
PluginCoordinates
Stovecom.stove:stove
StoveProviderscom.stove:stove-providers
StoveIAPcom.stove:stove-iap-google
StovePushcom.stove:stove-push-firebase

Exception Handling

  • If you are not building for Android: Skip this step.
  • If the game manages _APL.xml separately: Even if the file location is different, you can change the dependencies coordinates in the com.stove:* block using the same rules.

⚠️ Leave the com.google.android.gms:play-services-games-v2:19.0.0 line as is.
It is a Google dependency required for game login (GPG), so if you delete it when deleting com.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-firebase will 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 no 2.9 versions, and the play-services-games-v2 line 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.x3.0.0
Delegate used by SDKFIOSCoreDelegates::OnOpenURLwithOptionsFIOSCoreDelegates::OnOpenURL
Engine requirements8) LSSupportsOpeningDocumentsInPlace 사용 patch8) 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.

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);
/***********************************************/

⚠️ If you leave the 8) patch, the build will succeed, but login will not complete after returning to the game from external login.
If the application:openURL:options: added by the 8) patch remains, iOS will not call the OnOpenURL path, 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 Stove plugin. You do not need to call SGSApplicationDelegate directly in your game code.

Verification: Searching for OnOpenURLwithOptions in 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/ 's SGS_ folder and 2.9.x build outputs (Binaries/ · Intermediate/) deleted
  • No .uproject · .Build.cs strings in SGS_
  • _APL.xml 's com.stove: coordinates match the plugin selected in Step.1, no 2.9 version coordinates
  • (iOS) Set MinimumiOSVersion to IOS_15 or higher
  • (iOS) No OnOpenURLwithOptions in 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-v2 line. 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 like Auth.h · User.h · GoogleProvider.h remain the same. However, module headers (SGS_Base.h · SGS_Auth.h etc. 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.
  • AndroidManifest meta-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.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_GamingServicesRemoved (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

SymptomCause
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.csSGS_* 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 devicesIOS_15 is less than



Do you have any inquiries?