- 마지막 업데이트
Mobile SDK 3.0.0 마이그레이션 — 실기기 스모크 체크리스트 (Unity)
Mobile SDK 3.0.0 마이그레이션 가이드(Unity) 대로 3.0.0 으로 올린 뒤 실기기에서 확인하는 항목입니다.
00. 이 문서가 다루는 것
빌드로는 드러나지 않는 항목만 모았습니다. 이번 마이그레이션에서 놓치기 쉬운 문제는
컴파일 에러가 아니라 빌드는 성공하는데 실행하면 오류 없이 동작하지 않는 경우입니다.
- Android 진입점 훅 3개(
Push.handleIntent×2 ·ViewUI.handleIntent/7585)는 없어도 빌드가 됩니다 - iOS AppController 의
onOpenURL:과configurationForConnectingSceneSession:도 없어도 빌드가 됩니다 - 매니페스트가 존재하지 않는 Activity 클래스를 가리켜도 빌드가 됩니다
컴파일·링크·좌표 확인은 이 문서가 아니라 마이그레이션 가이드 Step.5 에서 합니다. 그쪽이
끝난 뒤 이 문서를 실행하십시오.
소요 시간: 사전 준비를 마친 뒤 플랫폼당 20~30분 정도 걸립니다.
01. 사전 준비
- Android 실기기 + APK: 에뮬레이터에서는 푸시 · 결제를 제대로 확인할 수 없습니다
- iOS 실기기 + adhoc/development IPA: 시뮬레이터로는 푸시를 받을 수 없습니다
- 테스트 푸시 발송: 서버에서 테스트 푸시를 보낼 수 있어야 합니다 (A-2 · A-3 · I-2)
- 딥링크 URL: 게임에서 실제로 쓰는 URL (A-4 · I-3)
- 결제 테스트 계정: 구글 · 애플 결제 테스트에 등록된 계정 (C-1)
- 외부 로그인 계정: 구글 또는 애플 계정 (I-1)
- 로그 확인: Android 는
adb logcat, iOS 는 Xcode Devices 또는 Console.app
💡 테스트 푸시 발송과 결제 테스트 계정은 준비에 시간이 걸리므로 먼저 요청해 두십시오.
02. Android
A-0. 설치 직후 첫 실행
- APK 를 설치하고 런처 아이콘으로 실행합니다
기대: 앱이 정상적으로 뜹니다.
실패 징후: 실행 즉시 종료되고 logcat 에ClassNotFoundException: Didn't find class "…" 또는 ActivityNotFoundException 이 남습니다.
원인: AndroidManifest 의 activity android:name 이 실재하지 않는 클래스를 가리킵니다.
가이드 Step.1 의 A · B 를 다시 보십시오 — 상속해 확장 중이면 자기 클래스, SDK 파일을 그대로
쓰면 com.stove.unity.StoveUnityPlayerActivity 여야 하고, 후자라면 그 .kt 파일이 실제로Assets/Stove/Plugins/Android/ 에 있어야 합니다.
# 실제로 무엇이 런처로 등록됐는지 확인
adb shell cmd package resolve-activity --brief -c android.intent.category.LAUNCHER <패키지명>
A-1. 로그인 → 게임 진입
- 앱을 실행해 로그인하고 게임 화면까지 들어갑니다.
기대: 로그인 성공 후 게임 진입까지 막히는 지점이 없습니다.
실패 시: 좌표 누락이 가장 흔합니다 — 가이드 Step.3 의 좌표 목록과 임포트한 패키지가
1:1 인지 확인하십시오. logcat 에 NoClassDefFoundError 가 보이면 그 쪽입니다.
A-2. 푸시 — 앱이 떠 있는 상태에서 알림 탭 (onNewIntent 경로)
- 앱을 실행한 뒤 홈으로 나가 백그라운드에 둡니다
- 서버에서 테스트 푸시를 발송합니다
- 알림을 탭합니다
기대: 앱으로 돌아오고, 푸시에 실린 이동(공지·이벤트 등)이 처리됩니다.
원인(실패 시): 진입점 Activity 의 onNewIntent 에 Push.handleIntent 가 없습니다.
A-3. 푸시 — 앱을 완전히 종료한 상태에서 알림 탭 (onCreate 경로)
⚠️ A-2 와 다른 코드 경로입니다. 둘 다 해야 합니다. 하나만 하면 훅 한 개가 빠진 상태를
통과시킵니다.
- 최근 앱 목록에서 앱을 밀어서 완전히 종료합니다
- 테스트 푸시를 발송하고 알림을 탭합니다
기대: 앱이 새로 실행되고 푸시에 실린 이동이 처리됩니다.
원인(실패 시): onCreate 에 Push.handleIntent(applicationContext, intent) 가 없습니다.
A-4. 딥링크
adb shell am start -a android.intent.action.VIEW -d "<딥링크 URL>"
기대: 앱이 열리고 링크가 지정한 화면으로 이동합니다. 앱이 떠 있는 상태와 종료 상태
둘 다 확인하십시오(A-2/A-3 과 같은 이유로 경로가 다릅니다).
A-5. 오버레이 화면에서 파일 첨부 (requestCode 7585)
⚠️ 이 훅을 검증하는 유일한 경로입니다. 다른 어떤 테스트에서도 드러나지 않습니다.
- 고객센터 · 문의하기 등 SDK 오버레이 화면을 엽니다
- 파일(이미지) 첨부 버튼을 눌러 갤러리에서 이미지를 고릅니다
기대: 고른 이미지가 첨부 목록에 나타납니다.
실패 징후: 갤러리는 정상적으로 열리는데, 이미지를 고르고 돌아오면 아무 일도 일어나지
않습니다(에러도 없음).
원인: 진입점 Activity 의 onActivityResult 에if (requestCode == 7585) ViewUI.handleIntent(requestCode, resultCode, data) 가 없습니다.
03. iOS
I-0. 설치 직후 첫 실행 — 검은 화면 확인
- IPA 를 설치하고 실행합니다
기대: 스플래시를 거쳐 게임 화면이 뜹니다.
실패 징후: 실행 직후 검은 화면에서 더 진행되지 않습니다(크래시는 아님).
원인 두 가지:
- 커스텀 AppController 에 가이드 Step.4 ③
(application:configurationForConnectingSceneSession:options:)이 없습니다 - Unity 2022.3.72f1 미만인데 SceneDelegate 를 적용하지 않았습니다 →
가이드 부록 A(소스 +Info.plist+UnityFrameworkCompile Sources 등록).
2022.3.72f1 이상은 Unity 가 처리하므로 이 원인이 아닙니다
💡 자체 빌드 후처리 스크립트를 쓰면 이 설정이 자동으로 들어가지 않습니다. SDK 샘플은
XcodeSettingsPostProcesser가 처리하지만 게임 자체 스크립트는 직접 반영해야 합니다.
I-1. 외부 로그인 후 앱 복귀
⚠️ iOS 에서 가장 자주 빠지는 항목입니다.
- 구글 또는 애플 로그인을 실행합니다
- 브라우저·시스템 시트에서 인증을 마칩니다
기대: 앱으로 자동 복귀하고 로그인이 완료됩니다.
실패 징후: 인증은 끝났는데 앱으로 돌아오지 않거나, 돌아와도 로그인 결과가 반영되지
않고 대기 상태로 남습니다.
원인: 커스텀 AppController 에 가이드 Step.4 ② 가 없습니다 —AppDelegateListener 채택 · init 의 UnityRegisterAppDelegateListener(self) ·onOpenURL: 구현 세 가지가 모두 있어야 합니다. UIScene 생명주기에서는application:openURL:options: 가 앱 델리게이트로 전달되지 않기 때문에, 기존 오버라이드만
남아 있으면 이 증상이 납니다(기존 오버라이드는 지우지 말고 둡니다).
I-2. 푸시
- 앱이 떠 있는 상태에서 테스트 푸시를 발송하고 알림을 탭합니다
- 앱을 완전히 종료한 뒤 다시 발송하고 알림을 탭합니다
기대: 두 경우 모두 앱이 열리고 푸시에 실린 이동이 처리됩니다.
실패 시: 푸시 권한 · 인증서 · 프로파일을 먼저 확인하십시오(마이그레이션과 무관한 원인이
더 흔합니다). SDK 쪽이라면 AppController 의 SGSPushNotificationCenterDelegate 채택과
가이드 Step.4 ① 의 import 경로를 봅니다.
I-3. 딥링크 — 딥링크를 쓰는 게임만
메모 앱에 딥링크 URL 을 적고 탭해서 엽니다(Safari 주소창에 입력하면 Universal Links 가
앱으로 열리지 않습니다).
- 앱이 떠 있는 상태에서 링크를 탭합니다
- 앱을 완전히 종료한 뒤 다시 탭합니다
기대: 두 경우 모두 앱이 열리고 링크가 지정한 화면으로 이동합니다.
원인(실패 시):
- 1 만 실패 → I-1 과 같은
onOpenURL:경로입니다 - 2 만 실패 → 콜드 스타트 경로입니다. Unity 2022.3.72f1 미만이면 가이드 부록 A 의
SceneDelegate 가 빠지지 않았는지 확인하십시오 - I-1 이 통과했는데 둘 다 실패 → SDK 진입점이 아니라 URL 스킴 · Universal Links 설정 쪽입니다
04. 양 플랫폼 공통
C-1. 결제 1건
- 테스트 계정으로 상품 1건을 실제로 결제합니다
기대: 결제가 완료되고 아이템이 지급됩니다.
원인(실패 시): 임포트한 마켓 패키지와 mainTemplate.gradle 좌표가 어긋난 경우가
가장 흔합니다(가이드 Step.3). 3.0.0 은 마켓별로 패키지가 분리됐으므로, 쓰는 마켓의 패키지를
임포트했는지와 그 좌표가 들어갔는지를 함께 봅니다.
C-2. 계정 로그아웃 → 재로그인
- 로그아웃하고 다른 계정으로 로그인합니다
기대: 계정이 정상적으로 전환되고 이전 계정 정보가 남지 않습니다.
05. 결과 기록
| ID | 항목 | 결과 | 비고 |
|---|---|---|---|
| A-0 | 설치 직후 첫 실행 | ☐ | |
| A-1 | 로그인 → 게임 진입 | ☐ | |
| A-2 | 푸시 (앱 떠 있음 / onNewIntent) | ☐ | |
| A-3 | 푸시 (앱 종료 / onCreate) | ☐ | |
| A-4 | 딥링크 (떠 있음 · 종료 둘 다) | ☐ | |
| A-5 | 오버레이 파일 첨부 (7585) | ☐ | |
| I-0 | 첫 실행 — 검은 화면 아님 | ☐ | |
| I-1 | 외부 로그인 후 앱 복귀 | ☐ | |
| I-2 | 푸시 (떠 있음 · 종료 둘 다) | ☐ | |
| I-3 | 딥링크 (떠 있음 · 종료 둘 다) | ☐ | |
| C-1 | 결제 1건 | ☐ | |
| C-2 | 로그아웃 → 재로그인 | ☐ |
테스트 환경 기록 — 실패를 재현하려면 아래가 필요합니다.
| 항목 | 값 |
|---|---|
| Unity 버전 | |
| 받은 패키지 형태 | 기능별 / 전체 패키지 |
| 임포트한 패키지 | |
| Android 진입점 | 자체 Activity(상속) / SDK 파일 |
| iOS AppController | 게임 자체 / SDK 파일 |
| Android 기기 · OS | |
| iOS 기기 · OS |
06. 우선순위
시간이 부족하면 아래 순서로 줄이십시오. 위 3개는 다른 어떤 테스트로도 대체되지 않습니다.
- A-5(파일 첨부 /
7585) — 이 훅을 검증하는 유일한 경로 - I-1(외부 로그인 복귀) — iOS Step.4 ② 를 검증하는 유일한 경로
- A-3(앱 종료 상태 푸시) —
onCreate훅을 검증하는 경로. A-2 로 대체되지 않습니다 - I-0(검은 화면) · A-0(첫 실행) — 실패하면 즉시 눈에 보이므로 뒤로 미뤄도 됩니다
- C-1 · A-4 · I-3 · A-2 · I-2 · C-2
- 개발자센터 이용/스마일게이트 퍼블리싱 게임 관련: stove.developers@smilegate.com
- 스토브 스토어 입점/스토브 스튜디오 관련: store.support@smilegate.com