> 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/en/tutorials/webview.md).

# Integrating the SDK into an Existing Web Project

You can directly install the SDK in an existing web project and convert it into a mini app.

***

### 1. Install and initialize the SDK

After installing the SDK, initialize the environment.

{% 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. Edit the configuration file

When you create the project `granite.config.ts` is created automatically. `appName`, `displayName`, `icon`Please change them to match the app information registered in the Apps in Toss console.

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

export default defineConfig({
  appName: 'my-mini-app', // Enter the appName you entered in the console.
  brand: {
    displayName: 'App Name', // Enter the app name you entered in the console.
    primaryColor: '#FF91D5', // Change this to the app's main color that will be displayed on the screen.
    icon: '', // Enter the URL of the image uploaded in the console. (Right-click the uploaded image in the console's app info and copy the link, then paste it here)
  },
  web: {
    host: 'localhost',
    port: 5173,
    commands: {
      dev: 'vite dev',
      build: 'vite build',
    },
  },
  permissions: [],
  outdir: 'dist',
});
```

{% hint style="info" %}
**Important**

* `appName`is used as the **unique key**that identifies each app.
* `intoss://{appName}` It is also used for deep link paths in the form of intoss\://{appName} and during testing and deployment.
* Even when testing in the sandbox app, `intoss://{appName}`you access it with `intoss-private://{appName}`is used.
  {% endhint %}

***

### 3. Install TDS

**TDS (Toss Design System) WebView** With this package, you can easily apply components based on the Toss Design System.

{% 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 %}

For how to use TDS components and guides, [TDS WebView documentation](https://tossmini-docs.toss.im/tds-mobile/)please check it.

***

### 4. Run the project

{% 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. Run the mini app

Once the development server is running, you can view the mini app in the sandbox app. For detailed instructions on testing in the local sandbox app, [sandbox app](https://appsintoss.gitbook.io/appsintoss-docs/landing-page/development/test/sandbox) please check the documentation.

#### Accessing the development server on a physical device

To test on a physical device, when running the bundler `--host` option, and `web.host`must be set to a network address that can be accessed from the physical device.

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

export default defineConfig({
  appName: 'ping-pong',
  web: {
    host: '192.168.0.100', // Change to an IP address accessible from the physical device
    port: 5173,
    commands: {
      dev: 'vite --host', // Enable the --host option
      build: 'vite build',
    },
  },
  permissions: [],
});
```

Once the settings are complete, proceed on the physical device in the following order.

1. Refer to Install the sandbox app and install the sandbox app that matches your device.
2. Change the Metro server address in the sandbox app `web.host`to the IP address set in
3. `intoss://{appName}` Access the mini app via deep link.

***

### 6. Debugging

#### Android — Chrome DevTools

{% hint style="info" %}
**Preparation required**

To debug on a device, you must first enable USB debugging. `Settings → System → About phone → Developer options → Enable USB debugging`
{% endhint %}

1. Run the mini app on an Android emulator or physical device.
2. In the Chrome browser, `chrome://inspect/#devices` open the page.
3. Under the WebView content to debug in Remote Target **inspect** select the button.
4. You can debug WebView content just like debugging a normal web page.

#### iOS — Safari Developer Tools

{% hint style="info" %}
**Preparation required**

* You need to enable the Safari Develop menu. `Safari Preferences → Advanced tab → Enable the checkbox for Show features for web developers`
* To debug on a device, you need to enable Web Inspector. `Settings → Safari → Advanced → Enable Web Inspector`
* If the device does not appear in the Develop menu, try restarting Safari.
  {% endhint %}

1. Run the mini app on the iOS simulator or physical device.
2. Safari top menu `Developer → [Device Name] → [App Name] → [URL - Title]`select it.
3. You can debug WebView content just like debugging on the web.

***

### 7. Build and perform final testing in the Toss app

After development and basic verification in the sandbox app are complete, `npm run build`generate the app bundle, upload it to the console, and then perform final testing. You must complete testing in the Toss app before you can submit a release request. For details, please refer to [Testing in the Toss app](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/toss) documentation.

***

### 8. Release

For how to release, [Mini app release](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/deploy) documentation.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.