> 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 into an existing web project and convert it into a mini app.

***

### 1. Install and initialize the SDK

After installing the SDK, please 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` file is created automatically. `appName`, `displayName`, `icon`Please change it 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', // Please change this to the app's primary 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 app information in the console 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 to identify each app **unique key**is used as.
* `intoss://{appName}` It is also used for deep link paths in the form of, and during testing and deployment.
* When testing in the sandbox app as well `intoss://{appName}`access it via. However, when testing with the QR code in the Release menu, `intoss-private://{appName}`is used.
  {% endhint %}

***

### 3. Install TDS

**TDS (Toss Design System) WebView** By using the 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 instructions on using TDS components and guides, [TDS WebView documentation](https://tossmini-docs.toss.im/tds-mobile/)please check.

***

### 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 check 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` enable the 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, please proceed on the physical device in the following order.

1. Refer to Install the sandbox app and install the sandbox app appropriate for your device.
2. In the sandbox app, change the Metro server address `web.host`to the IP address you set.
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 you want to debug in Remote Target **inspect** click the button.
4. You can debug WebView content just like a regular web page.

#### iOS — Safari Developer Tools

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

* You need to enable the Safari Developer menu. `Safari Preferences → Advanced tab → Enable the checkbox for Show features for web developers`
* To debug on a device, you must 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 an iOS simulator or physical device.
2. Safari top menu `Develop → [device name] → [app name] → [URL - title]`select it.
3. You can debug WebView content just like you debug on the web.

***

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

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

***

### 8. Release

To release, [Mini app release](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/deploy) please refer to the 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.