- Cập nhật lần cuối
Mobile SDK 3.0.0 Migration Guide — Unity
01. Overview
This guide explains how to upgrade the Mobile SDK in your Unity project from 2.9.x to 3.0.0.
Target Audience: Games that have integrated the Mobile SDK using Unity
Scope: Mobile SDK 2.9.x → 3.0.0 / iOS · Android
As the SDK modules are integrated in 3.0.0, the iOS pod name and Android Gradle coordinates have changed.
Replacing the SDK package + modifying 2 build configuration files is the standard procedure, and game code requires custom AppController modifications.
⚠️ This guide assumes that 2.9.x is already integrated.
| # | Target | What | Platform |
|---|---|---|---|
| 1 | Assets/Stove | Delete the entire folder → Import 3.0.0 package · Place entry points | Common |
| 2 | Podfile | Remove existing modules → Add new modules | iOS |
| 3 | Assets/Plugins/Android/mainTemplate.gradle | Remove existing modules → Add new modules | Android |
| 4 | Custom AppController | #import Replace · 3 ways to handle UIScene | iOS · Only if customized |
02. Prerequisites
- SDK Distribution: Receive the Mobile SDK 3.0.0 Unity delivery zip
- Build Environment: Environment capable of performing both iOS builds (CocoaPods) and Android builds
- iOS Deployment Target: 15.0 or higher — both for the app target and
UnityFrameworktarget - Unity Version: If lower than 2022.3.72f1, apply Appendix A together in Step 4
- Check: Whether there is a custom class inheriting from
UnityAppController(If so, Step 4 is required) - Check: Whether there is a custom Activity inheriting from
UnityPlayerActivity(If so, check the entry point placement in Step 1)
03. Procedure
Step.1 Assets/Stove Package Replacement
Replace the SDK files in your project with the 3.0.0 distribution.
Delete the existing Assets/Stove folder entirely before importing the 3.0.0 package.
⚠️ Overwriting will cause compilation errors due to residual 2.9.x files.
You must delete it before importing.
💡 Tip 1: If your game has custom files placed under
Assets/Stove, move them to a different path before deleting.
💡 Tip 2: Check if
.gitignoreis ignoring*.meta. Since hundreds of assets are being replaced, if they are excluded, the GUIDs will differ between machines.
SDK packages are provided in two ways: by module and full package including samples.
| Delivery Method | Task |
|---|---|
| A. Per-module package Select and receive only the packages for the features you need | ① Import the received packages (Stove first). ② Manually place the Android entry point — see the table below. ③ No action is required for the iOS entry point at this stage — it will be handled in Step 4. |
| B. Full package including samples Receive all features and samples in one | ① In the import window, uncheck Assets/Stove/Sample · Assets/Stove/SSTools. ② If using a custom AppController, also uncheck Assets/Stove/Plugins/iOS/StoveSDKAppController.mm. ③ Both entry points are already included under Assets/Stove/Plugins/ — no separate placement is required. |
Android Entry Point Placement (Required if received via A. Per-module package)
| Game State | Task |
|---|---|
Inheriting and extending UnityPlayerActivity | ① Add the 3 hooks below to that Activity. ② Write your class name in the AndroidManifest of activity android:name. |
| Not inheriting | ① Place the EntryPoints/Android/StoveUnityPlayerActivity.kt from the delivery zip into .meta along with Assets/Stove/Plugins/Android/. ② Set activity android:name to com.stove.unity.StoveUnityPlayerActivity. |
com.stove.push.Push · com.stove.view.ViewUI are imported.
class CustomActivity : UnityPlayerActivity() {
override fun onCreate(bundle: Bundle?) {
super.onCreate(bundle)
Push.handleIntent(applicationContext, intent)
}
override fun onNewIntent(newIntent: Intent?) {
super.onNewIntent(newIntent)
Push.handleIntent(applicationContext, newIntent)
}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == 7585) ViewUI.handleIntent(requestCode, resultCode, data)
}
}
⚠️ The build will succeed even if you miss the entry point.
Android will fail to find the activity class immediately upon execution, and iOS will not correctly handle deep links, external login returns, or push callbacks. Verify on a real device in Step 6.
Check
- There are no compilation errors in the Unity console. (Native dependencies are resolved in Step 2 · Step 3.)
- The
AndroidManifestofactivity android:namepoints to an existing Activity class.
Step.2 Replace Podfile pod
Replace the SDK pod referenced by the iOS build with the 4 new ones.
Podfile Remove the existing v2 modules from the UnityFramework target.
target 'UnityFramework' do
/******************** remove ********************/
pod 'SGSBase', '2.9.0'
pod 'SGSLog', '2.9.0'
pod 'SGSAuth', '2.9.0'
pod 'SGSIAP2', '2.9.0'
pod 'SGSAuthApple', '2.9.0'
pod 'SGSAuthFacebook', '2.9.0'
pod 'SGSAuthGoogle', '2.9.0'
pod 'SGSAuthNaver', '2.9.0'
pod 'SGSAuthLine', '2.9.0'
pod 'SGSAuthSteam', '2.9.0'
pod 'SGSAuthUI', '2.9.0'
pod 'SGSPush', '2.9.0'
pod 'SGSView', '2.9.0'
/***********************************************/
end
Insert the following 4 lines in their place.
target 'UnityFramework' do
/********************* add **********************/
pod 'Stove', '3.0.0'
pod 'StoveProviders', '3.0.0'
pod 'StoveIAP2', '3.0.0'
pod 'StovePush', '3.0.0'
/***********************************************/
end
After modification, run pod install again.
Exception Handling
- If the
pod 'SGSGamingServices'line exists: Remove it and do not add it again. The GPG User ID feature has been absorbed intoStoveProviders.
Check:
pod installis successful, andPodfileinSGSThere are no pods left starting with .
Step.3 mainTemplate.gradle Replace Gradle coordinates
Change the SDK dependency coordinates injected into the Android build.
Assets/Plugins/Android/mainTemplate.gradle 's dependencies In the block, check the com.stove: coordinates.
dependencies {
/******************** remove ********************/
implementation 'com.stove:base:2.9.0'
implementation 'com.stove:log:2.9.0'
implementation 'com.stove:auth:2.9.1'
implementation 'com.stove:auth-facebook:2.9.0'
implementation 'com.stove:auth-google:2.9.0'
implementation 'com.stove:auth-googleplaygames:2.9.0'
implementation 'com.stove:auth-naver:2.9.0'
implementation 'com.stove:auth-apple:2.9.0'
implementation 'com.stove:auth-line:2.9.0'
implementation 'com.stove:auth-steam:2.9.0'
implementation 'com.stove:auth-ui:2.9.1'
implementation 'com.stove:view:2.9.0'
implementation 'com.stove:push-firebase:2.9.0'
implementation 'com.stove:iap-google:2.9.0'
/***********************************************/
}
remove Delete the section and replace it with the add section.
dependencies {
/********************* add **********************/
implementation 'com.stove:stove:3.0.0'
implementation 'com.stove:stove-providers:3.0.0'
implementation 'com.stove:stove-push:3.0.0'
implementation 'com.stove:stove-push-firebase:3.0.0'
implementation 'com.stove:stove-iap:3.0.0'
implementation 'com.stove:stove-iap-google:3.0.0'
/***********************************************/
}
Exception Handling
- If building for Huawei/One Store markets: Include the corresponding market coordinates as well
com.stove:stove-iap-huawei·com.stove:stove-iap-onestore·com.stove:stove-push-huawei. - If there is a
com.stove:gamingservicesline: Remove it.
💡
com.stove:All coordinates starting with are subject to removal, even those not in the list above.
The example above is based on Google Market/Firebase Push, so the number of lines may vary depending on the market/login configuration used by the project.
Check: There are no
com.stove:versions in the2.9coordinates.
Step.4 Modify custom AppController
If the game has its own AppController that inherits from UnityAppController, apply all of ①②③ below to that file.
Since this file is owned by the game, it is not updated by the Step.1 package replacement.
① #import Replace path
/******************** remove ********************/
#import <SGSPush/SGSPush.h>
#import <SGSAuth/SGSAuth.h>
/***********************************************/
/********************* add **********************/
#import "AppDelegateListener.h"
#import <StovePush/StovePush.h>
#import <Stove/Stove.h>
/***********************************************/
② AppDelegateListener Adoption and onOpenURL: addition — In a UIScene environment, application:openURL:options: is not passed to the app delegate, so without this path, external login callbacks (Google/Apple) will not work.
/********************* add **********************/
@interface MyAppController : UnityAppController <SGSPushNotificationCenterDelegate, AppDelegateListener>
@end
- (instancetype)init
{
self = [super init];
if (self != nil) { UnityRegisterAppDelegateListener(self); }
return self;
}
- (void)onOpenURL:(NSNotification *)notification
{
NSURL *url = notification.userInfo[@"url"];
if (![url isKindOfClass:NSURL.class]) { return; }
NSMutableDictionary<UIApplicationOpenURLOptionsKey, id> *options = [NSMutableDictionary dictionary];
// sourceApplication / annotation 을 userInfo 에서 옮겨 담고
options[UIApplicationOpenURLOptionsOpenInPlaceKey] = @NO;
// Since this is a UI path, please call it from the main thread.
[SGSApplicationDelegate application:UIApplication.sharedApplication openURL:url options:options];
}
/***********************************************/
기존 application:openURL:options: 오버라이드는 지우지 말고 그대로 둡니다. 두 경로가 함께 있어야 UIScene 환경과 그 이전 환경 모두에서 동작합니다.
③ configurationForConnectingSceneSession: 추가
/********************* add **********************/
- (UISceneConfiguration *)application:(UIApplication *)application
configurationForConnectingSceneSession:(UISceneSession *)session
options:(UISceneConnectionOptions *)options
{
return [UISceneConfiguration configurationWithName:@"Default Configuration"
sessionRole:session.role];
}
/***********************************************/
④ SceneDelegate — Judge based solely on the Unity version. It is independent of whether a custom AppController exists.
| Unity Version | Action |
|---|---|
| 2022.3.72f1 or higher (including Unity 6) | None. Unity provides the SceneDelegate — you do not need to read Appendix A |
| Below 2022.3.72f1 | Manually add the two SceneDelegate files and Info.plist settings — refer to Appendix A |
Exception Handling
- If you are using the
StoveSDKAppControllerprovided by the SDK as-is: Skip ①②③. The files in B. Full package including samples are already the 3.0.0 updated versions. Do verify ④.
⚠️ Reflecting only ① will allow compilation but it will not function correctly.
If ② is missing, the app will not return after external login; if ③ and ④ are missing, the screen will remain black immediately after launch. Neither of these issues will be apparent during the build process.
⚠️ If you carry over the
StoveSDKAppController.mmfrom 2.9.x as-is, compilation will fail. This is because it references removed pods (SGSPush·SGSAuth).
⚠️ Every time Unity regenerates the Xcode project, the settings for ④ will disappear. If you use a post-build script, include them in that script.
💡 Tip: Objective-C class names have not changed. Continue using
SGSApplicationDelegate·SGSPushNotificationCenteras they are. Only the framework (module) names have changed.
Verification: No
SGSstarting with#importremains in the file, external login on a physical device returns to the app normally, and the screen does not remain black immediately after launch.
Step.5 Build Verification
Build both platforms to confirm that the migration is complete.
- Deleted the existing
Assets/Stoveand imported the 3.0.0 package - No pods starting with
Podfileremain inSGS - The
mainTemplate.gradlecoordinates incom.stove:are 1:1 with the imported package and there are no2.9versions - iOS build successful — no linker errors after
pod install - Android build successful
- The
AndroidManifestinactivity android:namepoints to an existing Activity, and that Activity contains the 3 hooks - If using a custom
AppController, all of Step.4 ①②③ are included (iOS) - If Unity is below 2022.3.72f1, the SceneDelegate and
Info.plistsettings from Appendix A are included (iOS)
Step.6 Physical Device Verification
⚠️ Do not stop at a successful build.
The problems most easily missed in this migration are not compilation errors, but cases where the build succeeds but it does not function correctly at runtime without errors. The 3 entry point hooks, the iOSonOpenURL:·configurationForConnectingSceneSession:, and the existence of the classes pointed to by the manifest are not revealed during the build.
Perform at least the following 3 checks. They cannot be replaced by any other tests.
- Attach file from overlay screen — the only path to verify
ViewUI.handleIntent/7585 - Return to app after external login (iOS) — the only path to verify Step.4 ②
- Tap push notification while the app is completely closed —
onCreatehook path. This cannot be replaced by testing while the app is running
Procedures for each item and points to suspect in case of failure are in the separate document Mobile SDK 3.0.0 Physical Device Smoke Checklist (Unity). It takes 20–30 minutes per platform.
04. Reference
⚠️ Precautions
Assets/Stoveshould not be overwritten; delete it and then import. 2.9.x residual files will cause compilation errors.
- Always match the package, pod, and coordinates together. In 3.0.0, the native bridge is inside its own functional package, so if you remove unused features at the package level, you don't need the pods or coordinates. Conversely, if you import it but omit the pod or coordinates, the build will fail.
- Do not delete the
play-services-games-v2line. If deleted, GPG login will fail.
- Custom
AppControllerwill not be updated automatically. You must manually reflect all of Step.4 ①②③ — replacing#importis not enough.
- Do not delete the 2 entry points of
Assets/Stove/Plugins/. Unless you are replacing them with your own implementation, Android's manifest points to this class, so the app will not start if it is missing.
💡 Things that do not need to be fixed
- C#
using— The namespace remainsStove.StoveSDK.- Authentication · Payment · Push call code — Method signatures are identical.
- Objective-C class names —
SGSApplicationDelegateetc. remain the same. Only the framework name changes.StoveUnityPlayerActivity.kt— Content is the same as 2.9.x.- Kotlin package names —
com.stove.unity.*·com.stove.push.*remain the same.
Module Correspondence Table (iOS pod / Android coordinates)
| AS-IS · 2.9.x | TO-BE · 3.0.0 |
|---|---|
SGSBase SGSLog SGSAuth SGSAuthUI SGSView / base log auth auth-ui view | Stove / stove |
SGSAuthApple SGSAuthFacebook SGSAuthGoogle SGSAuthNaver SGSAuthLine SGSAuthSteam / auth-* 7 types | StoveProviders / stove-providers |
SGSIAP2 / iap iap-google iap-huawei iap-onestore | StoveIAP2 / stove-iap stove-iap-google stove-iap-huawei stove-iap-onestore |
SGSPush / push-firebase push-huawei | StovePush / stove-push-firebase stove-push-huawei |
SGSGamingServices / gamingservices | Removed (no replacement) |
If the build fails
| Symptom | Cause |
|---|---|
| Unity compilation error — reference to non-existent type | This happens if you only overwrote Assets/Stove in Step 1. Please delete the folder entirely and re-import it. |
Unity compilation error — pointing to 2.9.x path with error CS2001 | This happens if the editor has cached an old file list. Close the editor, delete the Library folder, and reopen it. |
| iOS linker error — symbol not found | This happens if the pod corresponding to the imported package is missing (Step 2). |
| Android compilation error — class not found | This happens if the coordinates corresponding to the imported package are missing (Step 3). |
| Gradle dependency resolution failure (Android) | Please check the version notation. |
| App does not start immediately upon execution (Android) | This happens if activity android:name points to a non-existent class (Step 1). |
| App does not return after external login (iOS) | This happens if onOpenURL: is missing in the custom AppController (Step 4 ②). |
| Black screen immediately after execution (iOS) | This happens if the SceneDelegate setting is missing in Unity versions below 2022.3.72f1 (Step 4 ④ · Appendix A). If you are using 2022.3.72f1 or higher, this is not the cause. |
Appendix A. StoveUnitySceneDelegate — Below Unity 2022.3.72f1
Since Unity versions below 2022.3.72f1 do not provide SceneDelegate, the two files below and Info.plist settings are required. If missing, it will result in a black screen immediately after execution.
Skip this appendix if you are using 2022.3.72f1 or higher (including Unity 6).
- Add the two files to the generated Xcode project —
.mmmust be added to theUnityFrameworktarget's Compile Sources (not the app target). - Add the scene manifest to
Info.plist. - If you use a post-build script, include steps 1 and 2 in that script — because they disappear every time Unity regenerates the Xcode project.
StoveUnitySceneDelegate.h
#import <UIKit/UIKit.h>
@interface StoveUnitySceneDelegate : UIResponder <UIWindowSceneDelegate>
@property (strong, nonatomic) UIWindow *window;
@end
StoveUnitySceneDelegate.mm
#import "StoveUnitySceneDelegate.h"
#import "UnityAppController.h"
#import "AppDelegateListener.h"
#include "Unity/UnityInterface.h"
@implementation StoveUnitySceneDelegate
{
UIOpenURLContext *_pendingURLContext;
}
- (void)scene:(UIScene *)scene
willConnectToSession:(UISceneSession *)session
options:(UISceneConnectionOptions *)connectionOptions
{
if ([scene isKindOfClass:UIWindowScene.class])
{
self.window = GetAppController().window;
if (self.window != nil)
{
self.window.windowScene = (UIWindowScene *)scene;
[self.window makeKeyAndVisible];
}
}
_pendingURLContext =
[self firstValidContextFromContexts:connectionOptions.URLContexts];
if (_pendingURLContext != nil)
{
UnitySetAbsoluteURL(
_pendingURLContext.URL.absoluteString.UTF8String);
}
}
- (void)sceneWillEnterForeground:(UIScene *)scene
{
if (_pendingURLContext != nil)
{
[self
applyURL:_pendingURLContext.URL
sourceApplication:_pendingURLContext.options.sourceApplication
annotation:_pendingURLContext.options.annotation];
_pendingURLContext = nil;
}
[GetAppController()
applicationWillEnterForeground:UIApplication.sharedApplication];
}
- (void)sceneDidBecomeActive:(UIScene *)scene
{
[GetAppController()
applicationDidBecomeActive:UIApplication.sharedApplication];
}
- (void)sceneWillResignActive:(UIScene *)scene
{
[GetAppController()
applicationWillResignActive:UIApplication.sharedApplication];
}
- (void)sceneDidEnterBackground:(UIScene *)scene
{
[GetAppController()
applicationDidEnterBackground:UIApplication.sharedApplication];
}
- (void)scene:(UIScene *)scene
openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
{
UIOpenURLContext *context =
[self firstValidContextFromContexts:URLContexts];
if (context != nil)
{
[self
applyURL:context.URL
sourceApplication:context.options.sourceApplication
annotation:context.options.annotation];
}
}
- (UIOpenURLContext *)firstValidContextFromContexts:
(NSSet<UIOpenURLContext *> *)contexts
{
for (UIOpenURLContext *context in contexts)
{
if (context.URL != nil &&
context.URL.absoluteString != nil)
{
return context;
}
}
return nil;
}
- (void)applyURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation
{
if (url == nil || url.absoluteString == nil)
{
return;
}
UnitySetAbsoluteURL(url.absoluteString.UTF8String);
NSMutableDictionary<NSString *, id> *notificationData =
[NSMutableDictionary dictionaryWithCapacity:3];
notificationData[@"url"] = url;
if (sourceApplication != nil)
{
notificationData[@"sourceApplication"] = sourceApplication;
}
if (annotation != nil)
{
notificationData[@"annotation"] = annotation;
}
AppController_SendNotificationWithArg(
kUnityOnOpenURL,
notificationData);
}
@end
Info.plist
<key>UIApplicationSceneManifest</key>
<dict>
<key>UIApplicationSupportsMultipleScenes</key>
<false/>
<key>UISceneConfigurations</key>
<dict>
<key>UIWindowSceneSessionRoleApplication</key>
<array>
<dict>
<key>UISceneConfigurationName</key>
<string>Default Configuration</string>
<key>UISceneDelegateClassName</key>
<string>StoveUnitySceneDelegate</string>
</dict>
</array>
</dict>
</dict>
Check:
StoveUnitySceneDelegate.mmThisUnityFrameworkis in the target's Compile Sources, the screen displays correctly upon execution, and external login return works.
- Developers Center Usage / Smilegate Publishing Games: stove.developers@smilegate.com
- STOVE Store Onboarding / STOVE Studio: store.support@smilegate.com