WebView 개발하기

준비가 필요해요

프로젝트를 스캐폴딩하고 서비스를 실행하려면 환경설정이 필요해요. 아래 가이드를 먼저 확인해 주세요.

• iOS 환경설정 문서 바로가기
• Android 환경설정 문서 바로가기

기존 웹 프로젝트에 @apps-in-toss/web-framework를 설치하면 앱인토스 샌드박스에서 바로 개발하고 배포할 수 있어요.

설치하기

기존 웹 프로젝트에 아래 명령어 중 사용하는 패키지 매니저에 맞는 명령어를 실행하세요.

npm

npm install @apps-in-toss/web-framework

pnpm

pnpm install @apps-in-toss/web-framework

yarn

yarn add @apps-in-toss/web-framework

환경 구성하기

ait init 명령어를 실행해 환경을 구성할 수 있어요.

1. ait init 명령어를 실행하세요.

npm

npx ait init

pnpm

pnpm ait init

yarn

yarn ait init

Cannot set properties of undefined (setting 'dev') 오류가 발생한다면?

package.json scripts 필드의 dev 필드에, 원래 사용하던 번들러의 개발 모드를 띄우는 커맨드를 입력 후 다시 시도해주세요.

2. web-framework를 선택하세요.
3. appName을 입력하세요.

• appName은 앱인토스 콘솔에서 앱을 생성할 때 지정한 이름이에요.
• 앱인토스 콘솔에서 확인할 수 있어요.

4. 웹 개발 서버에서 사용할 포트 번호를 입력하세요.

생성된 파일 확인하기

설정을 완료하면 다음과 같은 bedrock.config.ts 파일이 생성돼요.

bedrock.config.ts

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

export default defineConfig({
  appName: 'ping-pong', // 앱인토스 콘솔에서 설정한 앱 이름
  brand: {
    displayName: '%%appName%%', // 화면에 노출될 앱의 한글 이름으로 바꿔주세요.
    primaryColor: '#3182F6', // 화면에 노출될 앱의 기본 색상으로 바꿔주세요.
    icon: null, // 화면에 노출될 앱의 아이콘 이미지 주소로 바꿔주세요.
    bridgeColorMode: 'basic',
  },
  web: {
    host: 'localhost', // 앱 내 웹뷰에 사용될 host
    port: 5173,
    commands: {
      dev: 'vite', // 개발 모드 실행 (webpack serve도 가능)
      build: 'vite build', // 빌드 명령어 (webpack도 가능)
    },
  },
  permissions: [],
  webViewProps: {
    type: 'partner',
  },
});

• brand: 앱 브랜드와 관련된 구성이에요.
  • displayName: 브릿지 뷰에 표시할 앱 이름이에요.
  • icon: 앱 아이콘 이미지 주소예요. 사용자에게 앱 브랜드를 전달해요.
  • primaryColor: Toss 디자인 시스템(TDS) 컴포넌트에서 사용할 대표 색상이에요. RGB HEX 형식(eg. #3182F6)으로 지정해요.
  • bridgeColorMode: 브릿지 뷰의 배경 색상 유형이에요. 흰 배경인 basic 또는 검은 배경인 inverted 중 하나를 선택할 수 있어요.
• web.commands.dev 필드는 bedrock dev 명령어 실행 시 함께 실행할 명령어예요. 번들러의 개발 모드를 시작하는 명령어를 입력해주세요.
• web.commands.build 필드는 bedrock build 명령어 실행 시 함께 실행할 명령어예요. 번들러의 빌드 명령어를 입력해주세요.
• webViewProps.type 옵션에는 아래 세 가지 값 중 하나를 설정할 수 있어요.
  • partner: 파트너사 콘텐츠에 사용하는 기본 웹뷰예요. 다른 값을 설정하지 않으면 이 값이 기본으로 사용돼요.
  • external: 웹뷰 내부에서 자체 네비게이션(탭, 헤더 등)을 갖고 있는 콘텐츠에 적합해요.
  • game: 전체 화면을 사용하는 게임 콘텐츠처럼, 가득 찬 영역이 필요한 경우 사용해요.

웹 빌드 시 주의사항

bedrock build를 실행하면 web.commands.build가 실행되고, 이 과정에서 생성된 결과물을 바탕으로 .ait 파일을 만들어요. web.commands.build의 결과물은 bedrock.config.ts의 outdir 경로와 같아야 해요.

outdir의 기본값은 프로젝트 경로의 dist 폴더지만, 필요하면 bedrock.config.ts에서 수정할 수 있어요. 만약 빌드 결과물이 outdir과 다른 경로에 저장되면 배포가 정상적으로 이루어지지 않을 수 있으니 주의하세요.

개발 모드 사용하기

개발 모드를 실행하면 웹 개발 서버와 React Native 개발 서버가 함께 실행돼요. 웹 개발 서버는 bedrock.config.ts 파일의 web.commands.dev 필드에 설정한 명령어를 사용해 실행돼요.

또, HMR(Hot Module Replacement)을 지원해서 코드 변경 사항을 실시간으로 반영할 수 있어요.

다음은 개발 서버를 실행하는 명령어에요.

npm

npx bedrock dev

pnpm

pnpm bedrock dev

yarn

yarn bedrock dev

Android에서 웹 로컬 서버에 접속하는 방법

Android 기기에서 웹 로컬 서버에 접속하려면 포트를 연결해야 해요. 아래 명령어를 실행해서 React Native 서버와 웹 서버의 포트 모두 허용하세요.

# 기기가 한 대만 연결된 경우
adb reverse tcp:{웹 포트} tcp:{웹 포트}
adb reverse tcp:{React Native 포트} tcp:{React Native 포트}

# 예제
adb reverse tcp:5173 tcp:5173
adb reverse tcp:8081 tcp:8081

# 여러 대의 기기가 연결된 경우 (기기 시리얼 번호 지정)
adb -s <시리얼번호> reverse tcp:{웹 포트} tcp:{웹 포트}
adb -s <시리얼번호> reverse tcp:{React Native 포트} tcp:{React Native 포트}

# 예제
adb -s R3CTA0BMCPG reverse tcp:5173 tcp:5173
adb -s R3CTA0BMCPG reverse tcp:8081 tcp:8081

실기기에서 개발 모드 사용하기

실기기에서 테스트하려면 번들러를 실행할 때 --host 옵션을 활성화하고, web.host를 실 기기에서 접근할 수 있는 네트워크 주소로 설정해야 해요.

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

export default defineConfig({
  appName: "ping-pong",
  web: {
    host: "192.168.0.100", // 실 기기에서 접근할 수 있는 IP 주소로 변경
    port: 5173,
    commands: {
      dev: "vite --host", // --host 옵션 활성화
      build: "vite build",
    },
  },
  permissions: [],
});

번들 파일 생성하기

번들 파일은 .ait 확장자를 가진 파일로, 빌드된 프로젝트를 패키징한 결과물이에요. 이를 생성하려면 아래 명령어를 실행하세요.

npm

npm run build

pnpm

pnpm build

yarn

yarn build

위 명령어를 실행하면 프로젝트 루트 디렉터리에 <서비스명>.ait 파일이 생성돼요. 해당 파일은 앱을 출시할 때 사용해요.

출시하기

출시하는 방법은 앱 출시하기문서를 참고하세요.