メインコンテンツまでスキップ

API

危険

KOS Connectはまだ開発段階です。

APIが追加、変更、削除される可能性があります。詳細については、営業担当者または開発担当者にお問い合わせください。

クリニックホームページにKOS Connectウィジェットを追加すると、来院者がホームページで特定のボタンをクリックしたりアクションを起こした際に、ウィジェットと連携できます。

以下のAPIを使用して、クリニックホームページからKOS Connectウィジェットと連携できます。

SDKの初期化​

npmパッケージをインストールして、型安全なSDKを使用できます。

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

KOSConnect.init('YOUR_APP_ID');

KOSConnect.open();
クライアント環境でのみ使用してください

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'
});
アプリID

開発環境と本番環境のアプリIDは異なります。各環境に合ったアプリIDを使用してください。

API呼び出しタイミング

SDKの初期化前にAPIを呼び出すと、初期化完了後に順次実行されます。

ウィジェットを開く​

KOSConnect.open()

閉じていたウィジェットを開きます。

  • すでに開いている場合は何も行いません。
  • ウィジェットが開いても画面や状態はリセットされません。最後に表示していた画面が維持されます。
  • 別の画面を開きたい場合は、startReserveなどの他のAPIを使用してください。

ウィジェットを閉じる​

KOSConnect.close()

開いていたウィジェットを閉じます。

  • すでに閉じている場合は何も行いません。
  • ウィジェットを閉じても画面や状態はリセットされません。再度開くと最後に表示していた画面が維持されます。

言語の変更​

KOSConnect.setLanguage(language: 'ko' | 'ja')

KOS Connectウィジェットの表示言語を変更します。

  • setLanguageを呼び出さなくても、KOS Connectはユーザーのブラウザ言語設定に基づいて自動的に言語を検出して表示します。特定の言語に強制設定が必要な場合にこのコマンドを使用してください。
  • サポートされていない言語コードが渡された場合は無視されます。

パラメータ​

language (required)​

表示する言語コードを指定します。

値説明
'ko'韓国語
'ja'日本語

タブの切り替え​

KOSConnect.changeTab({
  tab: 'schedule' | 'history' | 'myPage',
  open?: boolean
})

指定したタブに切り替えます。タブバーが表示されている初期ページでのみ動作します。

  • ウィジェットが開いていなくても、初期ページの状態であればタブが切り替わります。
  • 無効なタブ識別子が渡された場合、コマンドは無視されます。
  • 初期ページ以外の状態でopen: trueを使用すると、タブ切り替えなしでウィジェットのみ開きます。

パラメータ​

tab (required)​

切り替えるタブを指定します。

値説明
'schedule'予定
'history'履歴
'myPage'マイページ

open (optional)​

trueに設定すると、ウィジェットが閉じている場合に自動的に開きます。

  • デフォルト値はfalseです。

予約を開始する​

KOSConnect.startReserve({
  cart?: undefined
    | { type: 'consultation' }
    | { type: 'items', items: Array<{ optionId: string } | { ticketId: string }> },
  date?: Date,
  visitor?: {
    name?: string,
    phoneticName?: string,
    gender?: 'MALE' | 'FEMALE' | 'UNSPECIFIED',
    nationality?: string,
    phoneNumber?: { countryCode: string, phoneNumber: string },
    email?: string
  }
})

新規予約フローを開始します。ウィジェットが閉じている場合は自動的に開きます。

新規予約フロー​

新規予約フローは以下のステップで構成されます。

  1. 希望施術の選択
  2. 予約日時の選択
  3. 予約情報の入力
  4. 予約完了

パラメータ​

cart (optional)​

カートの初期状態を指定します。値によって開始ステップが変わります。KOS Connectのカートに入っている項目を基に予約を開始するには、cartを渡さないでください。

値開始ステップ説明
undefined希望施術の選択来院者が直接希望施術を選択するか、「カウンセリング予約」を選択します。カートに入っている項目がある場合は維持されます。
{ type: 'consultation' }予約日時の選択「カウンセリング予約」として進みます。既存のカート項目は無視されます。
{ type: 'items', items: [...] }予約日時の選択指定した項目がカートに入った状態で進みます。既存の項目は維持されます。

items配列には以下の形式を使用します。

  • { optionId: string }：施術オプションID
  • { ticketId: string }：施術券ID（今後サポート予定）

date (optional)​

予約日時選択ステップでデフォルト選択される日付を指定します。

  • 渡さない場合は本日の日付がデフォルト選択されます。
  • 時間の値は無視され、日付のみ適用されます。

visitor (optional)​

予約情報入力ステップに表示する来院者情報の初期値です。

  • 来院者がログイン済みの場合、この値は無視されます。
  • 無効な形式の値は無視されます。
フィールド型説明
namestring来院者の名前
phoneticNamestring来院者の読み仮名。日本の場合は振り仮名、韓国の場合は外国人の韓国語読み
gender'MALE' | 'FEMALE' | 'UNSPECIFIED'性別
nationalitystring国籍（ISO 3166-1 alpha-2コード）。例：'KR'、'JP'、'US'
phoneNumber{ countryCode: string, phoneNumber: string }連絡先。countryCodeは国際電話の国番号（例：'82'）、phoneNumberはハイフンなしの電話番号（例：'1012345678'）
emailstringメールアドレス

すべてのフィールドは任意です。

カートを表示する​

KOSConnect.showCart({
  open?: boolean
})

カートのボトムシートを開きます。

  • KOS Connectにカートボタンがレンダリングされている状態でのみ動作します。
  • ウィジェットが閉じている状態でopen: trueを使用すると、ウィジェットを開いてカートのボトムシートを表示します。

パラメータ​

open (optional)​

trueに設定すると、ウィジェットが閉じている場合に自動的に開きます。

  • デフォルト値はfalseです。

カートに追加する​

KOSConnect.addToCart({
  options: [{ id: string }],
  silent?: boolean
})

指定した施術オプションをカートに追加します。

  • ログインしていない状態でもカートに追加できます。
  • ウィジェットが閉じていてもカートのみ更新されます。ウィジェットは自動的に開きません。
  • デフォルトではトースト通知が表示されます。silent: trueで非表示にできます。
  • すでに追加されているオプションIDは重複して追加されません。
  • 無効なオプションIDは無視され、有効な項目のみ反映されます。

カートから削除する​

KOSConnect.removeFromCart({
  options: [{ id: string }],
  silent?: boolean
})

指定した施術オプションをカートから削除します。

  • ログインしていない状態でも使用できます。
  • ウィジェットが閉じていてもカートのみ更新されます。ウィジェットは自動的に開きません。
  • デフォルトではトースト通知が表示されます。silent: trueで非表示にできます。
  • カートにないオプションIDは無視されます。

カートをリセットする​

KOSConnect.resetCart()

カートに入っているすべての施術オプションを削除します。

  • ログインしていない状態でも使用できます。
  • ウィジェットが閉じていてもカートのみ更新されます。ウィジェットは自動的に開きません。
  • カートがすでに空の場合は何も行いません。

イベントの購読​

まだ使用できません

この機能は現在開発中であり、まだ使用できません。

イベントの詳細

各イベントの正確な発行タイミング、GA4マッピング、クリニックGA/GTM連携方法は分析イベントドキュメントをご参照ください。

KOSConnect.on(type: ConnectEventType, handler: (payload) => void)

KOS Connect内部で発生するイベントを購読します。同一のイベントに複数のハンドラーを登録できます。

パラメータ​

type (required)​

購読するイベントタイプを指定します。

イベント説明ペイロード
'procedureListViewed'施術リスト表示{ category?: { id, name }, items: ProductEventItem[] }
'procedureViewed'施術詳細表示{ item: ProductEventItem }
'cartItemAdded'カートに項目追加{ items: ProductEventItem[] }
'cartItemRemoved'カートから項目削除{ items: ProductEventItem[] }
'cartReset'カートリセット{}
'registerStarted'来院者登録開始{}
'registerCompleted'来院者登録完了{ visitorId, nationality, gender }
'checkoutStarted'予約チェックアウト開始{ items: ProductEventItem[], totalValue, currency }
'dateTimeSelected'予約日時選択{ dateTime }
'reservationCompleted'予約完了{ reservationId, items: ProductEventItem[], totalValue, currency }
'reservationCancelled'予約キャンセル{ reservationId, items: ProductEventItem[], totalValue, currency }
'widgetPageView'ウィジェット内ページ遷移{ pagePath, pageTitle, previousPath? }

handler (required)​

イベント発生時に呼び出されるコールバック関数です。イベントタイプに応じたペイロードを引数として受け取ります。

使用例​

KOSConnect.on('reservationCompleted', (payload) => {
  console.log('予約完了:', payload.reservationId);
});

KOSConnect.on('cartItemAdded', (payload) => {
  console.log('カート追加:', payload.items);
});

イベントの購読解除​

KOSConnect.off(type: ConnectEventType, handler: (payload) => void)

onで登録したイベントハンドラーを解除します。

  • onに渡したものと同一の関数参照を渡す必要があります。
  • 登録されていないハンドラーを渡した場合は何も行いません。

パラメータ​

type (required)​

購読を解除するイベントタイプを指定します。onで使用可能なイベントタイプと同一です。

handler (required)​

解除するハンドラー関数です。onに渡したものと同一の参照である必要があります。

使用例​

const handler = (payload) => {
  console.log('予約完了:', payload.reservationId);
};

KOSConnect.on('reservationCompleted', handler);

// 購読解除
KOSConnect.off('reservationCompleted', handler);