Skip to content
Stove
Last Updated

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.

#TargetWhatPlatform
1Assets/StoveDelete the entire folder → Import 3.0.0 package · Place entry pointsCommon
2PodfileRemove existing modules → Add new modulesiOS
3Assets/Plugins/Android/mainTemplate.gradleRemove existing modules → Add new modulesAndroid
4Custom AppController#import Replace · 3 ways to handle UISceneiOS · 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 UnityFramework target
  • 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 .gitignore is 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 MethodTask
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 StateTask
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.

kotlin
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 AndroidManifest of activity android:name points 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.

ruby
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.

ruby
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 into StoveProviders.

Check: pod install is successful, and Podfile in SGS There 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.

groovy
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.

groovy
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:gamingservices line: 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 the 2.9 coordinates.

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

objc
/******************** 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.

objc
/********************* 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: 추가

objc
/********************* 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 VersionAction
2022.3.72f1 or higher (including Unity 6)None. Unity provides the SceneDelegate — you do not need to read Appendix A
Below 2022.3.72f1Manually add the two SceneDelegate files and Info.plist settings — refer to Appendix A

Exception Handling

  • If you are using the StoveSDKAppController provided 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.mm from 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 · SGSPushNotificationCenter as they are. Only the framework (module) names have changed.

Verification: No SGS starting with #import remains 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/Stove and imported the 3.0.0 package
  • No pods starting with Podfile remain in SGS
  • The mainTemplate.gradle coordinates in com.stove: are 1:1 with the imported package and there are no 2.9 versions
  • iOS build successful — no linker errors after pod install
  • Android build successful
  • The AndroidManifest in activity android:name points 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.plist settings 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 iOS onOpenURL: · 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 — onCreate hook 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/Stove should 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-v2 line. If deleted, GPG login will fail.
  • Custom AppController will not be updated automatically. You must manually reflect all of Step.4 ①②③ — replacing #import is 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 remains Stove.StoveSDK.
  • Authentication · Payment · Push call code — Method signatures are identical.
  • Objective-C class names — SGSApplicationDelegate etc. 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.xTO-BE · 3.0.0
SGSBase SGSLog SGSAuth SGSAuthUI SGSView / base log auth auth-ui viewStove / stove
SGSAuthApple SGSAuthFacebook SGSAuthGoogle SGSAuthNaver SGSAuthLine SGSAuthSteam / auth-* 7 typesStoveProviders / stove-providers
SGSIAP2 / iap iap-google iap-huawei iap-onestoreStoveIAP2 / stove-iap stove-iap-google stove-iap-huawei stove-iap-onestore
SGSPush / push-firebase push-huaweiStovePush / stove-push-firebase stove-push-huawei
SGSGamingServices / gamingservicesRemoved (no replacement)

If the build fails

SymptomCause
Unity compilation error — reference to non-existent typeThis 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 CS2001This 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 foundThis happens if the pod corresponding to the imported package is missing (Step 2).
Android compilation error — class not foundThis 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).

  1. Add the two files to the generated Xcode project — .mm must be added to the UnityFramework target's Compile Sources (not the app target).
  2. Add the scene manifest to Info.plist.
  3. 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

objc
#import <UIKit/UIKit.h>

@interface StoveUnitySceneDelegate : UIResponder <UIWindowSceneDelegate>

@property (strong, nonatomic) UIWindow *window;

@end

StoveUnitySceneDelegate.mm

objc
#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

xml
<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.mm This UnityFramework is in the target's Compile Sources, the screen displays correctly upon execution, and external login return works.



Do you have any inquiries?