- 마지막 업데이트
Mobile SDK 3.0.0 마이그레이션 가이드 — Unity
01. 개요
이 가이드는 Unity 프로젝트의 Mobile SDK 를 2.9.x 에서 3.0.0 으로 올리는 방법을 설명합니다.
적용 대상: Unity 로 Mobile SDK 를 연동한 게임
적용 범위: Mobile SDK 2.9.x → 3.0.0 / iOS · Android
3.0.0 에서 SDK 모듈이 통합되면서, iOS pod 이름과 Android Gradle 좌표가 변경되었습니다.
SDK 패키지 교체 + 빌드 구성 파일 2개 수정이 기본이고, 게임 코드는 커스텀 AppController 수정이 필요합니다.
⚠️ 이 가이드는 2.9.x 가 이미 연동된 상태를 가정합니다.
| # | 대상 | 무엇을 | 플랫폼 |
|---|---|---|---|
| 1 | Assets/Stove | 폴더째 삭제 → 3.0.0 패키지 임포트 · 진입점 배치 | 공통 |
| 2 | Podfile | 기존 모듈 제거 → 신규 모듈 추가 | iOS |
| 3 | Assets/Plugins/Android/mainTemplate.gradle | 기존 모듈 제거 → 신규 모듈 추가 | Android |
| 4 | 커스텀 AppController | #import 교체 · UIScene 대응 3가지 | iOS · 커스텀한 경우만 |
02. 사전 조건
- SDK 배포본: Mobile SDK 3.0.0 Unity 전달 zip 수령
- 빌드 환경: iOS 빌드(CocoaPods)와 Android 빌드를 모두 수행할 수 있는 환경
- iOS 배포 타깃: 15.0 이상 — 앱 타깃과
UnityFramework타깃 모두 - Unity 버전: 2022.3.72f1 미만이면 Step.4에서 부록 A 를 함께 적용합니다
- 확인 사항:
UnityAppController를 상속한 자체 클래스가 있는지 (있으면 Step.4 필요) - 확인 사항:
UnityPlayerActivity를 상속한 자체 Activity 가 있는지 (있으면 Step.1 진입점 배치 확인)
03. 절차
Step.1 Assets/Stove 패키지 교체
프로젝트의 SDK 파일을 3.0.0 배포본으로 교체합니다.
기존 Assets/Stove 를 폴더째 삭제한 뒤 3.0.0 패키지를 임포트합니다.
⚠️ 덮어쓰기만 하면 2.9.x 잔여 파일이 컴파일 에러를 일으킵니다.
반드시 삭제 후 import 하십시오.
💡 Tip 1: 게임이 직접 만든 파일을
Assets/Stove아래에 두었다면, 삭제하기 전에 다른 경로로 옮기십시오.
💡 Tip 2:
.gitignore가*.meta를 무시하고 있지 않은지 확인하십시오. 자산 수백 개가 교체되므로, 제외되어 있으면 장비마다 GUID 가 달라집니다.
SDK 패키지는 모듈별 과 샘플 포함 전체 두 가지 방식으로 제공됩니다.
| 받는 방식 | 할 일 |
|---|---|
| A. 모듈별 패키지 필요한 기능의 패키지만 골라 받습니다 | ① 받은 패키지를 임포트합니다 (Stove 를 먼저).② Android 진입점을 직접 배치합니다 — 아래 표 참조. ③ iOS 진입점은 이 단계에서 할 일이 없습니다 — Step.4에서 처리합니다. |
| B. 샘플 포함 전체 패키지 모든 기능과 샘플을 하나로 받습니다 | ① 임포트 창에서 Assets/Stove/Sample · Assets/Stove/SSTools 를 체크 해제합니다.② 커스텀 AppController 를 쓴다면 Assets/Stove/Plugins/iOS/StoveSDKAppController.mm 도 체크 해제합니다.③ 진입점 2개는 Assets/Stove/Plugins/ 아래에 이미 포함되어 있습니다 — 별도 배치가 필요 없습니다. |
Android 진입점 배치 (A. 모듈별 패키지 로 받은 경우 필요)
| 게임의 상태 | 할 일 |
|---|---|
UnityPlayerActivity 를 상속해 확장 중 | ① 그 Activity 에 아래 훅 3개를 추가합니다. ② AndroidManifest 의 activity android:name 에 자기 클래스를 적습니다. |
| 상속해 쓰지 않음 | ① 전달 zip 의 EntryPoints/Android/StoveUnityPlayerActivity.kt 를 .meta 와 함께 Assets/Stove/Plugins/Android/ 에 둡니다.② activity android:name 을 com.stove.unity.StoveUnityPlayerActivity 로 지정합니다. |
com.stove.push.Push · com.stove.view.ViewUI 를 import 합니다.
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)
}
}
⚠️ 진입점을 빠뜨려도 빌드는 성공합니다.
Android 는 실행 즉시 액티비티 클래스를 찾지 못하고, iOS 는 딥링크 · 외부 로그인 복귀 · 푸시 콜백이 오류 없이 동작하지 않습니다. Step.6에서 실기기로 확인하십시오.
확인
- Unity 콘솔에 컴파일 에러가 없습니다. (네이티브 의존성은 Step.2 · Step.3에서 맞춥니다.)
AndroidManifest의activity android:name이 실재하는 Activity 클래스를 가리킵니다.
Step.2 Podfile 의 pod 교체
iOS 빌드가 참조하는 SDK pod 을 신규 4개로 바꿉니다.
Podfile 의 UnityFramework 타깃에서 기존 v2 모듈을 삭제합니다.
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
그 자리에 아래 4줄을 넣습니다.
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
수정 후 pod install 을 다시 실행합니다.
예외 처리
pod 'SGSGamingServices'줄이 있는 경우: 제거하고 새로 추가하지 않습니다. GPG User ID 기능은StoveProviders에 흡수됐습니다.
확인:
pod install이 성공하고,Podfile에SGS로 시작하는 pod 이 하나도 남아 있지 않습니다.
Step.3 mainTemplate.gradle 의 Gradle 좌표 교체
Android 빌드에 주입되는 SDK 의존성 좌표를 바꿉니다.
Assets/Plugins/Android/mainTemplate.gradle 의 dependencies 블록에서 com.stove: 좌표를 확인합니다.
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 구간을 지우고 add 구간으로 바꿉니다.
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'
/***********************************************/
}
예외 처리
- 화웨이 · 원스토어 마켓을 빌드하는 경우: 해당 마켓 좌표를 함께 적습니다
com.stove:stove-iap-huawei·com.stove:stove-iap-onestore·com.stove:stove-push-huawei. com.stove:gamingservices줄이 있는 경우: 제거합니다.
💡
com.stove:로 시작하는 좌표는 위 목록에 없는 것까지 모두 제거 대상입니다.
위 예시는 구글 마켓 · Firebase 푸시 기준이므로, 프로젝트가 쓰는 마켓 · 로그인 구성에 따라 줄 수가 다를 수 있습니다.
확인:
com.stove:좌표에2.9버전이 하나도 없습니다.
Step.4 커스텀 AppController 수정
게임이 UnityAppController 를 상속한 자체 AppController 를 두고 있다면, 그 파일에 아래 ①②③ 을 모두 반영합니다.
이 파일은 게임이 소유한 파일이라 Step.1 패키지 교체로 갱신되지 않습니다.
① #import 경로 교체
/******************** remove ********************/
#import <SGSPush/SGSPush.h>
#import <SGSAuth/SGSAuth.h>
/***********************************************/
/********************* add **********************/
#import "AppDelegateListener.h"
#import <StovePush/StovePush.h>
#import <Stove/Stove.h>
/***********************************************/
② AppDelegateListener 채택과 onOpenURL: 추가 — UIScene 환경에서는 application:openURL:options: 가 앱 델리게이트로 전달되지 않아, 이 경로가 없으면 외부 로그인 콜백(구글 · 애플)이 동작하지 않습니다.
/********************* 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;
// UI 경로이므로 메인 스레드에서 호출하십시오.
[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 — Unity 버전만 보고 판단합니다. 커스텀 AppController 유무와 무관합니다.
| Unity 버전 | 할 일 |
|---|---|
| 2022.3.72f1 이상 (Unity 6 포함) | 없음. Unity 가 SceneDelegate 를 제공합니다 — 부록 A 를 읽지 않아도 됩니다 |
| 2022.3.72f1 미만 | SceneDelegate 파일 2개와 Info.plist 설정을 직접 넣습니다 — 부록 A 참조 |
예외 처리
- SDK 가 제공하는
StoveSDKAppController를 그대로 쓰는 경우: ①②③ 은 건너뜁니다. B. 샘플 포함 전체 패키지 의 파일이 이미 3.0.0 갱신본입니다. ④ 는 확인합니다.
⚠️ ①만 반영하면 컴파일은 되지만 정상 동작하지 않습니다.
②가 빠지면 외부 로그인 후 앱으로 복귀하지 않고, ③ · ④가 빠지면 실행 직후 검은 화면이 됩니다. 둘 다 빌드에서는 드러나지 않습니다.
⚠️ 2.9.x 의
StoveSDKAppController.mm을 그대로 들고 오면 컴파일에 실패합니다. 없어진 pod(SGSPush·SGSAuth)을 참조하기 때문입니다.
⚠️ Unity 가 Xcode 프로젝트를 다시 생성할 때마다 ④ 의 설정은 사라집니다. 빌드 후처리 스크립트를 쓰신다면 그 스크립트에 넣으십시오.
💡 Tip: Objective-C 클래스 이름은 바뀌지 않았습니다.
SGSApplicationDelegate·SGSPushNotificationCenter등을 그대로 씁니다. 바뀐 것은 프레임워크(모듈) 이름입니다.
확인: 파일에
SGS로 시작하는#import가 남아 있지 않고, 실기기에서 외부 로그인이 앱으로 정상 복귀하며 실행 직후 화면이 검게 남지 않습니다.
Step.5 빌드 확인
양 플랫폼을 모두 빌드해 마이그레이션이 끝났는지 확인합니다.
- 기존
Assets/Stove를 삭제하고 3.0.0 패키지를 임포트했다 -
Podfile에SGS로 시작하는 pod 이 하나도 남아 있지 않다 -
mainTemplate.gradle의com.stove:좌표가 임포트한 패키지와 1:1 이고2.9버전이 하나도 없다 - iOS 빌드 성공 —
pod install후 링커 에러 없음 - Android 빌드 성공
-
AndroidManifest의activity android:name이 실재하는 Activity 를 가리키고, 그 Activity 에 훅 3개가 들어 있다 - 커스텀
AppController를 쓴다면 Step.4 ①②③ 이 모두 들어 있다 (iOS) - Unity 2022.3.72f1 미만이라면 부록 A 의 SceneDelegate 와
Info.plist설정이 들어 있다 (iOS)
Step.6 실기기 확인
⚠️ 빌드 성공으로 끝내지 마십시오.
이번 마이그레이션에서 놓치기 쉬운 문제는 컴파일 에러가 아니라 빌드는 성공하지만 실행 시 오류 없이 동작하지 않는 경우입니다. 진입점 훅 3개, iOS 의onOpenURL:·configurationForConnectingSceneSession:, 매니페스트가 가리키는 클래스의 실재 여부는 전부 빌드에서 드러나지 않습니다.
최소한 아래 3개는 수행하십시오. 다른 어떤 테스트로도 대체되지 않습니다.
- 오버레이 화면에서 파일 첨부 —
ViewUI.handleIntent/7585를 검증하는 유일한 경로 - 외부 로그인 후 앱 복귀 (iOS) — Step.4 ② 를 검증하는 유일한 경로
- 앱을 완전히 종료한 상태에서 푸시 알림 탭 —
onCreate훅 경로. 앱이 떠 있는 상태의 테스트로 대체되지 않습니다
항목별 절차와 실패 시 의심할 지점은 별도 문서 Mobile SDK 3.0.0 실기기 스모크 체크리스트(Unity) 에 있습니다. 플랫폼당 20~30분입니다.
04. 참고
⚠️ 주의사항
Assets/Stove는 덮어쓰지 말고 삭제 후 임포트합니다. 2.9.x 잔여 파일이 컴파일 에러를 일으킵니다.
- 패키지 · pod · 좌표 세 가지를 항상 함께 맞춥니다. 3.0.0 은 네이티브 브리지가 자기 기능의 패키지 안에 있어, 쓰지 않는 기능은 패키지 단위로 빼면 pod · 좌표도 필요 없습니다. 반대로 임포트하고 pod 이나 좌표를 누락하면 빌드가 실패합니다.
play-services-games-v2줄은 삭제하지 마십시오. 삭제하면 GPG 로그인이 실패합니다.
- 커스텀
AppController는 자동으로 갱신되지 않습니다. Step.4의 ①②③ 을 모두 직접 반영해야 합니다 —#import교체만으로는 부족합니다.
Assets/Stove/Plugins/의 진입점 2개는 삭제하지 마십시오. 자체 구현으로 대체하는 경우가 아니라면, Android 는 매니페스트가 이 클래스를 가리키므로 없으면 앱이 시작되지 않습니다.
💡 고치지 않아도 되는 것
- C#
using— 네임스페이스가Stove.StoveSDK로 그대로입니다.- 인증 · 결제 · 푸시 호출 코드 — 메서드 시그니처가 동일합니다.
- Objective-C 클래스 이름 —
SGSApplicationDelegate등은 그대로입니다. 프레임워크 이름만 바뀝니다.StoveUnityPlayerActivity.kt— 2.9.x 와 내용이 같습니다.- Kotlin 패키지명 —
com.stove.unity.*·com.stove.push.*가 그대로입니다.
모듈 대응표 (iOS pod / Android 좌표)
| 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종 | 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 | 제거 (대체 모듈 없음) |
빌드가 실패하면
| 증상 | 원인 |
|---|---|
| Unity 컴파일 에러 — 없는 타입 참조 | Step.1에서 Assets/Stove 를 덮어쓰기만 한 경우입니다. 폴더째 삭제 후 다시 임포트하십시오. |
Unity 컴파일 에러 — error CS2001 로 2.9.x 경로를 가리킴 | 에디터가 옛 파일 목록을 캐시한 경우입니다. 에디터를 닫고 Library 폴더를 지운 뒤 다시 여십시오. |
| iOS 링커 에러 — 심볼 없음 | 임포트한 패키지에 대응하는 pod 이 누락된 경우입니다(Step.2). |
| Android 컴파일 에러 — 클래스 없음 | 임포트한 패키지에 대응하는 좌표가 누락된 경우입니다(Step.3). |
| Gradle 의존성 해석 실패 (Android) | 버전 표기를 확인해주세요. |
| 실행 즉시 앱이 시작되지 않음 (Android) | activity android:name 이 존재하지 않는 클래스를 가리키는 경우입니다(Step.1). |
| 외부 로그인 후 앱으로 복귀하지 않음 (iOS) | 커스텀 AppController 에 onOpenURL: 이 없는 경우입니다(Step.4 ②). |
| 실행 직후 검은 화면 (iOS) | Unity 2022.3.72f1 미만에서 SceneDelegate 설정이 빠진 경우입니다(Step.4 ④ · 부록 A). 2022.3.72f1 이상이라면 이 원인이 아닙니다. |
부록 A. StoveUnitySceneDelegate — Unity 2022.3.72f1 미만
Unity 2022.3.72f1 미만은 Unity 가 SceneDelegate 를 제공하지 않아, 아래 파일 2개와 Info.plist 설정이 필요합니다. 없으면 실행 직후 검은 화면이 됩니다.
2022.3.72f1 이상(Unity 6 포함)은 이 부록을 건너뜁니다.
- 생성된 Xcode 프로젝트에 두 파일을 추가합니다 —
.mm은UnityFramework타깃의 Compile Sources 에 넣습니다(앱 타깃이 아닙니다). Info.plist에 scene manifest 를 넣습니다.- 빌드 후처리 스크립트를 쓴다면 1 · 2 를 그 스크립트에 넣습니다 — Unity 가 Xcode 프로젝트를 다시 생성할 때마다 사라지기 때문입니다.
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>
확인:
StoveUnitySceneDelegate.mm이UnityFramework타깃의 Compile Sources 에 있고, 실행 시 화면이 정상 표시되며 외부 로그인 복귀가 동작합니다.
- 개발자센터 이용/스마일게이트 퍼블리싱 게임 관련: stove.developers@smilegate.com
- 스토브 스토어 입점/스토브 스튜디오 관련: store.support@smilegate.com