Setting API

해당 api를 사용할 경우 설정 -> 외부서비스 설정 하위의 설정 페이지를 만들고 유저가 입력한 값을 조회할 수 있어요.

Types

PluginInputType

플러그인 입력 타입을 나타내는 유니온 타입이에요.

type PluginInputType =
  | 'text'
  | 'number'
  | 'password'
  | 'radio'
  | 'checkbox'
  | 'toggle'
  | 'slider';

BaseInput

모든 입력 타입의 기본 속성을 정의하는 객체예요.

type BaseInput = {
  label: string; // 입력 필드 라벨
  required: boolean; // 필수 입력 여부
  id: string; // 입력 필드 ID
};

TextInput

텍스트 입력 필드를 정의하는 타입이에요.

export type TextInput = BaseInput & {
  type: 'text';
  default: string; // 기본값
  placeholder?: string; // 플레이스홀더
  suffix?: string; // 입력 필드 오른쪽에 붙는 단위 텍스트
  candidates?: { text: string; value: string }[]; // 선택지. 고르면 입력 필드가 자동으로 채워짐
};

필드	타입	필수	설명	예시
label	string	필수	입력 필드 라벨	'API 키'
required	boolean	필수	필수 입력 여부	true
id	string	필수	입력 필드 ID	'api_key'
type	'text'	필수	입력 타입	'text'
default	string	필수	기본값	'default_value'
placeholder	string	선택	플레이스홀더	'API 키를 입력하세요'
suffix	string	선택	입력 필드 오른쪽에 붙는 단위 텍스트	'원'
candidates	{ text: string; value: string }[]	선택	선택지. 유저가 하나를 고르면 입력 필드가 자동으로 채워져요	[{ text: '기본값', value: 'default' }]

PasswordInput

비밀번호 입력 필드를 정의하는 타입이에요.

export type PasswordInput = BaseInput & {
  type: 'password';
  default: string; // 기본값
  placeholder?: string; // 플레이스홀더
};

필드	타입	필수	설명	예시
label	string	필수	입력 필드 라벨	'비밀번호'
required	boolean	필수	필수 입력 여부	true
id	string	필수	입력 필드 ID	'password'
type	'password'	필수	입력 타입	'password'
default	string	필수	기본값	''
placeholder	string	선택	플레이스홀더	'비밀번호를 입력하세요'

NumberInput

숫자 입력 필드를 정의하는 타입이에요.

type NumberInput = BaseInput & {
  type: 'number';
  default: number; // 기본값
  placeholder?: string; // 플레이스홀더
  suffix?: string; // 입력 필드 오른쪽에 붙는 단위 텍스트
  candidates?: { text: string; value: number }[]; // 선택지. 고르면 입력 필드가 자동으로 채워짐
};

필드	타입	필수	설명	예시
label	string	필수	입력 필드 라벨	'타임아웃'
required	boolean	필수	필수 입력 여부	true
id	string	필수	입력 필드 ID	'timeout'
type	'number'	필수	입력 타입	'number'
default	number	필수	기본값	3000
placeholder	string	선택	플레이스홀더	'밀리초 단위로 입력하세요'
suffix	string	선택	입력 필드 오른쪽에 붙는 단위 텍스트	'ms'
candidates	{ text: string; value: number }[]	선택	선택지. 유저가 하나를 고르면 입력 필드가 자동으로 채워져요	[{ text: '3초', value: 3000 }]

InputValue

선택 옵션의 값을 정의하는 타입이에요.

type InputValue = {
  id: string; // 옵션 ID
  label: string; // 옵션 라벨
};

RadioInput

라디오 버튼 입력 필드를 정의하는 타입이에요.

type RadioInput = Omit<BaseInput, 'placeholder'> & {
  type: 'radio';
  default: string; // 선택된 value의 id
  values: InputValue[]; // 선택 옵션 목록
};

필드	타입	필수	설명	예시
label	string	필수	입력 필드 라벨	'결제 방식'
required	boolean	필수	필수 입력 여부	true
id	string	필수	입력 필드 ID	'payment_method'
type	'radio'	필수	입력 타입	'radio'
default	string	필수	선택된 value의 id	'card'
values	InputValue[]	필수	선택 옵션 목록	[{ id: 'card', label: '카드' }]

CheckBoxInput

체크박스 입력 필드를 정의하는 타입이에요.

type CheckBoxInput = Omit<BaseInput, 'placeholder'> & {
  type: 'checkbox';
  default: string[]; // 선택된 value의 id의 배열
  values: InputValue[]; // 선택 옵션 목록
};

필드	타입	필수	설명	예시
label	string	필수	입력 필드 라벨	'알림 설정'
required	boolean	필수	필수 입력 여부	false
id	string	필수	입력 필드 ID	'notification_settings'
type	'checkbox'	필수	입력 타입	'checkbox'
default	string[]	필수	선택된 value의 id의 배열	['email', 'sms']
values	InputValue[]	필수	선택 옵션 목록	[{ id: 'email', label: '이메일' }]

ToggleInput

토글 입력 필드를 정의하는 타입이에요.

type ToggleInput = Omit<BaseInput, 'placeholder'> & {
  type: 'toggle';
  default: boolean; // 기본값
};

필드	타입	필수	설명	예시
label	string	필수	입력 필드 라벨	'자동 저장'
required	boolean	필수	필수 입력 여부	false
id	string	필수	입력 필드 ID	'auto_save'
type	'toggle'	필수	입력 타입	'toggle'
default	boolean	필수	기본값	true

SliderInput

슬라이더 입력 필드를 정의하는 타입이에요.

type SliderInput = Omit<BaseInput, 'placeholder'> & {
  type: 'slider';
  default: number; // 기본값
  min: number; // 최소값
  max: number; // 최대값
  step: number; // 단계값
};

필드	타입	필수	설명	예시
label	string	필수	입력 필드 라벨	'음량'
required	boolean	필수	필수 입력 여부	false
id	string	필수	입력 필드 ID	'volume'
type	'slider'	필수	입력 타입	'slider'
default	number	필수	기본값	50
min	number	필수	최소값	0
max	number	필수	최대값	100
step	number	필수	단계값	5

PluginInputs

플러그인 설정 입력 필드의 유니온 타입이에요.

export type PluginInputs =
  | TextInput
  | NumberInput
  | PasswordInput
  | RadioInput
  | CheckBoxInput
  | ToggleInput
  | SliderInput;

Methods

setInputs

input을 이용해 설정화면을 만들어요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

await posPluginSdk.setting.setInputs([
  {
    label: 'ID',
    type: 'text',
    required: true,
    placeholder: 'ID',
    default: '',
    id: 'id',
  },
  {
    label: '비밀번호',
    type: 'password',
    required: true,
    placeholder: '비밀번호',
    default: '',
    id: 'password',
  },
]);

Parameters

파라미터	타입	필수	설명
inputs	PluginInputs[]	O	설정 화면에 표시할 입력 필드 목록. 배열 순서대로 화면에 나와요

Response

반환값이 없어요.

getValues

setInputs를 이용해 설정화면을 만들고 유저가 입력한 값을 불러와요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

const values = await posPluginSdk.setting.getValues();
console.log('id', values.id);
console.log('password', values.password);

Parameters

파라미터가 없어요.

Response

Promise<Record<string, string | number | string[] | boolean | undefined>> — 유저가 입력한 값이에요. setInputs로 등록한 입력 필드의 id가 키가 돼요.

입력 타입	값의 타입
text, password	string
number, slider	number
radio	string — 선택된 values의 id
checkbox	string[] — 선택된 values의 id 배열
toggle	boolean

타입 파라미터로 반환 타입을 좁힐 수 있어요.

const values = await posPluginSdk.setting.getValues<{ id: string; password: string }>();

on

설정 값이 변경되었을 때 실행할 콜백을 등록해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

posPluginSdk.setting.on('change', () => {
  // 변경된 값을 다시 읽어오는 로직
});

Parameters

파라미터	타입	필수	설명
event	'change'	O	구독할 이벤트. 현재 'change'만 지원해요
callback	() => void	O	설정 값이 변경되면 실행돼요. 변경된 값은 getValues로 조회해요

Response

반환값이 없어요.