[문의] 미니앱이 최초 배포부터 검은 화면 — 서버측 호스팅 확인 요청
▎
▎ 워크스페이스 **KAM(51725)**의 미니앱 서울 미식 캘린더(miniAppId 55168, appName seoul-gu-cal)가 최초 배포부터 현재까지 모든 번들에서 검은 화면으로만 뜹니다. JS/네이티브 에러 화면도 없이 순수 검정이며, 사용자가 아무 조작도 하기 전 진입 즉시 그렇습니다.
▎
▎ 자체적으로 원인을 격리한 결과 번들/코드 문제가 아님을 확인했습니다:
▎ 1. 앱 로직을 전부 제거하고 한 줄만 렌더하는 최소 번들도 동일하게 검정입니다. (test-push 전달·로드는 정상 확인)
▎ 2. 동일 워크스페이스의 부산 캘린더(miniAppId 52737, busan-cal)는 동일한 프레임워크·의존성·granite.config·SDK 2.10.6으로 같은 기기·같은 계정에서 정상 렌더됩니다.
▎ 3. 두 앱의 빌드 산출물(.granite의 micro-frontend-runtime.js·granite-globals.js·.apps-in-toss.env.js 등 host-integration 파일)이 이름을 제외하면 byte 단위로 동일합니다.
▎ 4. 앱 정보 검토 반려 통보(이메일)는 없었고, 콘솔 상태는 OPEN입니다.
▎
▎ 55168이 seoul-gu-cal 정체성으로 호스트에 마운트되지 못하는 것으로 보입니다. 서버측 등록/호스팅/라우팅을 확인 부탁드립니다.
▎ - 참고: 이 앱은 최초 스캐폴드 시 appName이 seoul-cal이었다가 선점되어 seoul-gu-cal로 변경한 이력이 있습니다. 서버측 라우팅에 구 식별자 잔재가 없는지도 확인 요청드립니다.
▎ - 추가 질문: iOS 실기기에서 이 미니앱의 실제 런타임 에러 로그를 확보하는 방법이 있을까요? (샌드박스 iOS 실기기 빌드가 오래되어 연결이 어려웠습니다.)
Dylan님, 제안대로 새로 스캐폴딩하여 업로드·테스트했으나 여전히 검정화면입니다. 원인을 좁히려 아래 통제 실험을 했고, RN 앱/번들 문제가 아님을 확인했습니다.
▎
▎ 1. create-granite-app 최신 템플릿으로 완전히 새로 스캐폴딩 → 앱 코드 이식 후 테스트푸시 → 검정 (55168, deploymentId 019fc5c6…, sdk 2.10.8)
▎
▎ 2. 앱 코드를 0줄로 제거하고 프레임워크 기본 화면(흰 배경 텍스트)만 담은 최소 번들 → 여전히 검정
▎ - 55168(OPEN)에 sdk 2.10.8: 검정 (019fc5f6…)
▎ - 55168(OPEN)에 sdk 2.10.6 (동작하는 부산앱과 동일 버전): 검정 (019fc603…)
▎ - 별도 미니앱 55148(seoul-cal)에도 동일 최소 번들: 검정 (019fc5f1…)
▎
▎ 3. 대조군: 같은 워크스페이스(51725)의 부산 캘린더(52737)·부산미식(51945)·퇴직연금 계산기(43565)는 모두 정상 렌더(sdk 2.10.4~2.10.6).
▎
▎ 정리: 코드·스캐폴드·SDK 버전·미니앱 정체성·승인상태를 모두 통제했는데 서울 계열 미니앱(55168, 55148)만 어떤 번들로도 검정입니다. 번들이 React 렌더 이전 단계에서 로드 실패하는 것으로 보입니다(ErrorBoundary 폴백 미표시). 55168/55148의 호스트측 번들 로딩/등록을 점검 부탁드립니다.
▎
▎ 참고 단서: 정상 앱들은 2026-06-29~07-14 생성, 검정 앱(55168)은 07-22 생성입니다. 또 55168은 appName이 seoul-cal→seoul-gu-cal로 변경된 이력이 있습니다(당시 seoul-cal은 별도 미니앱 55148이 선점). 호스트측 라우팅에 이 이관 잔재가 남았을 가능성을 함께 확인 부탁드립니다.
먼저 말씀 주신 테스트 스킴 콘솔 업로드는 흔쾌히 허용합니다. 직접 진단해 주신다니 정말 감사합니다. 다만 55168은 현재 라이브 상태라, 실사용자에게 나가는 번들이 덮어써지지 않도록 승격되지 않는 테스트 빌드로 진행해 주시면 감사하겠습니다. 필요하시다면 진단 전용으로 별도 앱 ID를 새로 만들어 드리는 것도 얼마든지 가능하니 편하신 방식으로 말씀해 주세요.
스캐폴드 방식은 아래와 같습니다. granite-js 기반 apps-in-toss 공식 템플릿을 사용했고, 빌드는 WSL(Ubuntu)에서 ait build로 진행합니다. (아래 패키지들은 모두 npm 스코프 패키지라, 실제 이름은 앞에 @가 붙습니다.)
apps-in-toss/framework ^2.10.6
granite-js/react-native · granite-js/native · plugin-router · plugin-hermes 모두 1.0.36
참고로 Windows 네이티브 빌드는 경로 백슬래시 문제로 실패해서 WSL에서 빌드하고 있는데, Windows↔Linux 번들 diff가 3곳뿐이라 빌드 환경은 원인에서 배제한 상태입니다.
현재 55168 라이브 상태도 공유드립니다. 7월 23일 배포 이후 추가 배포는 하지 않았고, 이 빌드는 정식 앱 전체를 ErrorBoundary로 감싼 진단용 빌드입니다. JS 단에서 크래시가 났다면 에러 화면이라도 떠야 하는데, 저희 여러 기기에서는 에러 문구조차 없이 검정화면만 나오고 있습니다. 그래서 문제가 JS/React 층이 아니라 그 아래 네이티브 층에 있는 것은 아닐까 조심스럽게 추측하고 있습니다.
원인을 좁혀 보고자 아래 통제 실험도 해봤습니다.
거의 빈 최소 앱을 올려도 검정화면이 떴고, apps-in-toss/framework 2.10.6·2.10.8 두 버전 모두 동일했습니다.
반면 완전히 동일한 스택과 빌드 경로로 만든 부산 앱(부산미식 51945, 부산 캘린더 52737)은 정상 동작합니다. 그래서 코드나 버전, 빌드 환경보다는 55168(및 55148) 앱 ID 쪽 조건과 관련된 것으로 보고 있습니다.
말씀하신 대로 그쪽에서는 특별한 문제가 보이지 않으신다니, 재현 여부가 갈리는 지점을 함께 좁혀보고 싶습니다. 혹시 테스트하신 기기 모델·OS 버전·토스앱 버전, 그리고 55168 정식 진입 경로로 확인하셨는지 여쭤봐도 될까요? 저희 쪽에서는 여러 기기에서 재현되고 있어, 조건을 맞춰 보면 원인이 드러날 것 같습니다.
번거로우실 텐데 세심히 봐주셔서 다시 한번 감사드립니다. 필요한 정보나 추가 빌드가 있으면 언제든 바로 준비해 드리겠습니다.
확인 감사합니다. 저희는 @"^1"이 아니라 npm create granite-app@latest로 스캐폴드했고, 그 결과 React 19.2.3 + React Native 0.84.0 + granite-js 1.0.36 조합이 나왔습니다.
▎
▎ 말씀 덕분에 결정적인 단서를 찾았습니다. 저희가 정상 작동 중인 부산 앱(부산미식 51945)은 RN 0.84.0 · granite-js 1.0.36 · framework 2.10.6으로 서울 앱과 동일한데, React만 18.3.1입니다. 반면 검정화면이 나는 서울 앱과 저희가 만든 최소 번들 변종 전부는 React 19.2.3입니다. 다른 조건은 같고 React 버전만 갈립니다.
▎
▎ 혹시 현재 호스트 런타임이 React 19와 호환되지 않아서(그래서 최소 번들도 @^1로 스캐폴드하신 것은 React 18이라 정상 작동한) 것일까요? 저희가 React 18.3.1로 다시 스캐폴드/고정해서 재배포해보면 될지 확인 부탁드립니다.
지금까지 안내해 주신 방향(스캐폴딩, React 버전 등)을 포함해 아래를 순서대로 확인했는데, 서울 미식 캘린더(miniAppId 55168, appName seoul-gu-cal)는 여전히 실행 시 “일시적인 오류” 화면이 뜨고 정상 렌더가 되지 않습니다. 반면 같은 폰·계정·워크스페이스(51725)의 부산 캘린더(52737), 부산미식(51945), 퇴직연금 계산기(43565)는 정상적으로 잘 뜹니다.
확인해 본 항목:
앱 코드 — create-granite-app 기본 템플릿(코드 없이 기본 화면만) 업로드해도 동일 증상.
스캐폴드 — npm create granite-app@^1로 클린 재스캐폴딩해도 동일.
React 버전 — 19.2.3 → 18.3.1 고정 후 재빌드해도 동일.
react-native-webview — 13.16.0 → 14.0.1(정상 동작하는 부산앱과 같은 버전)로 맞춰도 동일.
광고(InlineAd) 모듈 — 부팅 시 마운트되는 광고 컴포넌트를 제거한 번들(20260804-13)을 검수 승인 후 라이브 반영했으나 동일.
기기 캐시 — 위 번들이 라이브(APPROVED·OPEN·배포 완료)인 상태에서 토스 앱을 완전히 종료 후 재실행하고 열어도 동일.
번들 내용을 바꿔도 동일하게 실패하고, 화면도 앱 자체 에러 UI(ErrorBoundary)가 아니라 호스트의 “일시적인 오류” 화면이 뜨는 점에서, 저희 번들이 실제로 로드되기 이전 단계에서 막히는 것으로 보입니다. 페이지뷰·세션도 계속 0으로 집계됩니다.
혹시 참고가 될까 하여 한 가지 이력을 남깁니다. 이 미니앱은 처음에 appName을 seoul-cal로 스캐폴딩했다가 선점되어 seoul-gu-cal로 변경한 이력이 있습니다. 같은 워크스페이스의 서울 캘린더(55148, seoul-cal)도 동일하게 로딩되지 않는 상태여서, 혹시 호스트측 등록/라우팅 경로와 관련이 있는지 함께 봐주시면 감사하겠습니다.
번거로우시겠지만 아래를 확인해 주실 수 있을까요?
55168(seoul-gu-cal)의 번들 로딩/등록 관련 호스트측 로그
초기 appName(seoul-cal)에서 seoul-gu-cal로 변경된 이력이 등록 정보에 남아 있는지
정상 동작하는 부산 캘린더(52737, busan-cal)와의 등록/라우팅 차이
참고 정보:
워크스페이스: 51725
현재 라이브 배포: 버전 20260804-13, deploymentId 019fc82f-20b6-7df5-a669-0808afb1aade, SDK 2.10.8, 배포 2026-08-04, 상태 OPEN
바쁘신 와중에 확인 부탁드려 죄송하고, 도움 주셔서 감사합니다. 추가로 필요한 정보 있으면 바로 전달드리겠습니다.
안녕하세요, 안내해 주신 대로 클린 스캐폴딩부터 다시 진행해서 원인을 찾았습니다. 공유드립니다.
결론부터 말씀드리면, 재현되는 문제는 React 19 + react-native-svg 조합에서 발생하는 것으로 보입니다.
확인 과정:
create-granite-app@^1 클린 스캐폴딩 → @apps-in-toss/framework 설치 → ait init → seoul-gu-cal(55168)로 업로드하면 정상 동작합니다 (안내 주신 대로 확인했습니다).
여기에 react-native-svg(^15.15.5)만 추가하고 SvgXml 하나만 렌더해도 화면이 검게 나옵니다. svg를 빼면 다시 정상 동작합니다.
React를 19.2.3으로 유지한 채 svg를 완전히 제거하니 앱 전체가 정상적으로 떴습니다.
참고로 저희가 운영 중인 다른 앱(부산미식, tour-de-busan)은 React 18.3.1 + @apps-in-toss/framework 2.10.6 + react-native-svg 15.15.5 조합인데, 동일한 svg 아이콘이 정상 동작하며 라이브 서비스 중입니다. 이번 서울 앱만 안내 주신 대로 React 19로 올리면서 같은 svg가 부팅 시 크래시가 납니다.
여쭙고 싶은 점:
현재 앱인토스 호스트(React 19 기준)에서 react-native-svg가 지원되나요? 지원된다면 권장 버전이 있을까요?
아니면 당분간 부산앱처럼 React 18 유지가 맞을까요?
일단 svg를 제거한 React 19 버전으로 정상 동작은 확인했습니다. 다만 아이콘·여권 도장 UI를 svg로 복구하려면 위 부분 확인이 필요해서 문의드립니다. 감사합니다.
