TDS WebView 흰화면 증상

개발
,
1

안녕하세요. WebView에서 TDS를 사용하면 샌드박스 앱에서 흰화면이 발생합니다.

<TDSMobileAITProvider>
    <Button>버튼</Button>
</TDSMobileAITProvider>

위처럼 심플하게 구현하더라도 앱바와 흰 화면만 나타나고 버튼은 보이지 않습니다.

TDSMobileAITProvider대신 ThemeProvider를 사용하면 그때는 보이지만 탭바를 비롯한 다른 컴포넌트들이 정상적으로 동작하지 않는 것 같습니다.

web: {
    host: '192.168.0.5',
    port: 5173,
    commands: {
      dev: 'vite --host', 
      build: 'vite build',
    },
  },

ThemeProvider로 했을 때는 흰화면이 발생하지 않는 것으로 보아선 granite.config.ts 세팅도 문제 없어보입니다. 참고로 위와 같이 세팅한 상태이며, 기기도 같은 네트워크 상에 존재합니다.

 RN   LOG  Running "shared" with {"initialProps":{"initialColorPreference":"light","loadingStartTs":1767002200297,"initialFontScale":"100"},"rootTag":461}
 RN   DEBUG  [Analytics] {      
  "log_type": "screen",
  "log_name": "/::screen",      
  "params": {
    "referrer": null,
    "deployment_id": "local",   
    "deployment_timestamp": null
  }
}
 RN   LOG  [eventLogDebug] {"log_name": "/::screen", "log_type": "screen", "params": {"deployment_id": "local", "deployment_timestamp": "NaN", "referrer": "null", "search": ""}}
 RN   WARN  Encountered an error loading page {"canGoBack": false, "canGoForward": false, "code": -8, "description": "net::ERR_CONNECTION_TIMED_OUT", "loading": false, "target": 43, "title": "", "url": "http://192.168.0.5:5173/"}
 RN   LOG  [eventLogDebug] {"log_name": "/::screen", "log_type": "screen", "params": {"deployment_id": "local", "deployment_timestamp": "NaN", "referrer": "null", "search": ""}}

RN 로그는 위와 같이 나오는데, 흰화면이 나타나면서 계속 뭔가를 읽다가 타임아웃이 걸린 것으로 보입니다.

타임아웃 걸린 후에는 화면 상에도 Error loading page Domain: undefined 라는 문구가 보여집니다.

비슷한 오류가 발생하는 다른 게시물에서 보니 CSR이 아닐 경우 그런 현상이 발생할 수 있다고 하셨는데 현재 CSR로 구성한 상태입니다.

확인 부탁드립니다.

감사합니다.

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
샌드박스 앱 렌더링 질문 있습니다
4

감사합니다.
이런 말하기는 싫지만

앱인토스 완전 개판이네요.
빨리 안정화가 되기를 바랄 뿐입니다

1개의 좋아요
5

위 내용 공유드린 후 추가로 겪은 케이스가 있어서 덧붙입니다.

granite.config.ts의 web.host에 넣은 IP랑 실제 IP가 달라지면 마찬가지로 흰 화면 나옵니다.

이건 문서에도 기재된 당연한 체크포인트이긴 하지만 카페나 회의실 옮겨다니면서 작업하시는 분들 참고하시면 좋을 것 같아요. WiFi 바뀌면 IP도 바뀌는데 놓치기가 쉬워서요.

실기기 테스트하려면 IP를 넣어야 하는데, 이동할 때마다 ipconfig 쳐서 확인하고 수동으로 바꿔주는 게 번거로워서 저는 config에서 IP를 동적으로 가져오게 처리했습니다. (MacOS)

혹시 비슷한 고민 있으신 분은 참고하세요.

// granite.config.ts
import { defineConfig } from '@apps-in-toss/web-framework/config';
import { networkInterfaces } from 'os';

function getLocalIP(): string {
  const nets = networkInterfaces();
  for (const name of ['en0', 'eth0', 'wlan0']) {
    if (nets[name]) {
      for (const net of nets[name]) {
        if (net.family === 'IPv4' && !net.internal) {
          return net.address;
        }
      }
    }
  }
  return 'localhost';
}

export default defineConfig({
  // ...
  web: {
    host: getLocalIP(),
    port: 5173,
    // ...
  },
});

이렇게 하니까 WiFi 바꿔도 서버 재시작만 하면 알아서 잡힙니다.(로컬, 실기기 모두)

근데 config 파일에서 동적으로 로컬머신 IP 넣어줘도 괜찮을지는 모르겠어요. 일단 동작은 하는데 혹시 문제 생기면 알려주세요.

그리고 앱인토스 DX 관련해서 말씀드리자면, 아직 출시된 지 얼마 안 돼서 이해는 하는데 좀 아쉬운 부분이 있긴 하네요.

샌드박스에서 IP 불일치나 연결 실패 시 그냥 흰 화면만 나오고, WebView Safari 디버깅에서도 관련 로그가 안 보여서 원인 파악이 좀 힘들었습니다. “서버에 연결할 수 없습니다” 정도 메시지라도 있으면 삽질 시간이 많이 줄 것 같아요.

앞으로 개선되면 좋겠습니다.

6

감사합니다. 덕분에 해결되었습니다.

토스쪽에서 해결해줘야 할 문제를 임의로 버전 바꿔가면서 알아서 문제를 찾아서 해결해야되는 부분은 정말 아쉽습니다.

며칠 지난 것도 답변되지 않는 것들이 정말 많던데 또 이러한 문제들이 더 있지 않을지 걱정이 앞서네요.

1개의 좋아요
궁금한건데 문서에 호환성깨져있는건 명시하는거 쉽지않음?
7

답변을 놓쳤습니다 :cry:
현상 확인하였고, 빠르게 조치할 수 있도록 하겠습니다.
불편을 드려 죄송해요 :man_bowing:

8

TDS 2.2.1 버전에서 해결 되었습니다.
기다려주셔서 감사합니다 :man_bowing: