# Add A Widget To A Clinic Website :::danger **KOS Connect is still in development.** - Installation and control APIs may be added, changed, or removed. - Contact the KOS sales or development representative responsible for the clinic. ::: Embedding the KOS Connect widget into a clinic website lets visitors book directly from the site. This guide covers installation, basic control, and the integration details that are easiest to miss. You can see the widget in the [demo site](https://clinic-demo.dev.kos-solution.com/). ## Install Use the npm package when your website is built with React or TypeScript and you want typed APIs. ```sh title="npm" icon="npm" npm install @kos-solution/connect-sdk ``` ```sh title="yarn" icon="yarn" yarn add @kos-solution/connect-sdk ``` ```sh title="pnpm" icon="pnpm" pnpm add @kos-solution/connect-sdk ``` ```sh title="bun" bun add @kos-solution/connect-sdk ``` ```typescript import KOSConnect from '@kos-solution/connect-sdk'; KOSConnect.init('YOUR_APP_ID'); ``` :::tip{title="Getting an appId"} If you do not have an `appId`, contact the clinic's KOS sales representative. ::: :::warning{title="Use only in the browser"} `KOSConnect.init()` injects a script tag internally to load the widget. It does not work in Server Components or SSR execution. In Next.js, call it from a client component. ```tsx 'use client'; import { useEffect } from 'react'; import KOSConnect from '@kos-solution/connect-sdk'; export default function KOSConnectInit() { useEffect(() => { KOSConnect.init('YOUR_APP_ID'); }, []); return null; } ``` ::: Use `baseUrl` in development. ```typescript KOSConnect.init('YOUR_DEV_APP_ID', { baseUrl: 'https://connect.kos-solution.dev', }); ``` Add this script near the end of the clinic website's ``. ```html ``` Replace `YOUR_APP_ID` with the issued appId. :::tip{title="Getting an appId"} If you do not have an `appId`, contact the clinic's KOS sales representative. ::: Use the development URL in development environments. ```html ``` ## Control The Widget The clinic website can control the widget when a visitor clicks a button or takes another action. See the [KOS Connect API](/en/docs/connect/api) for the full command list. ### Example: Open The Widget From A Button ```tsx import KOSConnect from '@kos-solution/connect-sdk'; ``` ```html ``` ```jsx ``` ### Example: Open A Specific Tab Use `changeTab` when the site has separate buttons such as "Book now" and "My Page". ```tsx KOSConnect.changeTab({ tab: 'schedule', open: true }); KOSConnect.changeTab({ tab: 'myPage', open: true }); ``` ### Example: Add An Option To The Cart If the clinic site renders its own product list with OpenAPI, pass the selected product option ID to Connect. ```tsx import KOSConnect from '@kos-solution/connect-sdk'; ``` ```html ``` ```jsx ``` :::warning{title="Pass option IDs, not product IDs"} `addToCart` expects product option IDs. If you build the product list with OpenAPI, keep both product ID and option ID, then pass the option ID to Connect. ::: ## Language KOS Connect can detect the browser language automatically. If the clinic website has its own locale switcher and you need to force the widget language, call `setLanguage`. ```tsx KOSConnect.setLanguage('ko'); KOSConnect.setLanguage('ja'); ``` Only supported language codes are applied. Unsupported values are ignored. ## Widget Settings The following settings can be configured. | Setting | Default | Description | | --- | --- | --- | | Color | - | Applies the clinic brand color to the widget button and primary actions. | | Button label | Book | Text displayed on the widget opener button. The label can also be hidden. | | Position | Bottom right | Choose bottom left or bottom right. | | Margin | - | Horizontal and vertical margins for the widget opener button. | Contact the KOS team to change widget settings. ## Track Acquisition With UTM Parameters The widget automatically reads UTM parameters from the clinic website URL. If a visitor lands on the website with UTM parameters and books through the widget, the acquisition source is recorded in KOS. ```text https://kos-demo.clinic?utm_source=instagram&utm_medium=profile_link&utm_campaign=march_spring_event ``` KOS Connect supports these UTM parameters. | UTM parameter | Field recorded in KOS | Description | Example | | --- | --- | --- | --- | | `utm_source` | Acquisition channel category | Traffic source | `instagram`, `kakao`, `naver` | | `utm_medium` | Acquisition channel | Medium | `profile_link`, `message`, `qr_code` | | `utm_campaign` | Acquisition channel detail | Campaign name | `march_spring_event`, `friend_referral`, `waiting_room_sign` | :::tip{title="UTM parameter builder"} You can use [Google Campaign URL Builder](https://ga-dev-tools.google/campaign-url-builder/) to generate URLs with UTM parameters. ::: ## Integration Checklist - Use the npm package for React/TypeScript projects when possible. - Use the Script tag path when only HTML insertion is available. - Run `KOSConnect.init()` only in the browser. - Keep development and production appIds separate. - Use `baseUrl: 'https://connect.kos-solution.dev'` only for development appIds. - If your own product UI uses OpenAPI, pass product option IDs to `addToCart`. - If your site has locale switching, call `setLanguage` after initialization. - Add UTM parameters to campaign landing URLs before sharing them. ## Next Step Read the [KOS Connect API](/en/docs/connect/api) to control the widget with additional commands.