- 마지막 업데이트
Mobile SDK 3.0.0 마이그레이션 — 실기기 스모크 체크리스트 (Unreal)
Mobile SDK 3.0.0 마이그레이션 가이드(Unreal) 대로 3.0.0 이상으로 올린 뒤 실기기에서 확인하는 항목입니다.
00. 이 문서가 다루는 것
빌드로는 드러나지 않는 항목만 모았습니다. 이번 마이그레이션에서 놓치기 쉬운 문제는
컴파일 에러가 아니라 빌드는 성공하는데 실행하면 오류 없이 동작하지 않는 경우입니다.
- iOS 엔진에 2.9.x 용 8) 패치가 남아 있어도 빌드가 됩니다 — 외부 로그인 후 로그인이 완료되지 않습니다
- SceneDelegate 를 적용하면서 window 연결이 빠져도 빌드가 됩니다 — 실행 직후 화면이 진행되지 않습니다
_APL.xml에서 좌표나play-services-games-v2줄이 빠져도 빌드가 되는 경우가 있습니다
컴파일 · 링크 · 좌표 확인은 이 문서가 아니라 마이그레이션 가이드 Step.6 에서 합니다. 그쪽이
끝난 뒤 이 문서를 실행하십시오.
💡 Android 의 푸시 · 오버레이 화면 처리 코드는 플러그인이
GameActivity에 자동으로 넣습니다.
게임에서 직접 추가할 코드는 없으며, 아래 항목은 자동으로 들어간 처리가 동작하는지 확인하는 용도입니다.
소요 시간: 사전 준비를 마친 뒤 플랫폼당 20분 정도 걸립니다.
01. 사전 준비
- Android 실기기 + APK: 에뮬레이터에서는 푸시 · 결제를 제대로 확인할 수 없습니다
- iOS 실기기 + adhoc/development IPA: 시뮬레이터로는 푸시를 받을 수 없습니다
- 테스트 푸시 발송: 서버에서 테스트 푸시를 보낼 수 있어야 합니다 (A-3 · A-4 · I-2)
- 결제 테스트 계정: 구글 · 애플 결제 테스트에 등록된 계정 (C-1)
- 외부 로그인 계정: 게임에서 쓰는 외부 로그인(Google · Apple · Naver 등) 계정 (I-1)
- 딥링크 URL: 딥링크를 쓰는 게임만 — 게임에서 실제로 쓰는 URL (I-3)
💡 테스트 푸시 발송과 결제 테스트 계정은 준비에 시간이 걸리므로 먼저 요청해 두십시오.
02. Android
A-1. 로그인 → 게임 진입
- 앱을 실행해 로그인하고 게임 화면까지 들어갑니다
기대: 로그인 성공 후 게임 진입까지 막히는 지점이 없습니다.
실패 시: 좌표 누락이 가장 흔합니다 — 가이드 Step.4 의 좌표 표와 Step.1 에서 복사한
플러그인이 일치하는지 확인하십시오.
A-2. GPG 로그인 — GPG 를 쓰는 게임만
- Google Play Games 로그인을 실행합니다
기대: GPG 계정 선택 후 로그인이 완료됩니다.
원인(실패 시): _APL.xml 에서 com.google.android.gms:play-services-games-v2 줄이com.stove:* 와 함께 지워졌습니다(가이드 Step.4 ⚠️).
A-3. 푸시 — 앱이 떠 있는 상태에서 알림 탭
- 앱을 실행한 뒤 홈으로 나가 백그라운드에 둡니다
- 서버에서 테스트 푸시를 발송합니다
- 알림을 탭합니다
기대: 앱으로 돌아오고, 푸시에 실린 이동(공지 · 이벤트 등)이 처리됩니다.
A-4. 푸시 — 앱을 완전히 종료한 상태에서 알림 탭
⚠️ A-3 과 다른 코드 경로입니다. 둘 다 확인하십시오.
- 최근 앱 목록에서 앱을 밀어서 완전히 종료합니다
- 테스트 푸시를 발송하고 알림을 탭합니다
기대: 앱이 새로 실행되고 푸시에 실린 이동이 처리됩니다.
원인(A-3 · A-4 실패 시): StovePush 플러그인 폴더(Step.1)와 com.stove:stove-push-firebase
좌표(Step.4)가 모두 있는지 확인하십시오. 게임이 자체 _APL.xml 로 GameActivity 의onCreate · onNewIntent 를 수정하고 있다면, 그 코드가 플러그인의 처리를 막고 있지 않은지도 확인합니다.
A-5. 오버레이 화면에서 파일 첨부
- 고객센터 · 문의하기 등 SDK 오버레이 화면을 엽니다
- 파일(이미지) 첨부 버튼을 눌러 갤러리에서 이미지를 고릅니다
기대: 고른 이미지가 첨부 목록에 나타납니다.
실패 징후: 갤러리는 정상적으로 열리는데, 이미지를 고르고 돌아오면 아무 일도 일어나지
않습니다(에러도 없음).
원인: 게임이 자체 _APL.xml 로 GameActivity 의 onActivityResult 를 수정하고 있다면,requestCode 7585 결과가 SDK 로 전달되는지 확인하십시오.
03. iOS
I-0. 설치 직후 첫 실행 — SceneDelegate 를 적용한 게임만
- IPA 를 설치하고 실행합니다
기대: 스플래시를 거쳐 게임 화면이 뜹니다.
실패 징후: 실행 직후 검은 화면이나 스플래시에서 더 진행되지 않습니다.
원인: 개발 환경 설정 iOS Unreal UISceneDelegate 대응 업데이트
의 1. 공통 Scene lifecycle 구현이 일부 빠졌습니다. 최종 .app 의 Info.plist 에UIApplicationSceneManifest 가 있는지, IOSSceneDelegate 에서 window 생성과 엔진 초기화가 실행되는지 확인하십시오.
I-1. 외부 로그인 후 앱 복귀
⚠️ iOS 에서 가장 자주 빠지는 항목입니다.
- 게임에서 쓰는 외부 로그인(Google · Apple · Naver 등)을 실행합니다
- 브라우저 · 시스템 시트 · 외부 앱에서 인증을 마칩니다
기대: 앱으로 자동 복귀하고 로그인이 완료됩니다.
실패 징후: 인증은 끝났는데 앱으로 돌아오지 않거나, 돌아와도 로그인 결과가 반영되지
않고 대기 상태로 남습니다.
원인:
- 엔진에 2.9.x 용 8) 패치(
application:openURL:options:등)가 남아 있습니다 — 가이드 Step.5 ① - SceneDelegate 를 적용했다면
scene:openURLContexts:에서handleOpenURL:로 전달하는 코드가 빠졌습니다
I-2. 푸시
- 앱이 떠 있는 상태에서 테스트 푸시를 발송하고 알림을 탭합니다
- 앱을 완전히 종료한 뒤 다시 발송하고 알림을 탭합니다
기대: 두 경우 모두 앱이 열리고 푸시에 실린 이동이 처리됩니다.
실패 시: 푸시 권한 · 인증서 · 프로비저닝 프로파일을 먼저 확인하십시오(마이그레이션과
무관한 원인이 더 흔합니다).
I-3. 딥링크 — 딥링크를 쓰는 게임만
메모 앱에 딥링크 URL 을 적고 탭해서 엽니다. 앱이 떠 있는 상태에서 확인합니다.
기대: 앱으로 돌아오고 링크가 지정한 화면으로 이동합니다.
원인(실패 시):
- I-1 도 실패 → I-1 과 같은 원인입니다
- I-1 은 통과 → 게임 코드의 딥링크 처리가
OnOpenURL로 옮겨지지 않았거나(가이드 Step.5 ③), URL 스킴 설정 문제입니다
04. 양 플랫폼 공통
C-1. 결제 1건
- 테스트 계정으로 상품 1건을 실제로 결제합니다
기대: 결제가 완료되고 아이템이 지급됩니다.
원인(실패 시): StoveIAP 플러그인 폴더(Step.1)와 com.stove:stove-iap-google
좌표(Step.4)가 모두 있는지 확인하십시오. iOS 는 3.0.0 부터 StoreKit 2 로 동작하므로,
App Store Connect 의 상품 상태와 테스트 계정도 함께 확인합니다.
C-2. 계정 로그아웃 → 재로그인
- 로그아웃하고 다른 계정으로 로그인합니다
기대: 계정이 정상적으로 전환되고 이전 계정 정보가 남지 않습니다.
05. 결과 기록
| ID | 항목 | 결과 | 비고 |
|---|---|---|---|
| A-1 | 로그인 → 게임 진입 | ☐ | |
| A-2 | GPG 로그인 (GPG 사용 시) | ☐ | |
| A-3 | 푸시 (앱 떠 있음) | ☐ | |
| A-4 | 푸시 (앱 종료) | ☐ | |
| A-5 | 오버레이 파일 첨부 | ☐ | |
| I-0 | 첫 실행 (SceneDelegate 적용 시) | ☐ | |
| I-1 | 외부 로그인 후 앱 복귀 | ☐ | |
| I-2 | 푸시 (떠 있음 · 종료 둘 다) | ☐ | |
| I-3 | 딥링크 (딥링크 사용 시) | ☐ | |
| C-1 | 결제 1건 | ☐ | |
| C-2 | 로그아웃 → 재로그인 | ☐ |
테스트 환경 기록 — 실패를 재현하려면 아래가 필요합니다.
| 항목 | 값 |
|---|---|
| Unreal Engine 버전 | |
| SDK 플러그인 버전 | |
| 복사한 플러그인 | |
| iOS 엔진 수정 | SceneDelegate 적용 / 개발팀 안내에 따라 적용 |
| Android 기기 · OS | |
| iOS 기기 · OS |
06. 우선순위
시간이 부족하면 아래 순서로 줄이십시오. 위 2개는 다른 어떤 테스트로도 대체되지 않습니다.
- I-1(외부 로그인 복귀) — 가이드 Step.5 를 검증하는 유일한 경로
- C-1(결제 1건) — iOS StoreKit 2 전환 후 결제 경로를 검증하는 유일한 항목
- A-4(앱 종료 상태 푸시) — A-3 으로 대체되지 않습니다
- I-0 · A-1 — 실패하면 즉시 눈에 보이므로 뒤로 미뤄도 됩니다
- A-2 · A-3 · A-5 · I-2 · I-3 · C-2
- 개발자센터 이용/스마일게이트 퍼블리싱 게임 관련: stove.developers@smilegate.com
- 스토브 스토어 입점/스토브 스튜디오 관련: store.support@smilegate.com