- 마지막 업데이트
SDK 추가 후 환경 구성·빌드 설정·SDK Config 등록을 안내해요.
개발 환경 설정
환경 정의
스토브 플랫폼은 개발·테스트용 Sandbox와 실제 서비스용 Live 두 가지 환경으로 구성돼요. 두 환경은 데이터·계정·콘솔이 모두 분리되어 있어 SDK도 각 환경에 맞춰 구성해야 해요.
| 구분 | Sandbox | Live |
|---|---|---|
| 용도 | 개발 · QA · 테스트 | 실제 서비스 |
| 파트너스 | partners.gate8.com | partners.onstove.com |
| API Host | api.gate8.com | api.onstove.com |
| PC 런처 | 런처 3.0 Sandbox + 개발자 모드 사용 가능 | 런처 3.0 Live |
| 계정 / 데이터 | 독립 운영. 실 서비스에 영향 없음 | 독립 운영. QA 완료 후 전환 |
환경별 파트너스 접근 안내
ㆍ 파트너스는 환경별로 접속 URL이 달라요. 각 환경 모두 VPN 계정을 통해서만 접근할 수 있어요.
ㆍ SDK Config·앱 등록 등 모든 등록 작업은 각 환경의 파트너스에서 별도로 진행해야 해요.
- 환경 전환
SDK가 어떤 환경을 호출할지는 클라이언트 빌드의 환경 설정 값으로 결정돼요.
일반적으로 빌드 타입(debug / release) 또는 SDK 초기화 옵션으로 분기해요.- 개발·QA 빌드: Sandbox
- 스토어 배포 빌드: Live
환경 동기화 주의
ㆍ 클라이언트 환경 설정과 파트너스 SDK Config 등록 환경은 반드시 일치시켜야 해요.
ㆍ Sandbox 클라이언트가 Live SDK Config를 조회하면 SDK init이 실패해요.
플랫폼별 SDK 추가
플랫폼별로 SDK 모듈을 추가하고 빌드 환경을 구성하는 방법이에요. SDK 다운로드는 SDK 다운로드 및 설치 가이드를 먼저 참고해 주세요.
본인 환경 1개 섹션만 위에서 아래로 따라가면 돼요
ㆍ 본인 환경(MobileSDK / PC SDK)에 해당하는 섹션을 순서대로 적용하면 환경 설정이 끝나요. MobileSDK는 빌드 환경(Android / iOS / Unity / Unreal)에 따라 하위 섹션으로 세분화돼요.
ㆍ 예제 코드는 SDK 4.0.0 기준이에요. 최신 모듈 버전은 SDK 다운로드 및 설치에서 확인해 주세요.
ㆍ 4.0.0 은 모든 모듈을 함께 4.0.0 으로 교체해야 하고, 3.x 모듈과 섞어 쓸 수 없어요.
ㆍ 3.0.0 부터 모듈이 통합되어 2.9.x 모듈과 함께 쓸 수 없어요. 2.9.x 에서 올리는 중이라면 3.0.0 업그레이드 안내와 마이그레이션 가이드(Unity · Unreal)를 먼저 확인해 주세요.
ㆍ 요구 환경: iOS 15.0 이상 · Xcode 27.1 이상 · Android minSdk 24 / targetSdk 35 / compileSdk 35 · Android Gradle Plugin 8.6.1 / Kotlin 1.9.25 / Java 17
ㆍ 인증 Provider별 키(facebook_app_id, google_web_client_id, naver_client_id 등)는 로그인 가이드에서 각 Provider별로 다뤄요.
STOVE SDK 4.0.0 은 Xcode 27.1 이상에서 빌드해 주세요
ㆍ 4.0.0 은 Xcode 27.1 · iOS 27.1 SDK 빌드 환경을 기준으로 제공돼요. iOS · Unity · Unreal iOS 빌드 모두 해당돼요.
ㆍ Xcode 27.1 이상에서는 SceneDelegate(UIScene 라이프사이클) 적용과, 앱 · 확장 · 서드파티 pod 을 포함한 모든 타깃의 iOS Deployment Target 15.0 이상 설정이 필수예요. 자세한 내용은 iOS — Xcode 27.1 이상 빌드 환경을 확인해 주세요.
ㆍ 프로젝트 구조나 일정으로 인해 당장 적용하기 어렵다면 개발팀에 문의해 주세요. 프로젝트 상황에 맞는 개별 가이드로 도와드릴게요.
모바일 SDK
모바일 환경(Android · iOS)에서 동작하는 SDK예요. 본인 빌드 환경에 맞는 하위 섹션을 따라가세요. 같은 모바일이라도 빌드 도구(네이티브 / Unity / Unreal)별로 설정 방식이 달라 4개로 분리되어 있어요.
Unity
.unitypackage 임포트 후 Unity 스토브 환경 설정 + Android Custom Gradle Template + UnityPlayerActivity 추가 설정 + iOS Xcode 후처리까지 진행해요. (Unity 2022.3.10f1 이상)
1) Unity 패키지 임포트
- SDK 다운로드 및 설치에서 받은
.unitypackage를 압축 해제 - Unity → Assets → Import Package → Custom Package…로 가져오기
Stove패키지를 먼저 임포트한 뒤, 필요한 기능의 패키지를 임포트해요. 임포트한 패키지와 iOSPodfile의 pod, AndroidmainTemplate.gradle의 좌표는 항상 1:1로 맞춰야 해요.
2) 스토브 환경 설정 (Zone)
iOS Info.plist의 StoveEnvironment와 별개로, Unity는 에디터 Inspector에서 직접 환경을 설정해요.
- Unity → Stove → Edit Settings 클릭
- Inspector 창에서
Zone항목 설정 —live/sandbox
3) Android — Custom Gradle Template 5개 활성화
Project Settings → Player → Android → Publishing Settings에서 아래 5개를 모두 체크해요.
- Custom Main Gradle Template →
Assets/Plugins/Android/mainTemplate.gradle - Custom Launcher Gradle Template →
launcherTemplate.gradle - Custom Base Gradle Template →
baseProjectTemplate.gradle - Custom Gradle Properties Template →
gradleTemplate.properties - Custom Settings Gradle Template →
settingsTemplate.gradle
baseProjectTemplate.gradle — Plugin 버전 지정
plugins {
// Android Gradle Plugin 버전은 사용하는 Unity 버전에 내장된 Gradle 과 호환되는 값으로 맞춰요.
// https://docs.unity3d.com/Manual/android-gradle-overview.html
id 'com.android.application' version '8.6.1' apply false
id 'com.android.library' version '8.6.1' apply false
id 'org.jetbrains.kotlin.android' version '1.9.25' apply false
id 'com.google.gms.google-services' version '4.4.2' apply false
//**BUILD_SCRIPT_DEPS**
}
task clean(type: Delete) {
delete rootProject.buildDir
}
gradleTemplate.properties — AndroidX / Jetifier 활성화
org.gradle.jvmargs=-Xmx**JVM_HEAP_SIZE**M
org.gradle.parallel=true
unityStreamingAssets=**STREAMING_ASSETS**
android.useAndroidX=true
android.enableJetifier=true
**ADDITIONAL_PROPERTIES**
settingsTemplate.gradle — STOVE / Huawei / OneStore Maven 저장소 등록
pluginManagement {
repositories {
**ARTIFACTORYREPOSITORY**
gradlePluginPortal()
google()
mavenCentral()
}
}
include ':launcher', ':unityLibrary'
**INCLUDES**
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
repositories {
**ARTIFACTORYREPOSITORY**
google()
mavenCentral()
flatDir { dirs "${project(':unityLibrary').projectDir}/libs" }
maven { url "https://externalnexus.iam0.com/repository/mvp"; allowInsecureProtocol = true } // STOVE
maven { url "https://jitpack.io"; allowInsecureProtocol = true }
maven { url "https://developer.huawei.com/repo/"; allowInsecureProtocol = true } // Huawei
maven { url "https://repo.onestore.net/repository/onestore-sdk-public"; allowInsecureProtocol = true } // OneStore
}
}
mainTemplate.gradle — 스토브 의존성 + Java 17 + dataBinding + multiDexEnabled
plugins {
id 'com.android.library'
id 'org.jetbrains.kotlin.android'
id 'org.jetbrains.kotlin.kapt'
}
**APPLY_PLUGINS**
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar'])
implementation 'com.stove:stove:4.0.0'
implementation 'com.stove:stove-providers:4.0.0'
implementation 'com.stove:stove-push:4.0.0'
implementation 'com.stove:stove-push-firebase:4.0.0'
implementation 'com.stove:stove-iap:4.0.0'
implementation 'com.stove:stove-iap-google:4.0.0'
// implementation 'com.stove:stove-gamelog:4.0.0' // 게임 로그를 쓰는 경우만
// Google Play Games — GPG 로그인을 쓰는 경우
implementation "com.google.android.gms:play-services-games-v2:19.0.0"
implementation 'com.google.android.gms:play-services-tasks:18.0.2'
**DEPS**}
android {
namespace '**APPLICATIONID**'
ndkPath "**NDKPATH**"
compileSdkVersion **APIVERSION**
buildToolsVersion '**BUILDTOOLS**'
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = '17'
}
defaultConfig {
minSdkVersion **MINSDKVERSION**
targetSdkVersion **TARGETSDKVERSION**
ndk {
abiFilters **ABIFILTERS**
}
versionCode **VERSIONCODE**
versionName '**VERSIONNAME**'
multiDexEnabled true
consumerProguardFiles 'proguard-unity.txt'**USER_PROGUARD**
}
buildFeatures {
dataBinding true
}
lint {
abortOnError false
}
androidResources {
noCompress = **BUILTIN_NOCOMPRESS** + unityStreamingAssets.tokenize(', ')
ignoreAssetsPattern = "!.svn:!.git:!.ds_store:!*.scc:!CVS:!thumbs.db:!picasa.ini:!*~"
}**PACKAGING_OPTIONS**
}
**IL_CPP_BUILD_SETUP**
**SOURCE_BUILD_SETUP**
**EXTERNAL_SOURCES**
스토브 좌표는 프로젝트 구성에 맞게 조정해요
ㆍ 위 예시는 구글 마켓 · Firebase 푸시 기준이에요. 화웨이 · 원스토어 마켓을 빌드한다면 com.stove:stove-iap-huawei · com.stove:stove-iap-onestore · com.stove:stove-push-huawei를 함께 추가해요.
ㆍ com.stove: 좌표는 모두 4.0.0 으로 맞춰요. 2.9.x · 3.x 버전이 남아 있으면 안 돼요. 4.0.0 모듈과 함께 쓸 수 없어요.
ㆍ GPG(Google Play Games) 로그인을 쓴다면 play-services-games-v2 · play-services-tasks 줄은 지우지 마세요. 지우면 GPG 로그인이 실패해요.
launcherTemplate.gradle — Google Services 적용 + Amazon Build 충돌 회피 + Android 7.x 지원
plugins {
id 'com.android.application'
id 'com.google.gms.google-services'
}
dependencies {
implementation project(':unityLibrary')
}
configurations.all {
// Amazon Build에서 중복 의존성 제외
exclude(group: 'com.google.protobuf', module: 'protobuf-lite')
// Android 7.x 지원 (필수)
resolutionStrategy {
force 'com.google.android.gms:play-services-ads-identifier:18.0.1'
}
}
android {
namespace '**APPLICATIONID**'
ndkPath "**NDKPATH**"
compileSdkVersion **APIVERSION**
buildToolsVersion '**BUILDTOOLS**'
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
defaultConfig {
minSdkVersion **MINSDKVERSION**
targetSdkVersion **TARGETSDKVERSION**
applicationId '**APPLICATIONID**'
ndk {
abiFilters **ABIFILTERS**
}
versionCode **VERSIONCODE**
versionName '**VERSIONNAME**'
multiDexEnabled true
}
buildFeatures {
dataBinding true
}
lint {
abortOnError false
}
androidResources {
noCompress = **BUILTIN_NOCOMPRESS** + unityStreamingAssets.tokenize(', ')
ignoreAssetsPattern = "!.svn:!.git:!.ds_store:!*.scc:!CVS:!thumbs.db:!picasa.ini:!*~"
}**SIGN**
buildTypes {
debug {
minifyEnabled **MINIFY_DEBUG**
proguardFiles getDefaultProguardFile('proguard-android.txt')**SIGNCONFIG**
jniDebuggable true
}
release {
minifyEnabled **MINIFY_RELEASE**
proguardFiles getDefaultProguardFile('proguard-android.txt')**SIGNCONFIG**
}
}**PACKAGING_OPTIONS****PLAY_ASSET_PACKS****SPLITS**
**BUILT_APK_LOCATION**
bundle {
language {
enableSplit = false
}
density {
enableSplit = false
}
abi {
enableSplit = true
}
}
}**SPLITS_VERSION_CODE****LAUNCHER_SOURCE_BUILD_SETUP**
4) UnityPlayerActivity 상속 시 추가 설정
UnityPlayerActivity를 상속받아 커스텀 Activity를 사용 중이라면, STOVE Push / View UI Overlay가 정상 동작하도록 아래 코드를 추가하고 manifest에서 hardwareAccelerated를 설정해야 해요. 상속해 쓰지 않는다면 SDK가 제공하는 com.stove.unity.StoveUnityPlayerActivity를 그대로 지정하면 돼요.
class CustomActivity : UnityPlayerActivity() {
override fun onCreate(bundle: Bundle?) {
super.onCreate(bundle)
Push.handleIntent(applicationContext, intent) // Push 동작 추가
}
override fun onNewIntent(newIntent: Intent?) {
super.onNewIntent(newIntent)
Push.handleIntent(applicationContext, newIntent)
}
// UI Overlay 동작 추가
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == 7585) ViewUI.handleIntent(requestCode, resultCode, data)
}
}
진입점을 빠뜨려도 빌드는 성공해요AndroidManifest의 activity android:name이 실재하지 않는 클래스를 가리키면 앱이 실행 즉시 종료돼요. 위 훅이 빠지면 푸시 · 오버레이 파일 첨부가 오류 없이 동작하지 않아요. 실기기에서 꼭 확인해 주세요.
AndroidManifest 하드웨어 가속 설정 (필수)
<activity
android:name="com.stove.unity.StoveUnityPlayerActivity"
android:hardwareAccelerated="true"
android:exported="true">
<!-- ... -->
</activity>
5) iOS — Podfile + Xcode 후처리 (PostProcessBuild 권장)
Unity iOS 빌드는 Xcode 27.1 이상에서 진행해 주세요
ㆍ STOVE SDK 4.0.0 은 Xcode 27.1 이상 빌드가 필수예요. Podfile 의 post_install 블록과 Unity-iPhone · UnityFramework · NotificationServiceExtension 타깃의 Deployment Target 15.0 설정이 함께 필요해요.
ㆍ SceneDelegate 는 iOS Unity UISceneDelegate 대응 업데이트에 따라 적용해 주세요.
ㆍ pod 재설치 절차와 빌드 환경 확인 항목은 iOS — Xcode 27.1 이상 빌드 환경을 확인해 주세요.
Podfile — 스토브 pod은 UnityFramework target에 추가해요. 임포트한 패키지와 1:1로 맞춰요.
source 'http://stove-developers-gitlab.sginfra.net/stove-sdk/Specs.git'
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '15.0'
use_frameworks!
target 'UnityFramework' do
pod 'Stove', '4.0.0'
pod 'StoveProviders', '4.0.0'
pod 'StoveIAP2', '4.0.0'
pod 'StovePush', '4.0.0'
# pod 'StoveGameLog', '4.0.0' # 게임 로그를 쓰는 경우만
end
target 'Unity-iPhone' do
end
# Notification Service Extension 을 쓰는 경우
target 'NotificationServiceExtension' do
pod 'StovePushExtension', '4.0.0'
end
# Xcode 27+ requires IPHONEOS_DEPLOYMENT_TARGET >= 15.0.
# Third-party dependency pods (Facebook, Google, Naver, etc.) still declare lower targets in their podspecs.
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
if config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'].to_f < 15.0
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
end
end
end
end
STOVE pod은 모두 4.0.0 으로 맞춰요
ㆍ 4.0.0 pod과 3.x pod은 함께 쓸 수 없어요. 일부 pod만 4.0.0 으로 바꾸지 마세요.
ㆍ SGS로 시작하는 2.9.x pod(SGSBase 등)이 남아 있으면 안 돼요.
ㆍ SGSGamingServices는 3.0.0에서 제거되었어요. GPG User ID 기능은 StoveProviders에 들어 있어요.
ㆍ post_install 블록이 필요한 이유는 iOS — Xcode 27.1 이상 빌드 환경을 확인해 주세요. 이미 post_install을 쓰고 있다면 기존 블록 안에 반복문을 병합해요.
Unity는 빌드 시 Xcode 프로젝트를 생성해요. 매 빌드마다 수동으로 손대지 않도록 Assets/Editor/에 PostProcessBuild 스크립트를 두는 것을 권장해요. 자동화로 처리할 항목은 다음과 같아요(구체값은 아래 iOS 섹션 참조).
pod installInfo.plist키 추가 (StoveEnvironment/LSApplicationQueriesSchemes=[mstove]/ URL Schemes / 권한 메시지)- entitlements 머지 (Capabilities 키)
- Library / Runpath Search Paths 추가 (Xcode 16.x / 26 분기)
- iOS Deployment Target 15.0 설정 —
Unity-iPhone·UnityFramework·NotificationServiceExtension타깃 모두 (Xcode 27.1 이상 빌드 시 필수) AppDelegate.mm에SGSApplicationDelegate openURL위임 코드 삽입 — 3.0.0 부터 import 경로가<Stove/Stove.h>·<StovePush/StovePush.h>로 바뀌었어요. 커스텀AppController를 쓴다면 iOS Unity UISceneDelegate 대응 업데이트도 함께 적용해요.
Library / Runpath Search Paths — Xcode 버전 분기 실제 코드:
// Xcode 26부터 Metal toolchain이 cryptex로 분리되어 swift-5.0 경로 제거
pbxProject.AddBuildProperty(targetGuid, "LIBRARY_SEARCH_PATHS", "$(SDKROOT)/usr/lib/swift");
pbxProject.AddBuildProperty(targetGuid, "LIBRARY_SEARCH_PATHS", "$(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)");
// ⚠️ Xcode 26.0.x 사용 시 $(TOOLCHAIN_DIR)가 Metal cryptex로 잘못 resolve되는 버그 대응 (26.2에서 수정)
// pbxProject.AddBuildProperty(targetGuid, "LIBRARY_SEARCH_PATHS",
// "$(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/$(PLATFORM_NAME)");
pbxProject.AddBuildProperty(targetGuid, "LD_RUNPATH_SEARCH_PATHS", "/usr/lib/swift");
pbxProject.AddBuildProperty(targetGuid, "ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES", "YES");
// UnityFramework target
pbxProject.AddBuildProperty(frameworkTargetGuid, "LIBRARY_SEARCH_PATHS", "$(SDKROOT)/usr/lib/swift");
pbxProject.AddBuildProperty(frameworkTargetGuid, "LIBRARY_SEARCH_PATHS", "$(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)");
pbxProject.SetBuildProperty(frameworkTargetGuid, "LD_RUNPATH_SEARCH_PATHS", "/usr/lib/swift");
pbxProject.AddBuildProperty(frameworkTargetGuid, "LD_RUNPATH_SEARCH_PATHS", "$(inherited)");
pbxProject.AddBuildProperty(frameworkTargetGuid, "LD_RUNPATH_SEARCH_PATHS", "@executable_path/Frameworks");
pbxProject.AddBuildProperty(frameworkTargetGuid, "LD_RUNPATH_SEARCH_PATHS", "@loader_path/Frameworks");
pbxProject.AddBuildProperty(frameworkTargetGuid, "ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES", "NO");
iOS Deployment Target — Xcode 27.1 이상 빌드 시 필수:
// Unity-iPhone · UnityFramework · NotificationServiceExtension 타깃 모두 15.0
pbxProject.SetBuildProperty(targetGuid, "IPHONEOS_DEPLOYMENT_TARGET", "15.0");
pbxProject.SetBuildProperty(frameworkTargetGuid, "IPHONEOS_DEPLOYMENT_TARGET", "15.0");
pbxProject.SetBuildProperty(notificationServiceTarget, "IPHONEOS_DEPLOYMENT_TARGET", "15.0");
수동 처리도 가능해요
자동화 스크립트를 두지 않는다면 매 빌드 후 Xcode를 열어 위 값을 직접 적용해도 동작에는 문제없어요. 다만 빌드가 잦으면 자동화를 권장해요.
6) iOS — 인앱결제 (StoreKit 2)
Unity 의 StoveIAP 패키지는 iOS 에서 StoreKit 2 기반 StoveIAP2 pod을 사용해요. Podfile에 StoveIAP2를 추가하면 돼요. 2.9.x 처럼 IAPNativeInterface.mm의 import 를 바꾸거나 prepareTransactionListener 호출을 직접 추가할 필요는 없어요. 패키지의 stove_iap_setListener가 내부에서 호출해요.
7) Notification Service Extension (확장 푸시 사용 시)
iOS 푸시에서 이미지·액션을 사용하려면 Notification Service Extension target을 추가하고 StovePushExtension Pod을 의존성으로 넣어야 해요.
- Podfile에 Notification Service Extension target 추가 (위 5) iOS — Podfile 참고)
- Xcode → File → New → Target → "Notification Service Extension"으로 target 생성
Notification Service Extension target의 Build Settings — Xcode 버전 분기 실제 코드:
pbxProject.AddBuildProperty(notificationServiceTarget, "LIBRARY_SEARCH_PATHS", "$(SDKROOT)/usr/lib/swift");
pbxProject.AddBuildProperty(notificationServiceTarget, "LIBRARY_SEARCH_PATHS", "$(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)");
// ⚠️ Extension 타겟은 Swift 소스가 없어 Xcode 26.0.x 버그의 주요 영향 지점 (26.2에서 수정)
// pbxProject.AddBuildProperty(notificationServiceTarget, "LIBRARY_SEARCH_PATHS",
// "$(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/$(PLATFORM_NAME)");
pbxProject.SetBuildProperty(notificationServiceTarget, "LD_RUNPATH_SEARCH_PATHS", "/usr/lib/swift");
pbxProject.AddBuildProperty(notificationServiceTarget, "LD_RUNPATH_SEARCH_PATHS", "$(inherited)");
pbxProject.AddBuildProperty(notificationServiceTarget, "LD_RUNPATH_SEARCH_PATHS", "@executable_path/Frameworks");
pbxProject.AddBuildProperty(notificationServiceTarget, "LD_RUNPATH_SEARCH_PATHS", "@executable_path/../../Frameworks");
pbxProject.AddBuildProperty(notificationServiceTarget, "LD_RUNPATH_SEARCH_PATHS", "@loader_path/Frameworks");
Unreal
Plugins 폴더 배치 + Project.build.cs 의존성 + UPL(GamePlugin.xml)로 Android Gradle 의존성 주입 + Online Subsystem GooglePlay 비활성화까지가 기본이에요. iOS Capabilities(keychain·app group) 또는 LSSupportsOpeningDocumentsInPlace(네이버 로그인용)가 필요하면 커스텀 엔진 빌드 환경이 추가로 필요해요. (Unreal 5.4.4 이상)
1) 플러그인 배치 & 활성화
- 다운로드한 스토브 플러그인을 프로젝트
Plugins폴더에 복사 .uproject또는 편집 → 플러그인 메뉴에서 활성화
"Plugins": [
{ "Name": "Stove", "Enabled": true },
{ "Name": "StoveProviders", "Enabled": true },
{ "Name": "StoveIAP", "Enabled": true },
{ "Name": "StovePush", "Enabled": true },
{ "Name": "StoveGameLog", "Enabled": true }
]
Stove는 나머지 플러그인이 모두 의존하므로 항상 필요해요.- 결제를 쓰지 않으면
StoveIAP, 푸시를 쓰지 않으면StovePush, 게임 로그를 쓰지 않으면StoveGameLog는 빼도 돼요. - 2.9.x 의
SGS_IAP_Google·SGS_Push_Firebase는 각각StoveIAP·StovePush에 흡수되어 별도 플러그인이 없어요.
2.9.x 의 SGS_* 플러그인 폴더는 삭제해요
남아 있으면 iOS 에서 중복 심볼 링커 에러가 나요. .uproject에 "Enabled": false로 남겨 두지도 마세요.
2) Project.build.cs — 모듈 의존성
.uproject에서 활성화한 플러그인과 같은 이름을 적어요. 한쪽만 고치면 빌드가 되지 않아요.
using System.IO;
public class Game : ModuleRules
{
public Game(ReadOnlyTargetRules Target) : base(Target)
{
PublicDependencyModuleNames.AddRange(new string[] {
"Core", "CoreUObject", "Engine", "InputCore",
"Stove", "StoveProviders", "StoveIAP", "StovePush", "StoveGameLog"
});
}
}
3) Android 설정
SDK Manager 버전 고정
- SDK Platform 34 설치
- SDK Tools 34.0.0 설치 (상위 버전은 제거 또는 체크 해제)
Gradle 8.6 설정 — Engine/Build/Android/Java/gradle/gradle/wrapper/gradle-wrapper.properties
distributionUrl=https://services.gradle.org/distributions/gradle-8.6-all.zip
아래 샘플은 Gradle 8.6 기준이에요
다른 Gradle 버전을 사용한다면 해당 버전에 맞게 샘플 코드를 추가로 수정해야 할 수 있어요.
Online Subsystem GooglePlay 비활성화 (필수) — 언리얼 기본 제공 플러그인의 Online Subsystem GooglePlay를 비활성화해서 스토브 플러그인의 GooglePlay 라이브러리와의 충돌을 방지해요.
Extra Manifest — 편집 → 프로젝트 세팅 → Android → 고급 APK 패키징
<meta-data android:name="com.stove.environment" android:value="live" /> <!-- live / sandbox -->
UPL GamePlugin.xml — Unreal에서 Gradle 의존성을 주입하는 유일한 통로
<?xml version="1.0" encoding="utf-8"?>
<root xmlns:android="http://schemas.android.com/apk/res/android">
<init>
<log text="Android init"/>
</init>
<buildGradleAdditions>
<insert>
dependencies {
implementation 'com.stove:stove:4.0.0'
implementation 'com.stove:stove-providers:4.0.0'
implementation 'com.stove:stove-iap-google:4.0.0'
implementation 'com.stove:stove-push-firebase:4.0.0'
// Google Play Games — GPG 로그인을 쓰는 경우
implementation "com.google.android.gms:play-services-games-v2:19.0.0"
}
</insert>
</buildGradleAdditions>
</root>
stove-iap-google·stove-push-firebase가stove-iap·stove-push를 함께 가져와요.- 화웨이 · 원스토어 마켓을 빌드한다면
com.stove:stove-iap-huawei·com.stove:stove-iap-onestore·com.stove:stove-push-huawei를 추가해요. StoveGameLog플러그인은com.stove:stove-gamelog의존성을 직접 추가하므로 여기에 적지 않아도 돼요.- GPG(Google Play Games) 로그인을 쓴다면
play-services-games-v2줄은 지우지 마세요. 지우면 GPG 로그인이 실패해요.
Project.build.cs에 UPL 연결
public class Game : ModuleRules
{
public Game(ReadOnlyTargetRules Target) : base(Target)
{
// ...
if (Target.Platform == UnrealTargetPlatform.Android)
{
PrivateDependencyModuleNames.AddRange(new string[] { "Launch" });
string PluginPath = Utils.MakePathRelativeTo(ModuleDirectory, Target.RelativeEnginePath);
AdditionalPropertiesForReceipt.Add(
"AndroidPlugin",
Path.Combine(PluginPath, "GamePlugin.xml"));
}
}
}
이 UPL을 빼면 APK에 STOVE SDK가 안 들어가요
Unreal에서는 build.gradle을 직접 편집할 수 없고, UPL로만 dependency를 주입할 수 있어요.
4) iOS 설정 — 기본
Unreal iOS 빌드는 Xcode 27.1 이상에서 진행해 주세요
ㆍ STOVE SDK 4.0.0 은 Xcode 27.1 이상 빌드가 필수예요. 아래 Minimum iOS Version(iOS 15) 설정이 함께 필요해요.
ㆍ SceneDelegate 는 iOS Unreal UISceneDelegate 대응 업데이트에 따라 적용해 주세요.
Unreal 빌드 후 산출된 Xcode 프로젝트에 적용해요. 매 빌드마다 Xcode 설정이 초기화될 수 있으니 IPP 또는 Build.cs 후처리로 자동화를 권장해요. 처리할 항목:
Info.plist—StoveEnvironment/LSApplicationQueriesSchemes=[mstove]/ URL Schemes / 권한 메시지 (구체값은 아래 iOS 섹션 참고)- iOS 프레임워크는 각 스토브 플러그인의
Build.cs가PublicAdditionalFrameworks로 링크해요. 게임 프로젝트에서 따로 지정할 것은 없어요. - 최소 iOS 버전 — 편집 → 프로젝트 세팅 → iOS → Minimum iOS Version을
iOS 15로 설정해요. Xcode 27.1 이상 빌드 시 필수예요.Config/DefaultEngine.ini에서는 아래 값이에요.
[/Script/IOSRuntimeSettings.IOSRuntimeSettings]
MinimumiOSVersion=IOS_15
5) Unreal 플러그인 구성 (3.0.0 이상)
3.0.0 에서 플러그인이 통합되었어요. 2.9.x 플러그인과 함께 쓸 수 없으니 모두 교체해요. 플러그인 구성은 4.0.0 에서도 같고, 4.0.0 플러그인은 3.x 플러그인과 섞어 쓸 수 없으니 모든 플러그인을 4.0.0 으로 함께 교체해요.
| 3.0.0 이상 | 2.9.x | iOS 프레임워크 |
|---|---|---|
Stove | SGS_Base SGS_Log SGS_Auth SGS_AuthUI SGS_View | Stove |
StoveProviders | SGS_Auth_Google SGS_Auth_Facebook SGS_Auth_UApple SGS_Auth_Naver SGS_Auth_Line SGS_Auth_Steam SGS_Auth_GooglePlayGames | StoveProviders + 서드파티(GoogleSignIn · FBSDK · LineSDK · NidThirdPartyLogin 등) |
StoveIAP | SGS_IAP SGS_IAP_StoreKit2 SGS_IAP_Google | StoveIAP2 (StoreKit 2) |
StovePush | SGS_Push SGS_Push_Firebase | StovePush |
StoveGameLog (신규) | (SGS_Log에 포함) | StoveGameLog |
| 제거 (대체 플러그인 없음) | SGS_GamingServices | — |
6) iOS — 인앱결제 (StoreKit 2)
3.0.0 이상의 StoveIAP 플러그인은 iOS 에서 StoreKit 2 기반 StoveIAP2 프레임워크를 링크해요. 2.9.x 처럼 SGS_IAP_StoreKit2 플러그인으로 따로 교체할 필요가 없어요. prepareTransactionListener 호출 등 내부 처리도 플러그인에 포함돼 있어 게임에서 추가 작업이 필요 없어요.
7) iOS — Capabilities 설정 (커스텀 엔진 빌드 필요)
Unreal 5.4.4 기본 엔진은 Push Notifications / Sign in with Apple / In-App Purchase만 Capabilities로 지원해요. STOVE SDK에 필요한 Keychain Sharing / App Group을 추가하려면 GitHub의 Unreal Engine 풀 소스로 빌드한 커스텀 엔진이 필요해요.
커스텀 엔진 빌드 환경에서만 적용 가능합니다
ㆍ Epic Games 계정과 GitHub 계정을 연결해 Unreal Engine GitHub에서 풀 소스 받기
ㆍ 빌드 절차는 Unreal Engine GitHub 다운로드 안내를 참고하세요
커스텀 엔진의 Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSExports.cs의 WriteEntitlements() 함수에 스토브 키체인 설정을 추가해요.
// IOSExports.cs > WriteEntitlements() 함수 내에 추가
Text.AppendLine("\t<key>keychain-access-groups</key>");
Text.AppendLine("\t<array><string>$(AppIdentifierPrefix)com.stove.globaldata</string></array>");
키체인·앱 그룹이 필수가 아닌 게임은 기본 엔진으로 가능해요
토큰 영속 저장이나 NSE(푸시 확장) 등을 사용하지 않는 단순 연동 케이스라면 기본 엔진으로도 빌드할 수 있어요. 적용 가능 여부는 퍼블리싱 기술 담당자에게 확인해 주세요.
8) iOS — LSSupportsOpeningDocumentsInPlace 사용 (STOVE SDK 2.8.0 ~ 2.9.x, 커스텀 엔진 빌드 필요)
STOVE SDK 3.0.0 미만에서만 적용해요
ㆍ STOVE SDK 3.0.0 이상은 Unreal Engine의 기본 FIOSCoreDelegates::OnOpenURL로 URL callback을 받기 때문에 이 패치가 필요 없어요.
ㆍ 이 패치가 남아 있으면 OnOpenURL이 호출되지 않아 외부 로그인 후 게임으로 돌아와도 로그인이 완료되지 않아요. 빌드는 성공하니 주의해 주세요.
ㆍ 2.9.x에서 3.0.0으로 올린다면 마이그레이션 가이드(Unreal)의 Step.5에 따라 이 패치를 제거해 주세요.
네이버 로그인을 추가하면 deprecated된 OpenURL 메서드와 신규 메서드를 동시에 처리해야 해서 엔진 소스 수정이 필요해요. 이 작업도 커스텀 엔진 빌드 환경에서만 가능합니다.
배경: Unreal 엔진은 iOS의 deprecated된 OpenURL 함수를 사용하지만, 네이버 SDK는 신규 함수 형태를 사용해요. 두 형태를 모두 지원하려면 IOSAppDelegate에 application:openURL:options: 메서드 분기를 추가해야 해요.
수정 파일:
아래 예시 코드의 add - start 부터 add - end 까지 코드에 추가해 주세요
Engine/Source/Runtime/ApplicationCore/Public/IOS/IOSAppDelegate.h
DECLARE_MULTICAST_DELEGATE_FourParams(FOnOpenURL, UIApplication*, NSURL*, NSString*, id);
static FOnOpenURL OnOpenURL;
// add - start
DECLARE_MULTICAST_DELEGATE_ThreeParams(FOnOpenURLwithOptions, UIApplication*, NSURL*, NSDictionary* );
static FOnOpenURLwithOptions OnOpenURLwithOptions;
// add - end
// -------------------------------------------//
// parameters passed from openURL
@property (nonatomic, retain) NSMutableArray* savedOpenUrlParameters;
// add - start
@property (nonatomic, retain) NSMutableArray* savedOpenUrlWithOptionsParameters;
// add - end
Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSAppDelegate.cpp
FIOSCoreDelegates::FOnOpenURL FIOSCoreDelegates::OnOpenURL;
// add - start
FIOSCoreDelegates::FOnOpenURLwithOptions FIOSCoreDelegates::OnOpenURLwithOptions;
// add - end
FIOSCoreDelegates::FOnWillResignActive FIOSCoreDelegates::OnWillResignActive;
FIOSCoreDelegates::FOnDidBecomeActive FIOSCoreDelegates::OnDidBecomeActive;
TArray<FIOSCoreDelegates::FFilterDelegateAndHandle> FIOSCoreDelegates::PushNotificationFilters;
// ----------------------------------------- //
@synthesize AccessibilityCacheTimer;
#endif
@synthesize savedOpenUrlParameters;
// add - start
@synthesize savedOpenUrlWithOptionsParameters;
// add - end
@synthesize BackgroundSessionEventCompleteDelegate;
// ----------------------------------------- //
GShowSplashScreen = false;
}, TStatId(), NULL, ENamedThreads::ActualRenderingThread);
}
// add - start
for (NSDictionary* openUrlParameter in self.savedOpenUrlWithOptionsParameters)
{
UIApplication* application = [openUrlParameter valueForKey : @"application"];
NSURL* url = [openUrlParameter valueForKey : @"url"];
NSDictionary<NSString*, id> * options = [openUrlParameter valueForKey : @"options"];
FIOSCoreDelegates::OnOpenURLwithOptions.Broadcast(application, url, options);
}
self.savedOpenUrlWithOptionsParameters = nil; // clear after saved openurl delegate running
// add - end
for (NSDictionary* openUrlParameter in self.savedOpenUrlParameters)
{
UIApplication* application = [openUrlParameter valueForKey : @"application"];
// ----------------------------------------- //
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
// save launch options
self.launchOptions = launchOptions;
#if PLATFORM_TVOS
self.bDeviceInPortraitMode = false;
#else
// use the status bar orientation to properly determine landscape vs portrait
self.bDeviceInPortraitMode = UIInterfaceOrientationIsPortrait([[UIApplication sharedApplication] statusBarOrientation]);
printf("========= This app is in %s mode\n", self.bDeviceInPortraitMode ? "PORTRAIT" : "LANDSCAPE");
#endif
// check OS version to make sure we have the API
OSVersion = [[[UIDevice currentDevice] systemVersion] floatValue];
if (!FPlatformMisc::IsDebuggerPresent() || GAlwaysReportCrash)
{
// InstallSignalHandlers();
}
self.savedOpenUrlParameters = [[NSMutableArray alloc] init];
// add - start
self.savedOpenUrlWithOptionsParameters = [[NSMutableArray alloc] init];
// add - end
self.PeakMemoryTimer = [NSTimer scheduledTimerWithTimeInterval:0.1f target:self selector:@selector(RecordPeakMemory) userInfo:nil repeats:YES];
#if !BUILD_EMBEDDED_APP
// ----------------------------------------- //
return YES;
}
// add - start
//### use option
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString*, id> *)options
{
#if !NO_LOGGING
NSLog(@"%s", "IOSAppDelegate openURL options\n");
#endif
NSString* EncdodedURLString = [url absoluteString];
NSString* URLString = [EncdodedURLString stringByRemovingPercentEncoding];
FString CommandLineParameters(URLString);
// Strip the "URL" part of the URL before treating this like args. It comes in looking like so:
// "MyGame://arg1 arg2 arg3 ..."
// So, we're going to make it look like:
// "arg1 arg2 arg3 ..."
int32 URLTerminator = CommandLineParameters.Find( TEXT("://"), ESearchCase::CaseSensitive);
if ( URLTerminator > -1 )
{
CommandLineParameters.RightChopInline(URLTerminator + 3, false);
}
FIOSCommandLineHelper::InitCommandArgs(CommandLineParameters);
self.bCommandLineReady = true;
[self.CommandLineParseTimer invalidate];
self.CommandLineParseTimer = nil;
// Save openurl infomation before engine initialize.
// When engine is done ready, running like previous. ( if OnOpenUrl is bound on game source. )
if (bEngineInit)
{
FIOSCoreDelegates::OnOpenURLwithOptions.Broadcast(app, url, options);
}
else
{
#if !NO_LOGGING
NSLog(@"%s", "Before Engine Init receive IOSAppDelegate openURL\n");
#endif
NSDictionary* openUrlParameter = [NSDictionary dictionaryWithObjectsAndKeys :
app , @"application",
url, @"url",
options, @"options",
nil];
[savedOpenUrlWithOptionsParameters addObject : openUrlParameter];
}
return YES;
}
// add - end
FCriticalSection RenderSuspend;
- (void)applicationWillResignActive:(UIApplication *)application
{
구체 패치 코드가 필요하시면
엔진 버전별로 수정 위치가 다르므로, 상세 패치 스니펫은 스토브 퍼블리싱 기술 담당자에게 요청해 주세요.
Android
Gradle 의존성 + AndroidManifest.xml 메타데이터 + Android 7.x 지원 강제 옵션을 설정해요.
1) Gradle 의존성 (app/build.gradle)
STOVE Maven 저장소를 등록하고 필요한 모듈을 의존성으로 추가해요.
buildscript {
ext.kotlin_version = "1.9.25"
repositories {
google()
mavenCentral()
}
dependencies {
classpath 'com.android.tools.build:gradle:8.6.1'
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}
}
plugins {
id 'com.android.application'
id 'kotlin-android'
id 'kotlin-kapt'
}
android {
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = 17
}
buildFeatures {
buildConfig = true
viewBinding true
dataBinding true
}
}
repositories {
google()
maven {
url "https://externalnexus.iam0.com/repository/mvp"
allowInsecureProtocol = true // Android Gradle Plugin 7.0+ 필수
}
mavenCentral()
}
dependencies {
// 핵심 (인증 · 인증 UI · 뷰 · 로그 통합)
implementation 'com.stove:stove:4.0.0'
// 인증 Provider (Google · GPG · Facebook · Naver · Line · Steam · Apple 통합)
implementation 'com.stove:stove-providers:4.0.0'
// 푸시
implementation 'com.stove:stove-push:4.0.0'
implementation 'com.stove:stove-push-firebase:4.0.0'
// 인앱결제
implementation 'com.stove:stove-iap:4.0.0'
implementation 'com.stove:stove-iap-google:4.0.0'
// 게임 로그 — 게임 로그를 쓰는 경우만
// implementation 'com.stove:stove-gamelog:4.0.0'
}
마켓 · 기능 구성에 맞게 모듈을 조정해요
ㆍ 화웨이 마켓: com.stove:stove-iap-huawei · com.stove:stove-push-huawei / 원스토어: com.stove:stove-iap-onestore
ㆍ 2.9.x 의 com.stove:gamingservices는 3.0.0 에서 제거되었어요. GPG User ID 기능은 stove-providers에 들어 있어요.
ㆍ 모든 com.stove: 모듈을 4.0.0 으로 맞춰요. 3.x 모듈과 4.0.0 모듈은 함께 쓸 수 없어요.
ㆍ 2.9.x 모듈(com.stove:base 등)과 3.0.0 이상 모듈은 함께 쓸 수 없어요. 전체 매핑은 3.0.0 업그레이드 안내를 참고해 주세요.
2) AndroidManifest.xml — 스토브 환경 설정 (필수)
com.stove.environment 메타데이터가 없으면 SDK 초기화 시 AuthConfigurationError(30001)가 발생해요.
<application>
<!-- 환경: live(라이브) / sandbox(테스트) -->
<meta-data
android:name="com.stove.environment"
android:value="live" />
</application>
MemberNo 게임이라면 com.stove.config.enable_guid를 false로 설정해야 해요. GUID 게임은 설정하지 않아도 돼요.
<application>
<!-- MemberNo 게임만 -->
<meta-data
android:name="com.stove.config.enable_guid"
android:value="false" />
</application>
3) (선택) AuthUI 옵션
필요한 경우 아래 메타데이터를 추가하세요. 미설정 시 괄호 안의 기본값으로 동작해요.
<application>
<!-- 약관 화면 색상 테마: orange(default) / black / LostarkM -->
<meta-data android:name="com.stove.auth.ui.theme" android:value="orange" />
<!-- 라이트/다크 모드: 0=시스템(default) / 1=light / 2=dark -->
<meta-data android:name="com.stove.auth.ui.appearance_mode" android:value="1" />
<!-- 약관 화면 크기: full(default) / small -->
<meta-data android:name="com.stove.auth.ui.display_size" android:value="small" />
<!-- 푸시 헤드업 알림: false(default) / true -->
<meta-data android:name="com.stove.push.heads_up_notification_enable" android:value="true" />
</application>
com.stove.auth.ui.sanction_type은 3.0.0 부터 사용하지 않아요
3.0.0 은 제재 · 점검 · 강제 업데이트 안내 화면을 닫을 때 앱을 종료하지 않고 항상 콜백으로 결과를 전달해요. 남아 있어도 동작에는 영향이 없어요. 앱 종료 처리는 점검/업데이트 가이드의 "앱 종료 처리 (3.0.0 이상)"를 참고해 주세요.
4) Android 7.x 지원 (필수)
play-services-ads-identifier를 18.0.1로 고정해야 Android 7.x 단말에서 런타임 크래시가 발생하지 않아요.
configurations.all {
resolutionStrategy {
force 'com.google.android.gms:play-services-ads-identifier:18.0.1'
}
}
5) 디버그 로그 확인
게임 개발·디버깅 시 stove-sdk 태그로 logcat에서 SDK 동작 로그를 볼 수 있어요.
adb shell setprop log.tag.stove-sdk VERBOSE
iOS
CocoaPods로 STOVE SDK를 추가하고 Info.plist / entitlements / Xcode Build Settings / AppDelegate까지 설정해야 정상 동작해요.
iOS 빌드는 Xcode 27.1 이상에서 진행해 주세요
ㆍ STOVE SDK 4.0.0 은 Xcode 27.1 이상 빌드가 필수예요. Podfile 의 post_install 블록과 모든 타깃의 Deployment Target 15.0 설정이 함께 필요해요. 자세한 내용은 iOS — Xcode 27.1 이상 빌드 환경을 확인해 주세요.
ㆍ SceneDelegate 는 iOS Native UISceneDelegate 대응 업데이트에 따라 적용해 주세요.
1) 사전 준비 — Specs 저장소 등록 (최초 1회)
STOVE SDK Pod는 internal repo에 호스팅돼요. GitLab 가입 후 로컬 CocoaPods에 저장소를 추가해요.
# 1) http://stove-developers-gitlab.sginfra.net 에 웹 회원가입 (별도 승인 절차 없음)
# 2) 터미널에서 repo 추가 (최초 1회 username/password 입력)
pod repo add Specs https://stove-developers-gitlab.sginfra.net/stove-sdk/Specs.git
GitLab 접근이 안 되시나요?
퍼블리싱 기술 담당자에게 문의해 주세요.
2) Podfile
아래 예시의 {ProjectTargetName}은 본인 Xcode 프로젝트의 main target 이름으로 바꿔 주세요.
source 'http://stove-developers-gitlab.sginfra.net/stove-sdk/Specs.git'
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '15.0'
target '{ProjectTargetName}' do
# 핵심 (인증 · 인증 UI · 뷰 · 로그 통합)
pod 'Stove', '4.0.0'
# 인증 Provider (Apple · Facebook · Google · Naver · Line · Steam 통합)
pod 'StoveProviders', '4.0.0'
# 인앱결제 (StoreKit 2)
pod 'StoveIAP2', '4.0.0'
# 푸시
pod 'StovePush', '4.0.0'
# 게임 로그 — 게임 로그를 쓰는 경우만
# pod 'StoveGameLog', '4.0.0'
end
# 푸시 확장 (Notification Service Extension) — 별도 target
target 'NotificationServiceExtension' do
pod 'StovePushExtension', '4.0.0'
end
# Xcode 27+ requires IPHONEOS_DEPLOYMENT_TARGET >= 15.0.
# Third-party dependency pods (Facebook, Google, Naver, etc.) still declare lower targets in their podspecs.
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
if config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'].to_f < 15.0
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
end
end
end
end
STOVE pod은 모두 4.0.0 으로 맞춰요
ㆍ 4.0.0 pod과 3.x pod은 함께 쓸 수 없어요. 일부 pod만 4.0.0 으로 바꾸지 마세요.
ㆍ Podfile에 SGS로 시작하는 2.9.x pod이 남아 있으면 안 돼요.
ㆍ SGSGamingServices는 3.0.0 에서 제거되었어요. 의존성에서 빼기만 하면 돼요. GPG User ID 기능은 StoveProviders에 들어 있어요.
ㆍ 전체 매핑은 3.0.0 업그레이드 안내를 참고해 주세요.
설치/업데이트 후 생성된 .xcworkspace로 빌드해요.
pod install
# 또는
pod update
iOS — Xcode 27.1 이상 빌드 환경
STOVE SDK 4.0.0 은 Xcode 27.1 이상에서 빌드해 주세요
ㆍ 4.0.0 은 Xcode 27.1 · iOS 27.1 SDK 빌드 환경을 기준으로 제공돼요.
ㆍ Xcode 27.1 이상에서는 SceneDelegate 적용과 Deployment Target 15.0 이상 설정이 필수예요. SceneDelegate 는 iOS Native · Unity · Unreal UISceneDelegate 대응 업데이트를 확인해 주세요.
Xcode 27.1 이상은 iOS Deployment Target 이 15.0 미만인 타깃을 빌드 오류로 처리해요. 앱 타깃뿐 아니라 NotificationServiceExtension 등 프로젝트에 포함된 모든 타깃을 [Target] → [Build Settings] → [iOS Deployment Target]에서 15.0 이상으로 설정해요.
프로젝트 타깃을 모두 15.0 으로 맞춰도 아래와 같은 빌드 오류가 날 수 있어요. StoveProviders와 함께 설치되는 서드파티 pod(Google · Facebook · Naver 로그인 라이브러리 등)이 podspec 에 15.0 보다 낮은 최소 iOS 버전을 선언하고 있고, CocoaPods 가 이 값으로 Pods 타깃을 만들기 때문이에요.
The iOS Simulator deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 12.0, but the range of supported deployment target versions is 15.0 to 27.1.x.
위 Podfile 예시 끝의 post_install 블록이 15.0 미만으로 만들어진 Pods 타깃을 15.0 으로 올려 줘요. Podfile에 블록을 추가한 뒤 아래 절차로 pod 을 다시 설치해 주세요.
이미 post_install을 쓰고 있다면
ㆍ 새 블록을 추가하지 말고 기존 post_install 블록 안에 위 반복문을 병합해 주세요. post_install은 Podfile에 하나만 선언할 수 있어요.
pod 다시 설치하기
3.x 에서 4.0.0 으로 올리거나 post_install을 추가했다면 pod 을 다시 설치해요. 로컬 Specs 저장소를 업데이트하지 않으면 4.0.0 pod 을 찾지 못할 수 있어요.
pod deintegrate
pod cache clean --all
pod repo update
# 명령어 실행 후 Podfile 이 있는 폴더(Unity 는 Xcode 빌드 폴더)의 Podfile.lock 파일을 제거해 주세요.
# 그 후에 pod install 명령어로 SDK 모듈을 다시 설치해 주세요.
pod install
빌드 환경 확인
다음 항목을 모두 확인해 주세요. SceneDelegate 적용 결과는 플랫폼별 UISceneDelegate 대응 업데이트의 적용 결과 확인을 함께 확인해 주세요.
- Xcode 27.1 이상에서 빌드 오류 없이 빌드돼요.
- 모든 Target의 iOS Deployment Target이 15.0 이상이에요. (Unity:
Unity-iPhone·UnityFramework·NotificationServiceExtension) Podfile.lock에서 STOVE SDK pod 버전이 모두4.0.0이에요.- 서드파티 pod Target의 iOS Deployment Target이 15.0 이상이에요.
3) (선택) Framework 수동 다운로드
CocoaPods를 사용할 수 없는 환경에서는 SDK 다운로드 및 설치 페이지에서 tag 이름으로 항목을 선택해 직접 다운로드한 뒤 Xcode 프로젝트에 추가하세요.
4) 인앱결제 (StoveIAP2)
3.0.0 이상의 iOS 결제 모듈은 StoreKit 2 기반 StoveIAP2예요. 결제 알림 observer를 등록한 직후 prepareTransactionListener를 호출해야 해요.
#import <StoveIAP2/StoveIAP2.h>
[[NSNotificationCenter defaultCenter] removeObserver:self
name:NSNotification.SGSPurchasesUpdatedNotification object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(updatedPurchasesNotification:)
name:NSNotification.SGSPurchasesUpdatedNotification object:nil];
[SGSIAP prepareTransactionListener]; // ⚠️ 누락 시 결제 시도 즉시 errorListener 실패
호출 시점과 Firebase Analytics
ㆍ 결제 알림 observer를 등록한 직후 호출하세요. 미호출 시 결제 시도가 사일런트로 실패해요.
ㆍ StoreKit 2 환경에서는 Firebase Analytics의 결제 자동 수집이 동작하지 않아요. iOS Firebase Analytics 결제 이벤트 연동을 참고해 리스너에서 직접 전송해 주세요.
5) Info.plist
<key>StoveEnvironment</key>
<string>live</string> <!-- live / sandbox -->
<!-- 필수 -->
<key>NSUserTrackingUsageDescription</key>
<string>로그 수집을 위해 필요합니다</string>
<!-- MemberNo 게임만: GUID 사용 안 함 -->
<key>StoveEnableGUID</key>
<false/>
<!-- 커뮤니티/고객센터 사용 시 권한 메시지 (문구는 게임에 맞게 조정) -->
<key>NSCameraUsageDescription</key>
<string>커뮤니티 게시글/문의 시 사진·동영상 촬영에 사용됩니다</string>
<key>NSMicrophoneUsageDescription</key>
<string>음성이 포함된 동영상 촬영에 사용됩니다</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>기존 사진·동영상 첨부에 사용됩니다</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>사진·동영상을 디바이스에 저장하기 위해 사용됩니다</string>
<!-- 스토브 앱간 인증 — 미설정 시 인증 실패 -->
<key>LSApplicationQueriesSchemes</key>
<array>
<string>mstove</string>
</array>
<!-- URL Schemes — 외부 앱(Google/Apple/Naver/Line 등) 복귀에 사용 -->
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLSchemes</key>
<array>
<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
</array>
</dict>
</array>
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
6) Xcode Capabilities (.entitlements)
.entitlements 파일을 직접 편집하거나, Xcode → Signing & Capabilities → + Capability로 UI에서 토글해도 같은 결과예요.
<!-- APNS 푸시 사용 시 -->
<key>aps-environment</key>
<string>production</string>
<!-- StoveSDK 필수 — 미설정 시 토큰 저장 실패 -->
<key>keychain-access-groups</key>
<array>
<string>$(AppIdentifierPrefix)com.stove.globaldata</string>
</array>
<!-- 애플 로그인 사용 시 -->
<key>com.apple.developer.applesignin</key>
<array>
<string>Default</string>
</array>
<!-- 푸시 확장(Notification Service Extension) 사용 시 -->
<key>com.apple.security.application-groups</key>
<array>
<string>group.com.stove.sdk</string>
</array>
7) Build Settings — Search Paths
Xcode 버전에 따라 분기해서 설정해요. 미설정 시 Swift 런타임 링크 또는 dylib not found 오류가 발생해요.
Library Search Paths — Xcode → Build Settings → Search Paths
$(SDKROOT)/usr/lib/swift
$(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)
$(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)
Xcode 26.0.x 사용 시 추가 경로$(TOOLCHAIN_DIR)가 Metal cryptex 경로로 잘못 resolve되는 버그가 있어요(26.2에서 수정됨). 26.0.x 환경에서는 아래 경로를 추가하세요.$(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/$(PLATFORM_NAME)
Runpath Search Paths — Xcode → Build Settings → Linking (Xcode 16/26 공통, 아래 순서를 반드시 지켜서 추가)
/usr/lib/swift
$(inherited)
@executable_path/Frameworks
@loader_path/Frameworks
8) AppDelegate — Provider 로그인 위임 (필수)
Google/Apple/Facebook/Naver/Line OAuth 콜백이 SDK에 도달하려면 openURL을 위임해야 해요. 미설정 시 외부 로그인 자체가 실패해요.
#import <Stove/Stove.h> // Swift: import Stove
- (BOOL)application:(UIApplication *)app
openURL:(NSURL *)url
options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options
{
return [SGSApplicationDelegate application:app openURL:url options:options];
}
PC SDK
PC 빌드는 Mobile SDK와 별도의 패키지를 사용해요. 아래 3개 환경 중 게임에서 사용하는 엔진에 맞는 절차를 따라 주세요.
PCSDK3는 Windows 64bit 환경을 공식 지원해요.
ㆍ 32bit 또는 Mono(Unity) 지원이 필요하면 스토브 기술지원에 문의해 주세요.
ㆍ 모듈 의존성: 모든 모듈은 BaseSDK가 선행되어야 해요. IAPSDK/ViewSDK를 사용하는 경우 WebView2Loader.dll이 함께 포함되어야 해요.
- Native C/C++ 빌드 설정 (Visual Studio)
- 솔루션 디렉터리에
StovePCSDK3디렉터리를 생성하고 다운로드한 패키지의Include/Lib/Dll폴더를 복사해요. - 프로젝트 속성에서 다음과 같이 경로를 지정해요.
- 구성 속성 > C/C++ > 일반 > 추가 포함 디렉터리:
$(SolutionDir)StovePCSDK3\Include - 구성 속성 > 링커 > 일반 > 추가 라이브러리 디렉터리:
$(SolutionDir)StovePCSDK3\Lib - 구성 속성 > 링커 > 입력 > 추가 종속성: 사용할 모듈별
*.lib(예:BaseSDK.lib)
- 구성 속성 > C/C++ > 일반 > 추가 포함 디렉터리:
- 게임 빌드 출력 폴더에 사용할 모듈의
*.dll을 복사해 주세요. - 소스 코드에서
#include "BaseSDK.h"로 헤더를 포함해요.
- 솔루션 디렉터리에
- Unity 빌드 설정
Assets/Plugins/STOVEPCSDK3하위에Managed,Native디렉터리를 생성해요.- 다운로드한 패키지의
x86_64폴더에서 Managed 플러그인(*_NET.dll)과 Native 플러그인(*.dll)을 각각 위 디렉터리에 복사해요.- Native와 Managed 플러그인은 쌍을 이루므로 함께 포함해야 해요. (예: Base만 사용 →
BaseSDK.dll+BaseSDK_NET.dll) - IAP/View 사용 시
WebView2Loader.dll도 함께 복사해요.
- Native와 Managed 플러그인은 쌍을 이루므로 함께 포함해야 해요. (예: Base만 사용 →
- 각 dll Inspector → Platform settings에서
x86_64(또는x64) 선택 후 Apply 해요. - Player Settings → Configuration → Api Compatibility Level: .NET 4.x
- 빌드 시 Architecture는 시스템에 맞춰
x86_64로 지정해요. (Unity 에디터는 x64만 지원) - 코드에서
using static Stove.PCSDK.Base;와 같이 모듈별 네임스페이스를 추가해요.
!info
향후 unitypackage 방식으로 제공 예정이에요.
ㆍ 현재는 dll을 직접 배치하는 수동 방식만 지원하지만, 차기 버전부터.unitypackage임포트 방식으로 간편하게 제공할 예정이에요.
ㆍ 적용 시점은 SDK 릴리즈 노트에서 안내드릴게요.
- Unreal 빌드 설정
- 프로젝트 루트의
ThirdParty/StovePCSDK디렉터리에 다운로드한 패키지의Include/Lib/Dll폴더를 배치해요. - 모듈 dll은
Binaries/Win64에도 함께 복사해요. (IAP/View 사용 시WebView2Loader.dll포함) - 모듈의
*.Build.cs파일에 다음과 같은 형태로 PublicIncludePaths / PublicAdditionalLibraries / RuntimeDependencies를 추가해요.
csstring ThirdPartyPath = Path.GetFullPath(Path.Combine(ModuleDirectory, "../../ThirdParty")); string StovePCSDKPath = Path.Combine(ThirdPartyPath, "StovePCSDK"); PublicIncludePaths.Add(Path.Combine(StovePCSDKPath, "Include")); string[] SDKNameList = { "BaseSDK", "IAPSDK", "ViewSDK" }; foreach(string SDKName in SDKNameList) { PublicAdditionalLibraries.Add(Path.Combine(StovePCSDKPath, "Lib", "x64", SDKName + ".lib")); RuntimeDependencies.Add( Path.Combine("$(BinaryOutputDir)", SDKName + ".dll"), Path.Combine(StovePCSDKPath, "Dll", "x64", SDKName + ".dll")); }- 소스 코드에서
#include "BaseSDK.h"로 헤더를 포함해요.
- 프로젝트 루트의
PCSDK3 모듈 초기화·정리 흐름은 SDK 기본 연동 가이드를 따라 주세요.
ㆍ Base SDK 초기화 후 다른 모듈을 초기화하고, 정리 시에는 역순으로 진행해야 해요.
ㆍ 로그는 C:\Users\{유저명}\AppData\Local\STOVEPCSDK3{Env}\logs\{GameID} 경로에 모듈별로 쌓여요.
SDK Config 설정
SDK Config는 SDK 동작에 필요한 설정값을 등록·관리하는 시스템이에요. SDK v2.x에서 제공하며, 파트너스를 통해 등록·관리해요.
SDK Config 특징
- SDK 기본 설정값 및 UI 노출 옵션, 플랫폼 URL 설정값을 관리해요.
- 클라이언트나 서버 변경 없이 서비스 설정값을 변경할 수 있어요.
- 국가별, 마켓별(패키지명 기준) 설정이 가능해 지역별 운영이 유연해요.
SDK Config 미등록 시 SDK init 실패
ㆍ SDK Config는 패키지별 / 클라이언트 버전별로 반드시 등록해야 해요. 등록되지 않은 버전은 SDK init이 실패해 게임 접속이 불가능해요.
ㆍ 버전 업데이트 시에도 Config 세팅 작업을 함께 진행해 주세요.
등록 위치
[파트너스 > GM > SDK Config 설정] 에서 등록·관리해요. 환경별로 별도 등록이 필요해요.
| 환경 | 접속 경로 |
|---|---|
| Sandbox | partners.gate8.com > GM > SDK Config 설정 |
| Live | partners.onstove.com > GM > SDK Config 설정 |
주요 등록 항목
| 항목 | 필수 여부 | 설명 |
|---|---|---|
| 패키지 / 클라이언트 버전 | 필수 | 패키지명 + 클라이언트 버전 단위로 Config 등록 |
| App ID / Client ID | 필수 | 스토브 플랫폼이 게임을 식별하는 키값 |
| 기본 정책 설정 | 필수 | 접속국가 GDS 설정, 약관 정책, 본인인증 정책 등 |
| 기능별 모듈 설정 | 선택 | 팝업, 푸시, 인앱 결제, 캐릭터, 기기 등록 등 사용 기능별 옵션 |
| UI / 노출 옵션 | 선택 | 로그인 UI Provider 노출 순서, 약관 동의 UI 옵션 등 |
iOS Native UISceneDelegate 대응 업데이트
Native iOS SceneDelegate 연동
2027년 4월 이전까지 SceneDelegate 적용을 완료해 주세요
ㆍ 2027년 4월부터 App Store에 제출하는 앱은 Xcode 27 · iOS 27 SDK로 빌드해야 하고, 이 환경에서는 UIScene 기반 라이프사이클(SceneDelegate) 적용이 필수예요.
ㆍ SDK 3.0.0은 SceneDelegate를 적용하지 않아도 지금 바로 사용할 수 있어요. 다만 2027년 4월 이전까지는 아래 가이드에 따라 SceneDelegate를 적용해야 해요.
ㆍ 프로젝트 구조나 일정으로 인해 당장 SceneDelegate를 적용하기 어렵다면 개발팀에 문의해 주세요. 프로젝트 상황에 맞는 개별 가이드로 도와드릴게요.
Xcode 27에서 iOS 27 SDK를 사용해 빌드한 앱은 UIScene 기반 라이프사이클을 적용해야 해요. STOVE 앱 간 인증 후 게임으로 돌아오는 URL callback을 처리하려면 SceneDelegate 연동도 필요해요.
STOVE SDK 버전
ㆍ 이 가이드는 STOVE SDK 버전에 상관 없어요.
문제 현상
Apple 플랫폼 정책상 SceneDelegate(UIScene 라이프사이클) 지원은 iOS 26까지는 선택 사항이지만, iOS 27부터는 필수로 전환될 예정이에요.
Xcode 27에서 iOS 27 SDK를 사용해 빌드한 앱이 UIScene 기반 라이프사이클을 적용하지 않으면 앱을 실행할 수 없어요. 자세한 내용은 Apple 마켓 정책을 참고해 주세요.
기존 가이드에 따라 UIScene을 적용했더라도 앱 간 인증 응답값을 SceneDelegate에 전달하지 않으면 인증 callback이 동작하지 않을 수 있어요.
적용 방식
SceneDelegate에서 받은 URL callback을 기존 AppDelegate의 URL 처리 경로로 전달해요.
SceneDelegate
→ AppDelegate
→ SGSApplicationDelegate.application:openURL:options:
SceneDelegate는 기존 AppDelegate 이벤트 처리 경로를 유지해요. 이를 통해 다음 항목을 함께 유지할 수 있어요.
- 기존 게임의 STOVE SDK 연동 코드
- 게임 엔진의 lifecycle 처리
- STOVE 이외의 다른 SDK 처리
SceneDelegate에서 SGSApplicationDelegate를 직접 호출하지 마세요. 이 가이드에서는 모든 SDK 버전이 AppDelegate를 통해 인증 callback을 전달해요.
공통 적용 사항
1. SceneDelegate 추가
프로젝트에 UIWindowSceneDelegate를 구현한 SceneDelegate를 추가해요.
기존 SceneDelegate가 있다면 새 클래스를 추가하지 말고 기존 구현에 필요한 코드를 병합해 주세요.
// SceneDelegate.h
#import <UIKit/UIKit.h>
@interface SceneDelegate : UIResponder <UIWindowSceneDelegate>
@property (strong, nonatomic) UIWindow *window;
@end
2. Info.plist 설정
Info.plist에 Scene Manifest를 추가해요.
<!-- 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>SceneDelegate</string>
</dict>
</array>
</dict>
</dict>
SceneDelegate 수정 사항
Scene 기반 lifecycle에서는 window 연결과 URL callback 수신을 SceneDelegate에서 처리해요. 기존 AppDelegate 구현을 프로젝트 구조에 맞게 SceneDelegate와 연결해 주세요.
1. Scene 연결 및 window 관리
scene:willConnectToSession:options:는 Scene이 앱에 연결될 때 호출돼요. SceneDelegate를 적용하면 기존 AppDelegate에서 담당하던 window 관리도 이 메서드를 기준으로 처리해요.- 사용 엔진 환경에 맞게 기존 window, root view controller 및 게임 엔진 초기화가 이 메서드에서 실행되도록 기존 구현을 이동하거나 호출하고, window를 전달된
UIWindowScene에 연결해 주세요. - 앱이 종료된 상태에서 Custom URL Scheme으로 실행되면 URL callback은
connectionOptions.URLContexts로 전달돼요. window와 게임 엔진 및 SDK 초기화가 완료된 후 기존 AppDelegate URL 처리 경로로 전달해 주세요.
// SceneDelegate.m
- (void)scene:(UIScene *)scene
willConnectToSession:(UISceneSession *)session
options:(UISceneConnectionOptions *)connectionOptions
API_AVAILABLE(ios(13.0))
{
if (![scene isKindOfClass:UIWindowScene.class]) {
return;
}
UIWindowScene *windowScene = (UIWindowScene *)scene;
// 프로젝트별 구현
// 1. 기존 window를 windowScene에 연결해요.
// 2. 기존 root view controller와 게임 엔진을 초기화해요.
// 3. 실제 사용하는 window를 self.window에도 연결해요.
// window와 SDK 초기화가 완료된 후 URL callback을 전달해요.
[self scene:scene
openURLContexts:connectionOptions.URLContexts];
}
게임 엔진 또는 STOVE SDK 초기화 전에 URL을 전달하면 인증 요청을 처리할 객체가 준비되지 않았을 수 있어요.
2. 실행 중 전달된 URL callback
// SceneDelegate.m
- (void)scene:(UIScene *)scene
openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
API_AVAILABLE(ios(13.0))
{
id<UIApplicationDelegate> appDelegate =
UIApplication.sharedApplication.delegate;
for (UIOpenURLContext *context in URLContexts) {
NSMutableDictionary<UIApplicationOpenURLOptionsKey, id> *options =
[NSMutableDictionary dictionary];
if (context.options.sourceApplication != nil) {
options[UIApplicationOpenURLOptionsSourceApplicationKey] =
context.options.sourceApplication;
}
if (context.options.annotation != nil) {
options[UIApplicationOpenURLOptionsAnnotationKey] =
context.options.annotation;
}
options[UIApplicationOpenURLOptionsOpenInPlaceKey] =
@(context.options.openInPlace);
if ([appDelegate respondsToSelector:
@selector(application:openURL:options:)]) {
[appDelegate application:UIApplication.sharedApplication
openURL:context.URL
options:options];
}
}
}
기존 AppDelegate에서는 현재 사용 중인 STOVE 연동을 그대로 유지해요.
// AppDelegate.m
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options
{
return [SGSApplicationDelegate application:application
openURL:url
options:options];
}
3. App lifecycle 전달
게임 엔진에서 기존 AppDelegate lifecycle 처리를 사용하고 있다면 SceneDelegate의 lifecycle 이벤트를 AppDelegate로 전달해요.
// SceneDelegate.m
@interface SceneDelegate ()
@property (nonatomic, assign) BOOL sceneHasEnteredBackground;
@end
@implementation SceneDelegate
- (void)sceneDidBecomeActive:(UIScene *)scene
{
id<UIApplicationDelegate> appDelegate =
UIApplication.sharedApplication.delegate;
if ([appDelegate respondsToSelector:
@selector(applicationDidBecomeActive:)]) {
[appDelegate applicationDidBecomeActive:
UIApplication.sharedApplication];
}
}
- (void)sceneWillResignActive:(UIScene *)scene
{
id<UIApplicationDelegate> appDelegate =
UIApplication.sharedApplication.delegate;
if ([appDelegate respondsToSelector:
@selector(applicationWillResignActive:)]) {
[appDelegate applicationWillResignActive:
UIApplication.sharedApplication];
}
}
- (void)sceneDidEnterBackground:(UIScene *)scene
{
self.sceneHasEnteredBackground = YES;
id<UIApplicationDelegate> appDelegate =
UIApplication.sharedApplication.delegate;
if ([appDelegate respondsToSelector:
@selector(applicationDidEnterBackground:)]) {
[appDelegate applicationDidEnterBackground:
UIApplication.sharedApplication];
}
}
- (void)sceneWillEnterForeground:(UIScene *)scene
{
// 최초 Scene 연결에는 기존 앱 생명주기에 없던 foreground 복귀를 중복 전달하지 않아요.
if (!self.sceneHasEnteredBackground) {
return;
}
self.sceneHasEnteredBackground = NO;
id<UIApplicationDelegate> appDelegate =
UIApplication.sharedApplication.delegate;
if ([appDelegate respondsToSelector:
@selector(applicationWillEnterForeground:)]) {
[appDelegate applicationWillEnterForeground:
UIApplication.sharedApplication];
}
}
@end
적용 결과 확인
다음 항목을 모두 확인해 주세요.
- 최종 앱의 바이너리 내부
Info.plist에UIApplicationSceneManifest가 있어요.UISceneDelegateClassName에 실제 SceneDelegate 클래스가 설정되어 있어요.
- SceneDelegate 구현 파일이 앱 Target의 Compile Sources에 포함되어 있어요.
- 앱을 백그라운드로 전환한 후 다시 돌아왔을 때 게임이 정상 동작해요.
- 서드파티 앱 간 인증 후 게임으로 돌아오면 인증이 완료돼요.
- 앱 실행 중에 받은 URL callback이 정상 처리돼요.
- 앱 종료 상태의 URL callback을 지원하는 경우 기존 URL 처리 경로로 정상 전달돼요.
- STOVE 앱 간 인증 URL callback이 정상 처리돼요.
iOS Unity UISceneDelegate 대응 업데이트
2027년 4월 이전까지 SceneDelegate 적용을 완료해 주세요
ㆍ 2027년 4월부터 App Store에 제출하는 앱은 Xcode 27 · iOS 27 SDK로 빌드해야 하고, 이 환경에서는 UIScene 기반 라이프사이클(SceneDelegate) 적용이 필수예요.
ㆍ SDK 3.0.0은 SceneDelegate를 적용하지 않아도 지금 바로 사용할 수 있어요. 다만 2027년 4월 이전까지는 아래 가이드에 따라 SceneDelegate를 적용해야 해요.
ㆍ 프로젝트 구조나 일정으로 인해 당장 SceneDelegate를 적용하기 어렵다면 개발팀에 문의해 주세요. 프로젝트 상황에 맞는 개별 가이드로 도와드릴게요.
Xcode 27에서 iOS 27 SDK를 사용해 빌드한 앱은 UIScene 기반 라이프사이클을 적용해야 해요. STOVE 앱 간 인증 후 게임으로 돌아오는 URL callback을 처리하려면 Unity 버전과 STOVE SDK 버전에 맞는 SceneDelegate 연동도 필요해요.
STOVE SDK 버전
ㆍ STOVE SDK 3.0.0 이상은 SceneDelegate에서 전달된 Unity URL 이벤트를 자동으로 처리해요.
ㆍ STOVE SDK 3.0.0 미만을 유지해야 한다면 이 가이드의 SDK 버전별 추가 적용에서 AppController 연동 코드를 추가해 주세요.
ㆍ 가능하면 SceneDelegate 연동이 포함된 STOVE SDK 3.0.0 이상으로 업데이트하는 것을 권장해요.
문제 현상
Apple 플랫폼 정책상 SceneDelegate(UIScene 라이프사이클) 지원은 iOS 26까지는 선택 사항이지만, iOS 27부터는 필수로 전환될 예정이에요.
Xcode 27에서 iOS 27 SDK를 사용해 빌드한 앱이 UIScene 기반 라이프사이클을 적용하지 않으면 앱을 실행할 수 없어요. 자세한 내용은 Apple 마켓 정책을 참고해 주세요.
기존 가이드에 따라 UIScene을 적용했더라도 앱 간 인증 응답값을 SceneDelegate에서 STOVE SDK의 기존 URL 처리 경로로 전달하지 않으면 인증 callback이 동작하지 않을 수 있어요.
참고
- Unity Discussions — Apple: Update your Editor to receive UIScene lifecycle support
- Apple Developer — TN3187: Migrating to the UIKit scene-based life cycle
영향 범위
| 영역 | 관련 AppDelegate 콜백 | 증상 |
|---|---|---|
| 소셜 로그인(Auth) | application(_:open:options:) | Google · Facebook · Naver · LINE 등 3rd party 로그인 후 앱으로 돌아오는 리다이렉트 URL을 SDK가 수신하지 못해 로그인이 완료되지 않아요. |
Unity 엔진 버전별 적용 방법
| Unity 버전 | 적용 방법 |
|---|---|
| Unity 2022.3.72f1 이상 | Unity가 생성한 UnityScene과 Scene Manifest를 사용해요. |
| Unity 2022.3.72f1 미만 | StoveUnitySceneDelegate 파일과 Scene Manifest를 추가해요. |
Unity 2022.3.72f1 이상
권장 Unity 버전
ㆍ Unity 2022.3.76f1 이상 사용을 권장해요.
ㆍ Unity 2022.3.72f1부터 SceneDelegate를 지원하지만, 2022.3.76f1 미만 버전에는 URL 처리(딥링크)와 관련된 Unity 이슈가 있어요.
Unity가 생성한 UnityScene과 Scene Manifest를 그대로 사용해요. SceneDelegate 구성을 완료한 후 아래의 STOVE SDK 버전별 추가 적용을 확인해 주세요.
Unity가 생성한 설정을 수정하지 마세요
ㆍ 게임에서 별도의 SceneDelegate를 추가하지 마세요.
ㆍ 빌드 후 생성된 UnityScene.mm 또는 Info.plist를 수정하지 마세요.
ㆍ 이전에 **iOS Unity UISceneDelegate 임시 조치**를 적용한 적이 있다면 적용을 되돌려야 해요.
Unity 2022.3.72f1 미만
Unity 공식 UIScene 지원 대상이 아니에요
ㆍ STOVE는 Unity가 생성한 기존 window를 UIWindowScene에 연결하고 UIScene 기반 라이프사이클을 UnityAppController로 전달하는 호환 구현을 제공해요.
ㆍ 이 구현은 Unity 공식 가이드가 아니라 STOVE 검증을 기반으로 작성된 가이드예요.
Unity가 SceneDelegate를 생성하지 않으므로 Xcode 프로젝트를 생성한 후 아래 항목을 적용해 주세요.
1. SceneDelegate 파일 추가
StoveUnitySceneDelegate.h와 StoveUnitySceneDelegate.mm 파일을 Unity 프로젝트에 추가해요.
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];
}
}
- (void)scene:(UIScene *)scene
continueUserActivity:(NSUserActivity *)userActivity
{
// Universal Link 처리가 필요하면 프로젝트 정책에 맞게 추가해요.
}
- (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
SceneDelegate 구현 시 주의 사항
ㆍ SceneDelegate에서 SGSApplicationDelegate를 직접 호출하거나 별도의 StoveUnityAppDelegateListener를 추가하지 마세요. 동일한 URL이 중복 처리될 수 있어요.
ㆍ SceneDelegate에서 Unity를 다시 초기화하거나 새로운 UIWindow를 생성하지 마세요.
ㆍ Scene configuration 선택은 아래의 STOVE SDK 버전별 추가 적용에 따라 AppController에서 처리해요.
2. Info.plist 설정
Info.plist에 아래 Scene Manifest를 추가해요.
<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>
기존 설정에 병합해 주세요
ㆍ UISceneConfigurationName의 Default Configuration은 AppController가 선택하는 configuration 이름과 같아야 해요.
ㆍ 기존 SceneDelegate 또는 UIApplicationSceneManifest가 있다면 새로 추가하거나 전체 값을 교체하지 말고 위 내용을 기존 구현에 병합해 주세요.
STOVE SDK 버전별 추가 적용
Unity 버전에 맞는 SceneDelegate 구성을 완료한 후 사용 중인 STOVE SDK 버전에 해당하는 내용을 적용해요.
추가 작업은 필요하지 않아요. Unity가 전달한 URL callback을 STOVE SDK의 StoveSDKAppController가 자동으로 처리해요.
적용 결과 확인
생성된 Xcode 프로젝트와 실제 기기에서 다음 항목을 확인해요.
- 최종 앱의 바이너리 내부
Info.plist에UIApplicationSceneManifest가 있어요.UISceneDelegateClassName에 실제 SceneDelegate 클래스가 설정되어 있어요.
- Unity 2022.3.72f1 이상에서는 Unity가 생성한 SceneDelegate 설정을 유지하고 있어요.
- Unity 2022.3.72f1 미만에서는
StoveUnitySceneDelegate.mm이 UnityFramework Target의 Compile Sources에 포함되어 있어요. - 앱 실행 시 Unity 화면과 입력이 정상적으로 동작해요.
- 앱을 백그라운드에서 포그라운드로 전환한 후에도 정상적으로 동작해요.
- 앱 실행 중 STOVE 앱 간 인증 후 게임으로 돌아오면 인증이 완료돼요.
- 앱 종료 상태에서 인증 URL로 실행하면 callback이 한 번만 전달돼요.
- Scene lifecycle을 사용하지 않는 환경에서도 기존 AppDelegate URL callback이 정상 동작해요.
iOS Unity UISceneDelegate 임시 조치
임시 조치 적용 전 확인해 주세요
ㆍ 이 방법은 SceneDelegate 연동을 적용하기 어려운 게임사를 위해 UIScene lifecycle을 사용하지 않도록 하는 임시 조치예요.
ㆍ Apple은 iOS 27 SDK로 빌드하는 앱에 UIScene lifecycle 적용을 요구하며, 적용하지 않은 앱은 실행되지 않아요.
ㆍ Xcode 27과 iOS 27 SDK가 App Store Connect의 최소 제출 요건으로 적용된 이후에는 이 임시 조치를 사용한 앱을 제출할 수 없으므로 제한적으로 적용해 주세요.
확인 방법
프로젝트에 아래 설정이 적용되어 있는지 확인해요.
- Xcode에서
Info.plist파일을 열어요. Application Scene Manifest(raw key:UIApplicationSceneManifest)와 하위Scene Configuration(raw key:UISceneConfigurations)이 존재하는지 확인해요.- 소스 코드로 확인하려면
Info.plist를 마우스 우클릭한 후 Open As > Source Code를 선택해요.
<key>UIApplicationSceneManifest</key>
<dict>
<key>UIApplicationSupportsMultipleScenes</key>
<false/>
<key>UISceneConfigurations</key>
<dict/>
</dict>
조치 방법
UIApplicationSceneManifest 키와 하위 설정을 Info.plist에서 삭제해요. 삭제하면 iOS가 다시 AppDelegate lifecycle을 사용해요.
빌드 시 자동으로 다시 삽입될 수 있어요
ㆍ Unity 프로젝트는 Xcode 프로젝트를 다시 생성할 때 해당 설정을 자동으로 삽입할 수 있어요.
ㆍ 매 빌드 후 Info.plist를 확인하거나 빌드 후처리 스크립트(PostProcessBuild)로 해당 키를 제거하는 방식을 권장해요.
iOS Unity AppController 충돌 대응
ㆍ STOVE SDK의 Unity iOS 플러그인은 IMPL_APP_CONTROLLER_SUBCLASS 매크로를 사용해 StoveSDKAppController를 Unity의 AppController로 등록해요. 따라서 게임에서 AppDelegate를 직접 수정하지 않아도 로그인 URL callback과 Push 등 STOVE SDK 기능을 처리할 수 있어요.
ㆍ 외부 플러그인에서 같은 매크로를 사용하면 여러 AppController가 중복으로 등록돼요.
Unity에서는 하나의 AppController만 활성화되므로 STOVE SDK 또는 외부 플러그인 중 한쪽 기능이 동작하지 않을 수 있어요.
외부 플러그인과 STOVE SDK의 AppController를 병합해주세요.
ㆍ IMPL_APP_CONTROLLER_SUBCLASS는 클래스가 로드될 때 Unity의 AppController 클래스 정보를 변경해요.
ㆍ 여러 클래스의 로드 순서는 보장되지 않으므로 파일 순서나 빌드 순서를 조정하는 방법으로는 안정적으로 해결할 수 없어요.
ㆍ 여러 플러그인의 delegate 메서드를 하나의 AppController로 통합해 관리해야 해요.
적용 대상
| 프로젝트 상태 | 적용 방법 |
|---|---|
| STOVE SDK만 매크로를 선언한 경우 | 추가 작업이 필요하지 않아요. |
| 외부 플러그인도 매크로를 선언한 경우 | 통합 AppController를 생성하고 각 플러그인의 delegate 메서드를 병합해요. |
| STOVE SDK 2.9.x에서 통합 AppController를 사용 중인 경우 | STOVE SDK 3.0.0의 UIScene 라이프사이클 처리 코드를 통합 AppController에 추가해요. |
충돌 여부 확인
Unity 프로젝트의 Assets 폴더에서 아래 매크로를 사용하는지 검색해요.
IMPL_APP_CONTROLLER_SUBCLASS(
- 활성화된 매크로 선언이
StoveSDKAppController.mm에만 있으면 추가 작업이 필요하지 않아요. - 서로 다른 AppController 클래스에서 두 개 이상 선언되어 있으면 아래 통합 절차를 적용해요.
- 외부 플러그인이 컴파일된 라이브러리 형태로 제공되면 소스 검색 결과에 매크로가 나타나지 않을 수 있어요. 플러그인 개발 가이드에서 별도의 UnityAppController를 사용하는지 확인해 주세요.
통합 적용 방법 (STOVE SDK 3.0.0 신규 적용)
1. GameAppController.mm 파일 추가
Unity 프로젝트의 Assets 아래에 GameAppController.mm 파일을 추가해요.
하위 폴더 위치는 자유롭게 지정할 수 있지만, Unity가 iOS 네이티브 플러그인으로 인식할 수 있도록 경로에 Plugins/iOS가 포함되어야 해요.
Assets/Game/Plugins/iOS/GameAppController.mm
Assets/Plugins/iOS/GameAppController.mm
STOVE SDK 3.0.0 이상 기준 예제예요
ㆍ 아래 코드는 STOVE SDK의 로그인 URL callback, Push, foreground notification, UIScene configuration 처리를 포함해요.
ㆍ 외부 플러그인에서 AppController에 구현한 초기화 및 delegate 메서드는 주석으로 표시된 위치에 병합해 주세요.
STOVE SDK 3.0.0 미만은 병합 방법이 달라요
ㆍ 사용 중인 STOVE 플러그인의 StoveSDKAppController.mm 파일을 기준으로 메서드를 병합해 주세요.
ㆍ 3.0.0 예제에 포함된 UIScene 관련 메서드는 추가하지 말고, 현재 SDK에 구현된 메서드와 외부 플러그인 코드만 통합해 주세요.
#import "UnityAppController.h"
#import "AppDelegateListener.h"
#import <StovePush/StovePush.h>
#import <Stove/Stove.h>
// 사용하는 외부 플러그인의 헤더를 추가해요.
@interface GameAppController :
UnityAppController <SGSPushNotificationCenterDelegate, AppDelegateListener>
@end
@implementation GameAppController
- (instancetype)init
{
self = [super init];
if (self != nil)
{
UnityRegisterAppDelegateListener(self);
}
return self;
}
- (void)onOpenURL:(NSNotification *)notification
{
NSDictionary *userInfo = notification.userInfo;
id urlValue = userInfo[@"url"];
if (![urlValue isKindOfClass:NSURL.class])
{
return;
}
NSURL *url = (NSURL *)urlValue;
void (^handleURL)(void) = ^{
NSMutableDictionary<UIApplicationOpenURLOptionsKey, id> *options =
[NSMutableDictionary dictionary];
id sourceApplication = userInfo[@"sourceApplication"];
if (sourceApplication != nil &&
sourceApplication != NSNull.null)
{
options[UIApplicationOpenURLOptionsSourceApplicationKey] =
sourceApplication;
}
id annotation = userInfo[@"annotation"];
if (annotation != nil &&
annotation != NSNull.null)
{
options[UIApplicationOpenURLOptionsAnnotationKey] =
annotation;
}
options[UIApplicationOpenURLOptionsOpenInPlaceKey] = @NO;
[SGSApplicationDelegate
application:UIApplication.sharedApplication
openURL:url
options:options];
};
if (NSThread.isMainThread)
{
handleURL();
}
else
{
dispatch_async(
dispatch_get_main_queue(),
handleURL);
}
}
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
// 외부 플러그인의 앱 시작 초기화 코드를 병합해요.
[[SGSPushNotificationCenter currentPushNotificationCenter]
setDelegate:self];
return [super application:application
didFinishLaunchingWithOptions:launchOptions];
}
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
options:
(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options
{
// 외부 플러그인의 URL 처리 코드가 있다면 함께 호출해요.
return [SGSApplicationDelegate
application:application
openURL:url
options:options];
}
- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:
(NSData *)deviceToken
{
[[SGSPushNotificationCenter currentPushNotificationCenter]
application:application
didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
// 외부 플러그인의 device token 처리 코드를 병합해요.
}
- (void)application:(UIApplication *)application
didReceiveRemoteNotification:(NSDictionary *)userInfo
fetchCompletionHandler:
(void (^)(UIBackgroundFetchResult result))completionHandler
{
[[SGSPushNotificationCenter currentPushNotificationCenter]
application:application
didReceiveRemoteNotification:userInfo
fetchCompletionHandler:completionHandler];
// 같은 completionHandler를 여러 번 호출하지 않도록 주의해요.
}
- (UISceneConfiguration *)application:(UIApplication *)application
configurationForConnectingSceneSession:(UISceneSession *)session
options:
(UISceneConnectionOptions *)options
{
return [UISceneConfiguration
configurationWithName:@"Default Configuration"
sessionRole:session.role];
}
- (void)willPresentNotification:(UNNotification *)notification
withCompletionHandler:
(void (^)(UNNotificationPresentationOptions options))
completionHandler
{
UNNotificationPresentationOptions options = 0;
NSNumber *foregroundPushSettings =
[[NSBundle mainBundle]
objectForInfoDictionaryKey:@"ForegroundPushEnabled"];
BOOL foregroundPushEnabled =
(foregroundPushSettings == nil)
? YES
: foregroundPushSettings.boolValue;
NSNumber *pushListOptionEnabled =
[[NSBundle mainBundle]
objectForInfoDictionaryKey:@"EnablePushListOptions"];
BOOL enablePushListOptions =
(pushListOptionEnabled == nil)
? YES
: pushListOptionEnabled.boolValue;
if (foregroundPushEnabled)
{
options |= UNNotificationPresentationOptionSound;
if (@available(iOS 14.0, *))
{
options |= UNNotificationPresentationOptionBanner;
if (enablePushListOptions)
{
options |= UNNotificationPresentationOptionList;
}
}
else
{
options |= UNNotificationPresentationOptionAlert;
}
}
completionHandler(options);
}
// **외부 플러그인이 다른 delegate 메서드를 선언하고 있다면 이 위치에 병합해요.**
@end
IMPL_APP_CONTROLLER_SUBCLASS(GameAppController)
외부 플러그인의 반환값과 completionHandler를 확인해 주세요
ㆍ 동일한 delegate 메서드를 여러 플러그인이 구현하면 각 처리 결과를 하나의 반환값으로 병합해야 해요.
2. 기존 AppController의 매크로 비활성화
통합 AppController를 추가한 후 기존 AppController 파일에서 아래 매크로 선언을 주석 처리하거나 제거해요.
- STOVE SDK:
Assets/Stove/Plugins/iOS/StoveSDKAppController.mm - 외부 플러그인: 해당 플러그인이 UnityAppController를 구현한
.m또는.mm파일
// STOVE SDK AppController에서 비활성화
// IMPL_APP_CONTROLLER_SUBCLASS(StoveSDKAppController)
// 외부 플러그인 AppController에서도 비활성화
// IMPL_APP_CONTROLLER_SUBCLASS(ExternalSDKAppController)
활성화된 매크로는 하나만 남겨 주세요
ㆍ 병합 시 최종 프로젝트에서는 IMPL_APP_CONTROLLER_SUBCLASS(GameAppController)만 활성화되어 있어야 해요.
ㆍ 기존 클래스와 메서드 구현은 삭제하지 않아도 되지만, 해당 클래스의 매크로는 반드시 비활성화해야 해요.
ㆍ STOVE SDK 또는 외부 플러그인을 업데이트하면 수정한 매크로가 다시 활성화될 수 있으므로 업데이트 후마다 확인해 주세요.
기존 통합 AppController 업데이트 (2.x.x → 3.0.0)
변경 내용 요약
| 변경 항목 | STOVE SDK 3.0.0 적용 내용 |
|---|---|
| 모듈 import | SGSPush/SGSPush.h, SGSAuth/SGSAuth.h 대신 StovePush/StovePush.h, Stove/Stove.h를 사용해요. |
| AppDelegateListener | AppDelegateListener.h를 import하고 프로토콜을 채택한 뒤 init에서 UnityRegisterAppDelegateListener(self)를 호출해요. |
| Scene URL callback | onOpenURL:을 구현해 Scene에서 전달된 URL을 SGSApplicationDelegate로 전달해요. |
| Scene configuration | configurationForConnectingSceneSession에서 Default Configuration을 반환하는 메서드를 추가해요. |
| 기존 외부 플러그인 코드 | 기존 초기화, 딥링크, delegate 처리 코드는 유지하고 위 3.0.0 코드를 함께 병합해요. |
2.x.x 통합 파일을 수정하지 않고 사용하면 안 돼요
ㆍ AppDelegateListener와 onOpenURL:이 없으면 UIScene으로 전달된 앱 간 인증 URL을 STOVE SDK가 수신하지 못할 수 있어요.
ㆍ Scene configuration 메서드가 없으면 UIScene 연결 시 게임에서 사용하는 Default Configuration이 선택되지 않을 수 있어요.
STOVE SDK 2.x.x에서 AppController 충돌을 해결하기 위해 GameAppController.mm과 같은 통합 파일을 만들어 사용 중인 게임만 적용해요.
STOVE SDK 3.0.0에서는 기존 통합 파일을 삭제하거나 위 전체 예제로 교체하지 않고, 아래 네 항목만 기존 파일에 반영해요.
게임과 외부 플러그인 코드는 그대로 유지해 주세요
ㆍ Singular 등 외부 플러그인의 import, 초기화, 딥링크와 delegate 처리 코드는 삭제하지 않아요.
ㆍ 같은 delegate 메서드가 이미 있다면 메서드를 하나 더 만들지 말고 기존 메서드 안에 STOVE 코드를 병합해요.
ㆍ 최종 프로젝트에서 활성화된 IMPL_APP_CONTROLLER_SUBCLASS는 통합 AppController의 선언 하나만 남겨야 해요.
1. STOVE 모듈 import 교체
기존 STOVE import 두 개를 삭제하고 STOVE SDK 3.0.0 모듈로 교체해요. 외부 플러그인의 import는 유지해요.
// 삭제
#import <SGSPush/SGSPush.h>
#import <SGSAuth/SGSAuth.h>
// 추가
#import "AppDelegateListener.h"
#import <StovePush/StovePush.h>
#import <Stove/Stove.h>
2. AppDelegateListener 등록
통합 AppController에 AppDelegateListener 프로토콜을 추가해요.
@interface GameAppController :
UnityAppController <SGSPushNotificationCenterDelegate, AppDelegateListener>
@end
@implementation GameAppController 바로 아래에 init 메서드를 추가해요.
이미 init을 구현하고 있다면 기존 초기화 코드를 유지하고 UnityRegisterAppDelegateListener(self) 호출만 병합해요.
- (instancetype)init
{
self = [super init];
if (self != nil)
{
UnityRegisterAppDelegateListener(self);
}
return self;
}
3. Scene URL callback 추가
@implementation GameAppController 내부에 onOpenURL: 메서드를 추가해요. UIScene에서 받은 로그인 URL을 STOVE SDK로 전달하는 코드예요.
- (void)onOpenURL:(NSNotification *)notification
{
NSDictionary *userInfo = notification.userInfo;
id urlValue = userInfo[@"url"];
if (![urlValue isKindOfClass:NSURL.class])
{
return;
}
NSURL *url = (NSURL *)urlValue;
void (^handleURL)(void) = ^{
NSMutableDictionary<UIApplicationOpenURLOptionsKey, id> *options =
[NSMutableDictionary dictionary];
id sourceApplication = userInfo[@"sourceApplication"];
if (sourceApplication != nil &&
sourceApplication != NSNull.null)
{
options[UIApplicationOpenURLOptionsSourceApplicationKey] =
sourceApplication;
}
id annotation = userInfo[@"annotation"];
if (annotation != nil &&
annotation != NSNull.null)
{
options[UIApplicationOpenURLOptionsAnnotationKey] =
annotation;
}
options[UIApplicationOpenURLOptionsOpenInPlaceKey] = @NO;
[SGSApplicationDelegate
application:UIApplication.sharedApplication
openURL:url
options:options];
};
if (NSThread.isMainThread)
{
handleURL();
}
else
{
dispatch_async(
dispatch_get_main_queue(),
handleURL);
}
}
기존 application:openURL:options: 메서드는 삭제하지 않아요. AppDelegate 라이프사이클로 전달되는 URL을 계속 처리할 수 있도록 유지해요.
4. Scene configuration 메서드 추가
@implementation GameAppController 내부에 아래 메서드를 추가해요. 기존에 같은 메서드가 있다면 중복으로 추가하지 말고 Default Configuration을 반환하는지 확인해요.
- (UISceneConfiguration *)application:(UIApplication *)application
configurationForConnectingSceneSession:(UISceneSession *)session
options:
(UISceneConnectionOptions *)options
{
return [UISceneConfiguration
configurationWithName:@"Default Configuration"
sessionRole:session.role];
}
나머지 STOVE 코드는 변경하지 않아요
ㆍ Push device token, remote notification, foreground notification 처리 코드는 기존 구현을 유지해요.
ㆍ didFinishLaunchingWithOptions의 STOVE Push delegate 등록과 외부 플러그인 초기화 코드도 유지해요.
ㆍ 전체 코드 형태를 비교하고 싶다면 통합 적용 방법 (STOVE SDK 3.0.0 신규 적용)의 예제를 참고해 주세요.
5. 적용 결과 확인
- 빌드 오류 없이
AppDelegateListener와StovePush,Stove모듈이 import되는지 확인 - 활성화된
IMPL_APP_CONTROLLER_SUBCLASS가 통합 AppController에만 하나 있는지 확인 - 일반 실행과 알림 클릭 실행에서 Push callback이 정상적으로 전달되는지 확인
- STOVE 또는 소셜 로그인 후 게임으로 돌아왔을 때 로그인 callback이 한 번만 전달되는지 확인
- 외부 플러그인의 초기화, 딥링크와 delegate 기능이 업데이트 전과 동일하게 동작하는지 확인
iOS Unreal UISceneDelegate 대응 업데이트
2027년 4월 이전까지 SceneDelegate 적용을 완료해 주세요
ㆍ 2027년 4월부터 App Store에 제출하는 앱은 Xcode 27 · iOS 27 SDK로 빌드해야 하고, 이 환경에서는 UIScene 기반 라이프사이클(SceneDelegate) 적용이 필수예요.
ㆍ SDK 3.0.0은 SceneDelegate를 적용하지 않아도 지금 바로 사용할 수 있어요. 다만 2027년 4월 이전까지는 아래 가이드에 따라 SceneDelegate를 적용해야 해요.
ㆍ 단, 2.9.x에서 3.0.0으로 올리는 경우 8) iOS — LSSupportsOpeningDocumentsInPlace 사용 패치가 남아 있으면 외부 로그인 callback이 SDK에 전달되지 않아요. 이 가이드에 패치 원복이 포함되어 있으니 마이그레이션과 함께 적용하는 것을 권장해요.
ㆍ 프로젝트 구조나 일정으로 인해 당장 SceneDelegate를 적용하기 어렵다면 개발팀에 문의해 주세요. 프로젝트 상황에 맞는 개별 가이드로 도와드릴게요.
Xcode 27에서 iOS 27 SDK를 사용해 빌드한 앱은 UIScene 기반 라이프사이클을 적용해야 해요. STOVE 앱 간 인증 후 게임으로 돌아오는 URL callback을 처리하려면 Unreal 엔진 버전에 맞는 SceneDelegate 연동도 필요해요.
문제 현상
Apple 플랫폼 정책상 SceneDelegate(UIScene 라이프사이클) 지원은 iOS 26까지는 선택 사항이지만, iOS 27부터는 필수로 전환될 예정이에요.
Xcode 27에서 iOS 27 SDK를 사용해 빌드한 앱이 UIScene 기반 라이프사이클을 적용하지 않으면 앱을 실행할 수 없어요. 자세한 내용은 Apple 마켓 정책을 참고해 주세요.
기존 가이드에 따라 UIScene을 적용했더라도 앱 간 인증 응답값을 SceneDelegate에 전달하지 않으면 인증 callback이 동작하지 않을 수 있어요.
참고
- Unity Discussions — Apple: Update your Editor to receive UIScene lifecycle support
- Apple Developer — TN3187: Migrating to the UIKit scene-based life cycle
STOVE SDK 버전별 URL callback 처리
ㆍ STOVE SDK 3.0.0 이상은 Unreal Engine의 기본 FIOSCoreDelegates::OnOpenURL을 사용해요.
ㆍ STOVE SDK 3.0.0 미만은 기존 가이드에서 추가한 FIOSCoreDelegates::OnOpenURLwithOptions을 사용해요.
ㆍ 프로젝트에 적용된 STOVE SDK 버전에 해당하는 방법 하나만 적용해 주세요.
적용 경로 확인
Unreal Engine 5.8 이상
- STOVE SDK 3.0.0 이상
- Unreal Engine의 SceneDelegate 지원을 활성화하고 프로젝트를 다시 빌드해요.
- STOVE SDK 3.0.0 미만
- STOVE SDK 3.0.0 이상으로 업데이트하는 것을 권장해요.
- Unreal Engine 5.8 이상과 STOVE SDK 3.0.0 미만 조합은 이 가이드에서 지원하지 않아요.
Unreal Engine 5.8 미만
- STOVE SDK 3.0.0 이상
- 커스텀 엔진에 SceneDelegate와
OnOpenURL전달 경로를 추가해요.
- 커스텀 엔진에 SceneDelegate와
- STOVE SDK 3.0.0 미만
- 커스텀 엔진에 SceneDelegate와
OnOpenURLwithOptions전달 경로를 추가해요.
- 커스텀 엔진에 SceneDelegate와
URL callback 전달 경로
IOSSceneDelegate.scene:openURLContexts:
→ IOSAppDelegate.handleOpenURL:sourceApplication:annotation:
→ FIOSCoreDelegates::OnOpenURL
→ STOVE Unreal Plugin
→ SGSApplicationDelegate.application:openURL:options:
Unreal Engine 5.8 이상
1. Scene lifecycle 활성화
게임 프로젝트의 Config/DefaultEngine.ini에 다음 설정을 추가해요.
[/Script/IOSRuntimeSettings.IOSRuntimeSettings]
bUseSceneBasedLifecycle=True
2. STOVE SDK 버전 확인
추가 엔진 수정 없이 Unreal Engine의 기본 FIOSCoreDelegates::OnOpenURL 경로를 사용해요.
3. iOS target 다시 빌드
설정을 변경한 후 iOS target을 다시 빌드하고 패키징해요.
4. Info.plist 확인
최종 .app의 Info.plist에 다음 key-value가 생성되었는지 확인해요. 아래 내용은 빌드 결과를 확인하기 위한 예시이며 Info.plist를 직접 수정하지 않아요.
<!-- 최종 .app/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>IOSSceneDelegate</string>
</dict>
</array>
</dict>
</dict>
Unreal Engine 5.8 미만
Unreal Engine 5.8 미만 버전은 Unreal 공식 UIScene 지원 대상이 아니에요. Unreal Engine 5.4.4에서는 Scene lifecycle을 항상 사용하는 방식으로 엔진 소스를 직접 수정해요.
아래 구현은 Unreal 공식 가이드가 아니라 STOVE 검증을 기반으로 작성된 호환 가이드예요. Unreal Engine 5.8 이상 사용을 권장해요.
8) iOS — LSSupportsOpeningDocumentsInPlace 사용 을 적용했다면 먼저 원복해 주세요
ㆍ STOVE SDK 2.8.0 ~ 2.9.x 연동을 위해 IOSAppDelegate에 추가한 OnOpenURLwithOptions, savedOpenUrlWithOptionsParameters, application:openURL:options: 코드를 모두 제거한 뒤 아래 가이드를 적용해요.
ㆍ STOVE SDK 3.0.0 미만은 아래 가이드에서 같은 코드를 다시 추가해요. 원복하지 않으면 중복 선언으로 빌드가 실패해요.
ㆍ STOVE SDK 3.0.0 이상은 OnOpenURL만 사용하므로 해당 코드가 필요 없어요. 남아 있으면 URL callback이 OnOpenURL로 전달되지 않을 수 있어요.
1. 공통 Scene lifecycle 구현
SDK 버전과 관계없이 다음 항목을 커스텀 엔진에 적용해요.
IOSSceneDelegate추가UIWindowScene에 연결된 window 생성- 동일한 window를
IOSAppDelegate.Window에 연결 FAppEntry::PreInit, splash screen과 game thread 초기화- Scene lifecycle을 기존
IOSAppDelegatehandler로 전달 - 최종
Info.plist에 Scene Manifest 생성
// Engine/Source/Runtime/ApplicationCore/Public/IOS/IOSSceneDelegate.h
// 신규 파일로 생성해요.
#pragma once
#import <UIKit/UIKit.h>
#if PLATFORM_IOS && !PLATFORM_TVOS && !PLATFORM_VISIONOS
#ifndef SWIFT_IMPORT
APPLICATIONCORE_API
#endif
@interface IOSSceneDelegate : UIResponder <UIWindowSceneDelegate>
@property (strong, nonatomic) UIWindow *window;
@end
#endif
// Engine/Source/Runtime/ApplicationCore/Public/IOS/IOSAppDelegate.h
- (void)ForceExit;
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
- (void)handleWillResignActive;
- (void)handleDidEnterBackground;
- (void)handleWillEnterForeground;
- (void)handleDidBecomeActive;
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
@property (nonatomic, copy)
void(^BackgroundSessionEventCompleteDelegate)();
// Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSAppDelegate.cpp
FCriticalSection RenderSuspend;
// 기존 applicationWillResignActive: 메서드 이름을 변경하고
// 기존 본문을 그대로 유지해요.
- (void)handleWillResignActive
{
// 기존 applicationWillResignActive: 본문
}
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
- (void)applicationWillResignActive:(UIApplication *)application
{
[self handleWillResignActive];
}
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
// 기존 applicationDidEnterBackground: 메서드 이름을 변경하고
// 기존 본문을 그대로 유지해요.
- (void)handleDidEnterBackground
{
// 기존 applicationDidEnterBackground: 본문
}
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
- (void)applicationDidEnterBackground:(UIApplication *)application
{
[self handleDidEnterBackground];
}
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
// 기존 applicationWillEnterForeground: 메서드 이름을 변경하고
// 기존 본문을 그대로 유지해요.
- (void)handleWillEnterForeground
{
// 기존 applicationWillEnterForeground: 본문
}
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
- (void)applicationWillEnterForeground:(UIApplication *)application
{
[self handleWillEnterForeground];
}
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
extern double GCStartTime;
// 기존 applicationDidBecomeActive: 메서드 이름을 변경하고
// 기존 본문을 그대로 유지해요.
- (void)handleDidBecomeActive
{
// 기존 applicationDidBecomeActive: 본문
}
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
- (void)applicationDidBecomeActive:(UIApplication *)application
{
[self handleDidBecomeActive];
}
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
- (void)applicationWillTerminate:(UIApplication *)application
{
// 기존 applicationWillTerminate: 본문
}
// Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSAppDelegate.cpp
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
self.launchOptions = launchOptions;
#if PLATFORM_TVOS
self.bDeviceInPortraitMode = false;
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
#elif PLATFORM_IOS && !PLATFORM_VISIONOS
self.InterfaceOrientation = UIInterfaceOrientationUnknown;
self.bDeviceInPortraitMode = false;
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
#else
self.InterfaceOrientation =
[self.Window.windowScene interfaceOrientation];
self.bDeviceInPortraitMode =
UIInterfaceOrientationIsPortrait(self.InterfaceOrientation);
printf(
"========= This app is in %s mode\n",
self.bDeviceInPortraitMode ? "PORTRAIT" : "LANDSCAPE"
);
#endif
// 기존 코드
// ...
// Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSAppDelegate.cpp
#if !BUILD_EMBEDDED_APP
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
#if !(PLATFORM_IOS && !PLATFORM_TVOS && !PLATFORM_VISIONOS)
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
#if PLATFORM_VISIONOS
CGRect MainFrame = CGRectMake(0, 0, 1000, 1000);
#else
CGRect MainFrame = [[UIScreen mainScreen] bounds];
#endif
self.Window = [[UIWindow alloc] initWithFrame:MainFrame];
[self.Window makeKeyAndVisible];
FAppEntry::PreInit(self, application);
#if !PLATFORM_VISIONOS
UIStoryboard* storyboard =
[UIStoryboard storyboardWithName:@"LaunchScreen" bundle:nil];
if (storyboard != nil)
{
self.viewController =
[storyboard instantiateViewControllerWithIdentifier:
@"LaunchScreen"];
self.viewController.view.tag = 200;
[self.Window addSubview:self.viewController.view];
GShowSplashScreen = true;
}
#endif
timer = [NSTimer
scheduledTimerWithTimeInterval:0.05f
target:self
selector:@selector(timerForSplashScreen)
userInfo:nil
repeats:YES];
[self StartGameThread];
self.CommandLineParseTimer = [NSTimer
scheduledTimerWithTimeInterval:0.01f
target:self
selector:@selector(NoUrlCommandLine)
userInfo:nil
repeats:NO];
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
#endif // !(PLATFORM_IOS && !PLATFORM_TVOS && !PLATFORM_VISIONOS)
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
#endif
// Engine/Source/Programs/UnrealBuildTool/Platform/IOS/UEDeployIOS.cs
return MinVersionToReturn;
}
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
private static void AppendSceneManifest(StringBuilder Text)
{
Text.AppendLine("\t<key>UIApplicationSceneManifest</key>");
Text.AppendLine("\t<dict>");
Text.AppendLine(
"\t\t<key>UIApplicationSupportsMultipleScenes</key>"
);
Text.AppendLine("\t\t<false/>");
Text.AppendLine("\t\t<key>UISceneConfigurations</key>");
Text.AppendLine("\t\t<dict>");
Text.AppendLine(
"\t\t\t<key>UIWindowSceneSessionRoleApplication</key>"
);
Text.AppendLine("\t\t\t<array>");
Text.AppendLine("\t\t\t\t<dict>");
Text.AppendLine(
"\t\t\t\t\t<key>UISceneConfigurationName</key>"
);
Text.AppendLine(
"\t\t\t\t\t<string>Default Configuration</string>"
);
Text.AppendLine(
"\t\t\t\t\t<key>UISceneDelegateClassName</key>"
);
Text.AppendLine(
"\t\t\t\t\t<string>IOSSceneDelegate</string>"
);
Text.AppendLine("\t\t\t\t</dict>");
Text.AppendLine("\t\t\t</array>");
Text.AppendLine("\t\t</dict>");
Text.AppendLine("\t</dict>");
}
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
public static void WritePlistFile(
FileReference PlistFile,
DirectoryReference? ProjectLocation,
UnrealPluginLanguage? UPL,
string GameName,
bool bIsUnrealGame,
string ProjectName,
ILogger Logger
)
{
// 기존 plist 생성 코드
// ...
Text.AppendLine("\t<key>UIRequiresFullScreen</key>");
Text.AppendLine("\t<true/>");
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
AppendSceneManifest(Text);
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
Text.AppendLine("\t<key>UIViewControllerBasedStatusBarAppearance</key>");
}
public static bool GenerateLegacyIOSPList(...)
{
// 기존 plist 생성 코드
// ...
Text.AppendLine("\t<key>UIRequiresFullScreen</key>");
Text.AppendLine("\t<true/>");
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
AppendSceneManifest(Text);
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
Text.AppendLine(
"\t<key>UIViewControllerBasedStatusBarAppearance</key>"
);
// 기존 코드
// ...
}
// Engine/Source/Runtime/Launch/Private/IOS/LaunchIOS.cpp
#include "IMessagingModule.h"
#include "IOS/IOSAppDelegate.h"
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
#include "IOS/IOSApplication.h"
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
#include "IOS/IOSView.h"
#include "IOS/IOSCommandLineHelper.h"
// Engine/Source/Runtime/Launch/Private/IOS/LaunchIOS.cpp
static void MainThreadInit()
{
#if !UE_USE_SWIFT_UI_MAIN
IOSAppDelegate* AppDelegate = [IOSAppDelegate GetDelegate];
#if PLATFORM_VISIONOS
CGRect MainFrame = CGRectMake(0, 0, 1000, 1000);
#else
// Size the view appropriately for any potentially dynamically attached displays,
// prior to creating any framebuffers
CGRect MainFrame = [[UIScreen mainScreen] bounds];
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
#if PLATFORM_IOS && !PLATFORM_TVOS
if (UIWindowScene* WindowScene =
AppDelegate.Window.windowScene)
{
AppDelegate.InterfaceOrientation =
[WindowScene interfaceOrientation];
AppDelegate.bDeviceInPortraitMode =
UIInterfaceOrientationIsPortrait(
AppDelegate.InterfaceOrientation
);
const CGRect SceneBounds =
WindowScene.coordinateSpace.bounds;
if (SceneBounds.size.width > 0 &&
SceneBounds.size.height > 0)
{
MainFrame = SceneBounds;
}
}
if (AppDelegate.InterfaceOrientation !=
UIInterfaceOrientationUnknown)
{
FIOSApplication::CachedOrientation =
AppDelegate.InterfaceOrientation;
}
#endif
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
#endif
// 기존 MainThreadInit 코드
// ...
#endif
}
2. SDK 버전별 delegate 선언
Unreal Engine의 기존 FIOSCoreDelegates::OnOpenURL을 사용하므로 별도 delegate를 선언하지 않아요.
3. SDK 버전별 AppDelegate URL handler 추가
IOSAppDelegate.h에 다음 handler를 선언해요.
// Engine/Source/Runtime/ApplicationCore/Public/IOS/IOSAppDelegate.h
- (void)ForceExit;
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
- (BOOL)handleOpenURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation;
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
@property (nonatomic, copy)
void(^BackgroundSessionEventCompleteDelegate)();
IOSAppDelegate.cpp에서 엔진 초기화 상태에 따라 URL을 바로 전달하거나 기존 저장 경로에 보관해요.
// Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSAppDelegate.cpp
// 기존 메서드의 본문을 다음 공통 handler로 이동해요.
// ============ [STOVE SceneDelegate 코드 추가 시작] ============
- (BOOL)handleOpenURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation
{
#if !NO_LOGGING
NSLog(@"%s", "IOSAppDelegate openURL\n");
#endif
if (FString(url.scheme) == FApp::GetName())
{
NSString* EncodedURLString = [url absoluteString];
NSString* URLString =
[EncodedURLString stringByRemovingPercentEncoding];
FString CommandLineParameters(URLString);
int32 URLTerminator = CommandLineParameters.Find(
TEXT("://"),
ESearchCase::CaseSensitive
);
if (URLTerminator > -1)
{
CommandLineParameters.RightChopInline(
URLTerminator + 3,
false
);
}
FIOSCommandLineHelper::InitCommandArgs(
CommandLineParameters
);
self.bCommandLineReady = true;
[self.CommandLineParseTimer invalidate];
self.CommandLineParseTimer = nil;
}
UIApplication* Application =
[UIApplication sharedApplication];
if (bEngineInit)
{
FIOSCoreDelegates::OnOpenURL.Broadcast(
Application,
url,
sourceApplication,
annotation
);
}
else
{
NSMutableDictionary* Parameter = [@{
@"application": Application,
@"url": url
} mutableCopy];
if (sourceApplication != nil)
{
Parameter[@"sourceApplication"] = sourceApplication;
}
if (annotation != nil)
{
Parameter[@"annotation"] = annotation;
}
[savedOpenUrlParameters addObject:Parameter];
[Parameter release];
}
return YES;
}
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation
{
return [self handleOpenURL:url
sourceApplication:sourceApplication
annotation:annotation];
}
// ============ [STOVE SceneDelegate 코드 추가 끝] ============
FCriticalSection RenderSuspend;
4. 엔진 초기화 후 저장된 URL 전달
Unreal Engine의 기존 savedOpenUrlParameters 처리 경로를 유지해요.
// Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSAppDelegate.cpp
for (NSDictionary* Parameter in self.savedOpenUrlParameters)
{
UIApplication* Application = Parameter[@"application"];
NSURL* URL = Parameter[@"url"];
NSString* SourceApplication = Parameter[@"sourceApplication"];
id Annotation = Parameter[@"annotation"];
FIOSCoreDelegates::OnOpenURL.Broadcast(
Application,
URL,
SourceApplication,
Annotation
);
}
self.savedOpenUrlParameters = nil;
5. SDK 버전별 SceneDelegate URL 전달
// Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSSceneDelegate.cpp
// 신규 파일로 생성해요.
// Copyright Epic Games, Inc. All Rights Reserved.
#include "IOS/IOSSceneDelegate.h"
#if PLATFORM_IOS && !PLATFORM_TVOS && !PLATFORM_VISIONOS
#include "IOS/IOSAppDelegate.h"
extern bool GShowSplashScreen;
@implementation IOSSceneDelegate
@synthesize window = _window;
- (void)scene:(UIScene *)scene
willConnectToSession:(UISceneSession *)session
options:(UISceneConnectionOptions *)connectionOptions
{
if (![scene isKindOfClass:[UIWindowScene class]])
{
return;
}
UIWindowScene* WindowScene = (UIWindowScene*)scene;
IOSAppDelegate* AppDelegate = [IOSAppDelegate GetDelegate];
self.window =
[[UIWindow alloc] initWithWindowScene:WindowScene];
[self.window makeKeyAndVisible];
AppDelegate.Window = self.window;
AppDelegate.InterfaceOrientation =
[WindowScene interfaceOrientation];
AppDelegate.bDeviceInPortraitMode =
UIInterfaceOrientationIsPortrait(
AppDelegate.InterfaceOrientation
);
#if !BUILD_EMBEDDED_APP
FAppEntry::PreInit(
AppDelegate,
[UIApplication sharedApplication]
);
UIStoryboard* Storyboard =
[UIStoryboard storyboardWithName:@"LaunchScreen"
bundle:nil];
if (Storyboard != nil)
{
AppDelegate.viewController =
[Storyboard instantiateViewControllerWithIdentifier:
@"LaunchScreen"];
AppDelegate.viewController.view.tag = 200;
[self.window addSubview:
AppDelegate.viewController.view];
GShowSplashScreen = true;
}
AppDelegate.timer = [NSTimer
scheduledTimerWithTimeInterval:0.05f
target:AppDelegate
selector:@selector(timerForSplashScreen)
userInfo:nil
repeats:YES];
[AppDelegate StartGameThread];
AppDelegate.CommandLineParseTimer = [NSTimer
scheduledTimerWithTimeInterval:0.01f
target:AppDelegate
selector:@selector(NoUrlCommandLine)
userInfo:nil
repeats:NO];
#endif
if (connectionOptions.URLContexts.count > 0)
{
[self scene:scene
openURLContexts:connectionOptions.URLContexts];
}
}
- (void)sceneDidDisconnect:(UIScene *)scene
{
[[IOSAppDelegate GetDelegate] handleDidEnterBackground];
}
- (void)sceneDidBecomeActive:(UIScene *)scene
{
[[IOSAppDelegate GetDelegate] handleDidBecomeActive];
}
- (void)sceneWillResignActive:(UIScene *)scene
{
[[IOSAppDelegate GetDelegate] handleWillResignActive];
}
- (void)sceneWillEnterForeground:(UIScene *)scene
{
[[IOSAppDelegate GetDelegate] handleWillEnterForeground];
}
- (void)sceneDidEnterBackground:(UIScene *)scene
{
[[IOSAppDelegate GetDelegate] handleDidEnterBackground];
}
// 아래에서 사용하는 STOVE SDK 버전에 해당하는
// scene:openURLContexts: 구현 하나를 이 위치에 추가해요.
@end
#endif
// Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSSceneDelegate.cpp
- (void)scene:(UIScene *)scene
openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
{
IOSAppDelegate* AppDelegate =
[IOSAppDelegate GetDelegate];
for (UIOpenURLContext* Context in URLContexts)
{
[AppDelegate handleOpenURL:Context.URL
sourceApplication:
Context.options.sourceApplication
annotation:
Context.options.annotation];
}
}
6. 종료 상태 URL callback 전달
5단계에서 작성한 scene:willConnectToSession:options:의 마지막 부분이 다음과 같은지 확인해요. 아래 메서드를 새로 추가하지 않아요.
// Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSSceneDelegate.cpp
- (void)scene:(UIScene *)scene
willConnectToSession:(UISceneSession *)session
options:(UISceneConnectionOptions *)connectionOptions
{
// window, FAppEntry::PreInit, splash screen과
// game thread 초기화
// ...
AppDelegate.CommandLineParseTimer = [NSTimer
scheduledTimerWithTimeInterval:0.01f
target:AppDelegate
selector:@selector(NoUrlCommandLine)
userInfo:nil
repeats:NO];
#endif
// 종료 상태로 전달된 URL callback 처리
if (connectionOptions.URLContexts.count > 0)
{
[self scene:scene
openURLContexts:connectionOptions.URLContexts];
}
}
window와 STOVE SDK 초기화 경로를 구성하기 전에 URL을 전달하면 callback을 처리할 객체가 준비되지 않았을 수 있어요.
7. 엔진과 iOS target 다시 빌드
엔진 소스를 수정한 후 ApplicationCore, Launch, UnrealBuildTool 변경이 반영되도록 엔진을 다시 빌드해요.
8. 적용 결과 확인
- 최종 앱의
Info.plist에UIApplicationSceneManifest가 생성되어 있어요. UISceneDelegateClassName이 실제IOSSceneDelegate와 일치해요.- 앱 실행 중에 받은 URL callback이 한 번만 처리돼요.
- 앱 종료 상태에서 받은 URL callback이 엔진 초기화 후 처리돼요.
- STOVE 앱 간 인증 후 게임으로 돌아오면 인증이 완료돼요.
- 사용 중인 SDK 버전과 일치하는 URL delegate만 호출돼요.
iOS Firebase Analytics 결제 이벤트 연동
StoveIAP2를 사용하는 게임에서 Firebase Analytics에 결제 이벤트를 수동으로 연동하는 방법이에요. iOS 15 이상 + StoreKit 2 환경이 대상이에요.
개요
- iOS StoreKit 2 환경에서는 Firebase Analytics의 결제 자동 수집(
event_origin = auto)이 더 이상 동작하지 않아요. - 그래서 StoveIAP2 결제 리스너(
SGSPurchasesUpdatedNotification) 콜백 내부에서Analytics.logEvent("in_app_purchase", ...)를 직접 호출해야 해요. - 전송 파라미터 셋은 기존 StoreKit 1이 자동 적재하던 BigQuery 컬럼과 호환돼요.
iOS 전용 — Android는 플랫폼 가드로 감싸요
ㆍ Android는 현재 결제 이벤트 자동 수집이 지원돼요. 향후 수동 수집을 지원하는 Firebase Android SDK가 배포·적용되면 자동 수집분과 중복 집계될 수 있어요.
ㆍ 크로스플랫폼 엔진(Unity·Unreal)에서는 아래 예시 코드처럼 iOS 플랫폼 가드로 감싸 주세요.
참고 — Firebase 안내
Starting from Google Analytics for Firebase iOS SDK version 12.5.0, in_app_purchase events will no longer be reserved. Manually logged in_app_purchase events (via SDK or Measurement Protocol) will be counted in addition to those automatically collected by the SDK.
Android will follow in the coming months.
Firebase SDK 최소 버전
Firebase Analytics에서 예약 이벤트 in_app_purchase의 수동 전송이 지원되는 버전이에요.
| 플랫폼 | 최소 버전 |
|---|---|
| iOS Native (CocoaPods) | 12.5.0 이상 |
| Unity | 13.6.0 이상 |
| C++ (Cocos2d-x 등) | 13.3.0 이상 |
Firebase 공식 문서 (필독)
ㆍ Firebase iOS 인앱 구매 측정 문서를 함께 확인해 주세요. Firebase iOS 인앱 구매 측정
전송 파라미터 — 필수
결제 리스너 콜백에서 logEvent("in_app_purchase", ...)를 호출할 때 채우는 파라미터예요. 아래 표의 키·타입·단위 그대로 전송해요. 기존 StoreKit 1에서 자동 수집하던 컬럼과 동일한 형태예요.
| Firebase 키 | 전송 타입 | 예시 전송 값 | product 객체 필드 | BigQuery 저장값 |
|---|---|---|---|---|
| product_id | string | "item_001" | product.productIdentifier | 동일 |
| product_name | string | "1000엔 상품" | product.localizedTitle | 동일 |
| currency | string | "USD" | product.priceCurrencyCode | 동일 |
| price | double | 0.99 | product.priceAmountMicros / 1_000_000.0 | 990000 (Firebase 백엔드가 ×1,000,000 변환) |
| value | double | 0.99 | product.priceAmountMicros / 1_000_000.0 | 990000 (Firebase 백엔드가 ×1,000,000 변환) |
| quantity | long | 1 | 고정 (StoveIAP2는 단건 결제) | 1 |
| validated | long | 1 | 고정 (리스너는 검증 성공 시에만 호출) | 1 |
단위 주의 (중요)
ㆍ 예약 이벤트 in_app_purchase의 value·price는 Firebase 백엔드가 자동으로 ×1,000,000 하여 BigQuery(micros 정수)에 적재해요. 따라서 실제 통화 단위 Double(예: $0.99 → 0.99)로 보내야 기존 자동 전송 포맷의 990000 값과 일치해요.
ㆍ priceAmountMicros 정수(990000)를 그대로 전송하면 ×1,000,000이 한 번 더 적용돼 990000000000으로 과대 적재돼요. firebase_error 없이 "들어간 것처럼" 보이지만 매출 금액이 1백만 배로 왜곡되므로, 반드시 Double 단위로 전송해요.
전송 불필요 — Firebase 자동 부여
- 세션·화면 정보 등 시스템 파라미터는 Firebase SDK가 자동으로 부여하므로 전송 코드에 포함하지 않아요.
- 이벤트명은 반드시
in_app_purchase를 유지해요. - 필수 파라미터 이외의 커스텀 파라미터(
content_id,order_id,customer_user_id등)는in_app_purchase이벤트에 추가하지 않는 것을 권장해요. 게임사 자체 분석 데이터가 필요하면 별도 이벤트명(예:stove_purchase_detail)으로 분리 전송해 주세요.
StoveIAP2 리스너 페이로드 참조 (Product)
리스너 콜백의 result가 성공 상태인 경우에만 logEvent를 호출해요. Firebase 전송에는 product 필드만 사용해요.
| 필드 | 타입 | 용도 | 비고 |
|---|---|---|---|
| productIdentifier | String | Firebase product_id |
— |
| localizedTitle | String | Firebase product_name |
— |
| priceAmountMicros | Double | Firebase price 및 value |
⚠️ 단위 주의 (÷1,000,000 필요) |
| priceCurrencyCode | String | Firebase currency |
— |
엔진별 연동 코드
이미 등록·운영 중인 StoveIAP2 결제 리스너의 결제 성공 분기 안에 Firebase 전송 블록만 추가하는 형태예요. 리스너 등록 자체나 결제 성공·실패 분기 처리 로직을 새로 작성할 필요는 없어요. 추가 흐름은 3개 엔진 모두 동일해요 — 결제 성공 분기 진입 → product 필드에서 값 추출 → Firebase 파라미터 구성 → Analytics.logEvent("in_app_purchase", params) 호출.
작업 범위
ㆍ 아래 코드에서 // --------------- START --------------- ~ // --------------- END --------------- 사이 블록만 기존 리스너 성공 분기에 복사 추가하세요.
ㆍ 바깥쪽 리스너/조건 분기는 이미 존재하는 기존 코드의 위치를 보여주기 위한 것으로, 새로 작성·수정할 필요가 없어요.
Swift 프로젝트도 동일한 NotificationCenter API로 구독할 수 있어요. 기존 SGSPurchasesUpdatedNotification 옵저버 콜백의 결제 성공 분기 안에 아래 블록을 추가해요.
#import <FirebaseAnalytics/FirebaseAnalytics.h>
#import <StoveIAP2/StoveIAP2.h>
- (void)onSGSPurchasesUpdated:(NSNotification *)notification
{
SGSResult *result = [notification.userInfo objectForKey:@"result"];
if ([result isSuccessful]) {
// 게임 자체 결제 성공 처리 (아이템 지급, UI 업데이트 등)
// ...
// --------------- START: Firebase 결제 이벤트 전송 ---------------
SGSIAPProduct *product = [notification.userInfo objectForKey:@"product"];
// 단위: Firebase 가 예약 이벤트의 value/price 를 ×1,000,000 변환하므로
// 실제 통화 단위 Double 로 전송
double priceAmount = product.priceAmountMicros / 1000000.0;
NSDictionary *params = @{
@"product_id": product.productIdentifier ?: @"",
@"product_name": product.localizedTitle ?: @"",
@"currency": product.priceCurrencyCode ?: @"",
@"price": @(priceAmount),
@"value": @(priceAmount),
@"quantity": @1,
@"validated": @1
};
[FIRAnalytics logEventWithName:@"in_app_purchase" parameters:params];
// --------------- END ---------------
}
}
📖 Firebase iOS 이벤트 로깅 공식 문서: Log events
지원 엔진 요약
| 엔진 | 리스너 시그니처 | 비고 |
|---|---|---|
| iOS Native (Obj-C / Swift) | NotificationCenter의 SGSPurchasesUpdatedNotification 관찰 | Firebase iOS SDK 직접 호출 |
| Unity | IAP.SetListener(Action |
Firebase Unity SDK ↔ iOS CocoaPods 버전 매핑 주의 |
| Unreal (C++) | stove::IAP::SetListener(TFunction |
FString → UTF-8 변환 필요 |
| Cocos2d-x / 기타 C++ | iOS 네이티브 브릿지 직접 구성 | — |
적용 체크리스트
- Firebase SDK 버전 업데이트
- iOS Native: CocoaPods
12.5.0이상 - Unity:
13.6.0이상 (내부 iOS Pods12.6.0이상 자동 설치) - C++ (Cocos2d-x 등): Firebase C++
13.3.0이상 (내부 iOS Pods12.6.0이상)
- iOS Native: CocoaPods
- 엔진별 연동 코드 예시를 기존 리스너 성공 분기에 추가
결제 데이터 연동 확인
연동 후 Firebase DebugView에서 in_app_purchase 이벤트가 의도한 파라미터와 함께 실시간으로 집계되는지 확인할 수 있어요.
- 공식 가이드에 따라 테스트 빌드에 DebugView 활성화
- 테스트 결제 진행 (Apple Sandbox / TestFlight)
- Firebase 콘솔 Analytics → DebugView에서
in_app_purchase이벤트 발생 및 필수 파라미터 노출 확인
DebugView 참고
ㆍ DebugView로는 수동 전송 이벤트(event_origin = app)의 실시간 확인이 가능해요.
ㆍ Firebase DebugView 공식 가이드
참고
- Firebase iOS 인앱 구매 측정 — 파라미터 규격·단위 변환·집계 동작 정의 문서
- 엔진별 이벤트 로깅 공식 문서 — iOS · Unity · C++
- Firebase SDK Release Notes — iOS · Unity · C++
모듈 구성
STOVE SDK는 기능별로 모듈화되어 제공돼요. 3.0.0 부터는 기본 기능이 Stove 모듈 하나로 통합되었고, 인증 Provider · 결제 · 푸시 · 게임 로그는 필요한 모듈만 추가해요.
모듈 구분
4.0.0 기준이에요. 모듈 구성은 3.0.0 과 같고, 모든 모듈을 4.0.0 으로 함께 맞춰야 해요. 모듈 칸은 iOS pod / Android 좌표 순서예요. Unity 패키지 · Unreal 플러그인은 Stove · StoveProviders · StoveIAP · StovePush · StoveGameLog로 제공돼요.
| 구분 | 모듈 | 역할 |
|---|---|---|
| 기본 (필수) | Stove / stove | SDK 초기화 · 환경 설정, 로그인 · 토큰 관리, 통합 로그인 UI, 팝업 · 공지 · 커뮤니티 등 웹뷰 UI, 로그 수집 (2.9.x 의 Base · Log · Auth · AuthUI · View 통합) |
| 인증 Provider | StoveProviders / stove-providers | Google · Apple · Facebook · Naver · Line · Steam · Google Play Games 로그인 (2.9.x 의 Auth* Provider 모듈 통합) |
| 결제 | iOS: StoveIAP2 Android: stove-iap + stove-iap-google / stove-iap-huawei / stove-iap-onestore |
인앱 결제. iOS 는 StoreKit 2 기반, Android 는 사용하는 마켓 모듈만 선택 |
| 푸시 | iOS: StovePush (+ StovePushExtension) Android: stove-push + stove-push-firebase / stove-push-huawei |
푸시 알림 수신 · 처리. 알림 서비스 익스텐션은 iOS 리치 푸시를 쓰는 경우만 |
| 게임 로그 (선택) | StoveGameLog / stove-gamelog | 게임 로그 전송. 게임 로그를 쓰는 게임만 추가 |
2.9.x 모듈과 함께 쓸 수 없어요
ㆍ 2.9.x 의 GamingServices는 3.0.0 에서 제거되었어요. GPG User ID 기능은 StoveProviders에 들어 있어요.
ㆍ 2.9.x 모듈과의 전체 대응표는 3.0.0 업그레이드 안내를 참고해 주세요.
모듈 버전 정보 확인 방법
ㆍ 클라이언트에 적용된 SDK 모듈 버전은 Log.getSDKVersions()를 호출하면 JSON 형태로 확인할 수 있어요.
ㆍ QA 빌드 검증·디버깅·인게임 설정 화면 노출 등에 활용해요. 자세한 내용은 기능별 가이드 > 게임 정보를 참고해요.
버전별 외부 모듈 정보
- 3rd party 인증 Provider, 푸시(Firebase), 결제(StoreKit2) 등 외부 모듈은 SDK 버전에 따라 호환되는 외부 라이브러리 버전이 달라요.
- 외부 모듈을 추가할 때는 사용 중인 STOVE SDK 버전과 호환되는 외부 라이브러리 버전을 SDK 릴리즈 노트에서 확인해 주세요.
멀티플랫폼 고려사항
PC와 모바일을 동시에 서비스하는 멀티플랫폼 게임에서는 두 플랫폼 SDK를 모두 적용해야 해요. 이때 추가로 확인할 사항이에요.
SDK 적용
- PC와 모바일 SDK는 각각 별도 다운로드·적용
- 모바일 빌드: STOVE Mobile SDK (Android / iOS)
- PC 빌드: STOVE PC SDK (PCSDK3)
- 공통 식별자 일관성
- 게임 ID, App ID는 멀티플랫폼 게임 전체에서 동일하게 사용해요.
- 패키지명·번들 ID는 플랫폼별로 다르지만, 스토브 식별 키는 일관성을 유지해야 해요.
- 환경 동기화
- PC/모바일 빌드의 환경(Live/Sandbox)을 일치시켜야 해요.
- QA 시 PC = Sandbox, 모바일 = Live 같은 불일치 구성은 이용자 식별·결제 검증 오류로 이어져요.
이용자 식별
- MemberNo: 스토브 플랫폼 회원 식별자. PC/모바일 동일 회원의 경우 동일한 MemberNo를 사용해요.
- GUID: 게임 캐릭터 식별자. 멀티플랫폼 게임에서 PC/모바일 간 캐릭터 정보 공유 시 캐릭터 연동 가이드 참고
- 회원 타입 차이: 모바일은 정회원·게스트 모두 지원, PC는 정회원만 지원 (PC에서 게스트 로그인 불가)
빌드 분기 권장사항
- 빌드 환경별 분기: 클라이언트 코드에서 컴파일 분기(
#if UNITY_ANDROID등)로 PC/모바일 SDK 호출을 분리해요. - 공통 비즈니스 로직 추상화: 인증·결제 등 공통 흐름은 인터페이스로 추상화한 뒤 플랫폼별 구현체로 구분하는 것을 권장해요.
- 개발자센터 이용/스마일게이트 퍼블리싱 게임 관련: stove.developers@smilegate.com
- 스토브 스토어 입점/스토브 스튜디오 관련: store.support@smilegate.com