> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/ai-vibe-coding/tutorials/webview.md).

# 기존 웹 프로젝트에 SDK 연동하기

이미 운영 중인 웹 프로젝트에 SDK를 직접 설치해 미니앱으로 전환할 수 있어요.

***

### 1. SDK 설치 및 초기화하기

SDK를 설치한 뒤 환경을 초기화해 주세요.

{% tabs %}
{% tab title="npm" %}

```sh
npm install @apps-in-toss/web-framework
npx ait init
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm add @apps-in-toss/web-framework
pnpm ait init
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn add @apps-in-toss/web-framework
yarn ait init
```

{% endtab %}
{% endtabs %}

***

### 2. 설정 파일 수정하기

프로젝트를 초기화하면 `apps-in-toss.config.ts` 파일이 자동으로 만들어져요. \
`appName`을 앱인토스 콘솔에 등록한 앱 정보와 동일하게 수정해 주세요. 

`appName`이 등록한 앱 정보와 다르면 콘솔에 업로드할 수 없어요.

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

export default defineConfig({
  appName: "webview-app",
  brand: {
    // 화면에 노출될 앱의 기본 색상으로 바꿔주세요.
    primaryColor: "#E0B20C"
  },

  webView: {
  },
  permissions: [
    { name: "microphone", access: "access" },
    { name: "photos", access: "read" },
  ],
  webBundleDir: "dist",
});

```

{% hint style="info" %}
**중요해요**

* `appName`은 각 앱을 식별하는 **고유한 키**로 사용돼요.
* `intoss://{appName}` 형태의 딥링크 경로나 테스트·배포 시에도 사용돼요.
* 출시하기 메뉴의 QR 코드로 테스트할 때는 `intoss-private://{appName}`이 사용돼요.
  {% endhint %}

***

### 3. TDS 설치하기

**TDS(Toss Design System) WebView** 패키지를 사용하면 토스 디자인 시스템 기반의 컴포넌트를 쉽게 적용할 수 있어요.

{% tabs %}
{% tab title="npm" %}

```sh
npm install @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm add @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn add @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18
```

{% endtab %}
{% endtabs %}

TDS 컴포넌트 사용법과 가이드는 [TDS WebView 문서](https://tossmini-docs.toss.im/tds-mobile/)를 확인해 주세요.

***

### 4. 프로젝트 실행하기

{% tabs %}
{% tab title="npm" %}

```sh
npm run dev
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm run dev
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn dev
```

{% endtab %}
{% endtabs %}

***

### 5. 미니앱 실행하기

개발 서버가 실행되면 로컬 브라우저에서 미니앱을 확인할 수 있어요. 

오른쪽 아래 `AIT` 버튼으로 다양한 환경으로 미리 테스트해 볼 수 있어요.

<figure><img src="https://937761732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNbJTp2UkOUSb6YpQegOx%2Fuploads%2F0Tf7m656kusF2e7q8KN6%2Fimage.png?alt=media&amp;token=65520027-7a84-4b91-b7d9-19740769635a" alt=""><figcaption></figcaption></figure>

***

### 6. 빌드하고 토스앱에서 최종 테스트하기

샌드박스 앱에서 개발과 기본 검증이 끝나면 `npm run build`로 앱 번들을 생성한 뒤, 콘솔에 업로드해 최종 테스트를 진행해 주세요.&#x20;

토스앱 테스트를 완료해야 출시 요청을 보낼 수 있어요. 자세한 방법은 [토스앱 테스트하기](/guide/operation/toss.md) 문서를 참고해 주세요.

***

### 7. 출시하기

출시하는 방법은 [미니앱 출시](/guide/operation/deploy.md) 문서를 참고해 주세요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers-apps-in-toss.toss.im/ai-vibe-coding/tutorials/webview.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.