TDS WebView 흰화면 증상

개발
,
2

TDS WebView 흰화면 증상 - 해결 경험 공유

안녕하세요. 저도 비슷한 증상을 겪다가 해결해서 경험 공유드립니다.

주의: 아래 내용은 제가 디버깅하면서 추정한 내용이라 정확하지 않을 수 있습니다. 참고만 해주시고, 공식적인 답변은 앱인토스 팀 확인이 필요할 것 같습니다.

제 개발 환경

package.json

{
  "dependencies": {
    "@apps-in-toss/web-framework": "^1.6.2",
    "@toss/tds-mobile": "^2.2.0",
    "@toss/tds-mobile-ait": "^2.2.0",
    "react": "^19.1.0",
    "react-dom": "^19.1.0",
    "react-router-dom": "^7.11.0"
  }
}

granite.config.ts

import { defineConfig } from '@apps-in-toss/web-framework';

export default defineConfig({
  appKey: 'xxx',
  web: {
    host: '192.168.0.x',
    port: 5173,
    commands: {
      dev: 'vite --host',
      build: 'vite build',
    },
  },
});

제가 겪은 증상

저도 질문자분처럼 TDSMobileAITProvider로 감싸면 샌드박스에서 흰화면이 나왔습니다.

다만 저는 브라우저 콘솔에서 아래 에러가 찍혔어요.

Error: brandBridgeColorMode is not a constant handler
    at reportError (@toss_tds-mobile-ait.js:42)
    at defaultOnUncaughtError (react-dom_client.js:6965)
    ...

Provider를 빼면 화면은 나오는데, 그러면 TDS 컴포넌트를 못 쓰니까 의미가 없더라고요.

제가 추정한 원인

여기서부터는 제 추측입니다.

공식 문서 [공통 설정 > 변경 이력] 보니까 이런 내용이 있었어요:

SDK 1.6.1: 브릿지 뷰 기능이 제거되었어요.

그래서 “혹시 bridgeColorMode가 브릿지 뷰 관련 기능이라 1.6.1에서 빠진 건가?” 싶었습니다.

근데 @toss/tds-mobile-ait의 TDSMobileAITProvider가 아직 brandBridgeColorMode를 호출하려고 하니까 에러가 나는 것 같았어요.

정리하면 이런 상황으로 추정됩니다:

SDK 버전 bridgeColorMode TDS 2.2.0
1.6.0 있음 동작함
1.6.1+ 제거됨 에러

SDK랑 TDS 버전 간 호환이 안 맞는 것 같은데, 확실하진 않습니다.

제가 해결한 방법

일단 저는 SDK를 1.6.0으로 내려서 해결했습니다.

package.json 수정

{
  "dependencies": {
-   "@apps-in-toss/web-framework": "^1.6.2",
+   "@apps-in-toss/web-framework": "1.6.0",
    "@toss/tds-mobile": "^2.2.0",
    "@toss/tds-mobile-ait": "^2.2.0"
  }
}

캐럿(^) 빼고 1.6.0으로 고정해주세요.

granite.config.ts

다운그레이드 후에 bridgeColorMode 설정을 추가해야 했습니다. 1.6.0에서는 이 옵션을 명시적으로 넣어줘야 하더라고요.

export default defineConfig({
  appName: 'xxx',
  brand: {
    displayName: '앱이름',
    primaryColor: '#3182F6',
    icon: 'https://...',
+   bridgeColorMode: 'inverted',  // 다운그레이드 후 추가 필요('basic' | 'inverted')
  },
  web: {
    host: '192.168.0.x',  // 본인 IP
    port: 5173,
    commands: {
      dev: 'vite --host',
      build: 'vite build',
    },
  },
});

bridgeColorMode는 'basic'이나 'inverted' 값을 넣으면 됩니다.

패키지 재설치

pnpm install
pnpm dev

결과

다운그레이드 후에 이렇게 하니까 정상 동작했습니다:

// main.tsx
import { TDSMobileAITProvider } from '@toss/tds-mobile-ait';
import { createRoot } from 'react-dom/client';
import { App } from '@/app';

createRoot(document.getElementById('root')!).render(
  <TDSMobileAITProvider>
    <App />
  </TDSMobileAITProvider>
);

// App.tsx
import { Button, Spacing } from '@toss/tds-mobile';

function App() {
  return (
    <div style={{ padding: 20 }}>
      <h1>테스트</h1>
      <Spacing size={24} />
      <Button variant="fill">버튼</Button>
    </div>
  );
}

Button, Spacing 다 잘 나오고, 에러도 안 뜹니다.

요약

항목 내용
문제 TDSMobileAITProvider 사용 시 흰화면
에러 brandBridgeColorMode is not a constant handler
추정 원인 SDK 1.6.1에서 bridgeColorMode 제거, TDS는 아직 호출 시도
해결 1 @apps-in-toss/web-framework를 1.6.0으로 다운그레이드
해결 2 granite.config.ts에 bridgeColorMode: "inverted" 추가

다시 말씀드리지만 제 추정이라 틀릴 수 있습니다. 혹시 앱인토스 팀에서 공식 답변 주시면 더 정확할 것 같아요.

도움이 되셨으면 좋겠습니다!

2개의 좋아요
화면 렌더링이 안됩니다. brandBridgeColorMode is not a constant handler
샌드박스 앱 렌더링 질문 있습니다