본문으로 건너뛰기

병원 홈페이지에 위젯 추가하기

위험

KOS Connect는 아직 개발 단계입니다.

  • 위젯 설치 방법, 제어 방법 등이 추가되거나, 사용하고 있던 API가 제거되거나 변경될 수 있습니다.
  • 병원을 담당하고 있는 코스 팀의 영업 담당자 혹은 개발 담당자에게 문의해주세요.

병원 홈페이지에 KOS Connect 위젯을 삽입하면 내원객이 홈페이지에서 바로 예약할 수 있습니다. 이 문서에서는 위젯 설치, 제어, 설정 방법을 안내합니다.

데모 사이트에서 위젯이 적용된 모습을 확인할 수 있습니다.

설치하기​

npm 패키지를 설치하여 타입 안전한 SDK를 사용할 수 있습니다.

npm install @kos-solution/connect-sdk
import KOSConnect from '@kos-solution/connect-sdk';

// appId로 초기화
KOSConnect.init('YOUR_APP_ID');
appId 발급

appId가 없다면 영업 담당자에게 문의하여 발급받으세요.

클라이언트 환경에서만 사용하세요

KOSConnect.init()은 내부적으로 <script> 태그를 주입하여 위젯을 로드합니다. Server Component나 SSR 환경에서는 동작하지 않으므로, 반드시 클라이언트 환경에서 호출하세요.

'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;
}

개발 환경에서는 baseUrl 옵션을 사용하세요.

KOSConnect.init('YOUR_DEV_APP_ID', {
  baseUrl: 'https://connect.dev.kos-solution.com'
});

위젯 제어하기​

병원 홈페이지에서 버튼 클릭이나 사용자 행동에 따라 위젯을 제어할 수 있습니다. 자세한 내용은 KOS Connect API 문서를 참고하세요.

예시: 버튼 클릭 시 위젯 열기​

import KOSConnect from '@kos-solution/connect-sdk';

<button onClick={() => KOSConnect.open()}>위젯 열기</button>

예시: 장바구니에 옵션 추가하기​

import KOSConnect from '@kos-solution/connect-sdk';

<button onClick={() => KOSConnect.addToCart({
  options: [{ id: '694b7805e2e5b0c20f4aaa0a' }]
})}>
  보톡스 예약하기
</button>

위젯 설정하기​

다음 항목을 설정할 수 있습니다.

항목기본값설명
색상-병원 브랜드 색상을 적용합니다. 위젯 열기 버튼과 주요 버튼에 사용됩니다.
버튼 라벨예약하기위젯 열기 버튼에 표시할 텍스트입니다. 라벨을 숨길 수도 있습니다.
위치우하단좌하단 또는 우하단 중 선택합니다.
여백-위젯 열기 버튼의 가로/세로 여백을 설정합니다.

설정을 변경하려면 코스팀에 문의하세요.

UTM 파라미터로 유입 경로 추적하기​

위젯은 병원 홈페이지 URL에 포함된 UTM 파라미터를 자동으로 인식합니다. 내원객이 UTM 파라미터가 포함된 링크로 홈페이지에 접속한 후 위젯을 통해 예약하면, 해당 유입 경로가 코스에 자동으로 기록됩니다.

예를 들어, 내원객이 아래 URL로 홈페이지에 접속한 후 위젯으로 예약하면 유입 경로가 기록됩니다.

https://kos-demo.clinic?utm_source=인스타그램&utm_medium=프로필_링크&utm_campaign=3월_봄_이벤트

KOS Connect는 다음 3가지 UTM 파라미터를 지원합니다.

UTM 파라미터KOS에 기록되는 필드설명예시
utm_source유입채널카테고리트래픽 출처인스타그램, 카카오, 네이버
utm_medium유입채널매체 유형프로필_링크, 메시지, QR코드
utm_campaign상세유입채널캠페인명3월_봄_이벤트, 친구_추천, 대기실_안내
UTM 파라미터 생성 도구

Google Campaign URL Builder를 사용하면 UTM 파라미터가 포함된 URL을 쉽게 생성할 수 있습니다.

다음 단계​

KOS Connect API 문서에서 위젯을 제어하는 다양한 방법을 확인하세요.