React SDK 레퍼런스

Moss React SDK는 강력한 AI 어시스턴트를 웹 애플리케이션에 통합하기 위한 React 컴포넌트와 훅 세트를 제공합니다. 상태 관리, 백엔드와의 통신, UI 렌더링을 모두 처리하며, 스타일 충돌을 방지하기 위해 Shadow DOM 내에 캡슐화되어 있습니다.

설치

GitHub 패키지 레지스트리에서 SDK 패키지를 설치합니다. GitHub 패키지로 인증되었는지 확인하세요.

npm install @principles-first/moss-sdk

`AgentProvider`

AgentProvider는 SDK의 핵심 컴포넌트입니다. 컨텍스트를 설정하고 백엔드와의 연결을 관리하며, 어시스턴트를 사용하려는 애플리케이션 부분을 감싸야 합니다.

사용법

config.js

import React from 'react';
import { AgentProvider, FloatingActionBar, MossSDKConfig, LogLevel } from '@principles-first/moss-sdk';

const config: MossSDKConfig = {
  apiUrl: 'http://localhost:8000', // 백엔드 API URL
  applicationName: 'your-app-name',
  userId: 'user-123',
  debugMode: true,
};

function App() {
  return (
    <AgentProvider config={config}>
      <YourAppContent />
      <FloatingActionBar />
    </AgentProvider>
  );
}

설정 (`MossSDKConfig`)

AgentProvider는 다음 속성을 가진 config 객체를 받습니다:

apiUrl

string

required

백엔드 에이전트 서비스의 기본 HTTP URL입니다.

applicationName

string

required

SDK를 통합하는 클라이언트 애플리케이션의 고유 식별자입니다.

userId

string

required

애플리케이션 내 최종 사용자의 고유 식별자입니다.

apiKey

string

백엔드 서비스 인증을 위한 선택적 API 키입니다.

observeTargetSelector

string

default:"'body'"

DOM 변경을 관찰할 루트 요소의 CSS 선택자입니다.

logLevel

enum

SDK 내부 로거의 최소 로그 레벨을 설정합니다. LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, LogLevel.ERROR, 또는 LogLevel.SILENT가 될 수 있습니다.

debugMode

boolean

default:"false"

SDK에서 디버그 기능을 활성화하거나 비활성화합니다.

screenshotMode

enum

default:"'fullpage'"

비전 기능이 활성화되었을 때 스크린샷 캡처 모드를 제어합니다. 'fullpage' 또는 'viewport'가 될 수 있습니다.

stability

StabilityConfig

DOM 안정성 감지 전략에 대한 설정입니다. 아래의 StabilityConfig 섹션을 참조하세요.

pageSanitizationScript

(document: Document) => void

컨텍스트 캡처 전에 DOM을 정리하기 위해 실행되는 선택적 함수입니다. AI를 혼란스럽게 할 수 있는 요소를 제거하거나 수정하는 데 사용합니다.

language

enum

SDK UI의 고정 언어를 설정합니다. 지원되는 값은 'en'과 'ko'입니다. 제공되지 않으면 언어가 자동으로 감지됩니다.

`useAgent` 훅

useAgent 훅은 SDK의 상태 및 핵심 기능에 대한 접근을 제공합니다. AgentProvider의 자식인 컴포넌트 내에서 사용해야 합니다.

사용법

import { useAgent } from '@principles-first/moss-sdk';

const MyComponent = () => {
  const { isChatOpen, toggleChat, sendMessage } = useAgent();

  return (
    <button onClick={toggleChat}>
      {isChatOpen ? '채팅 닫기' : '채팅 열기'}
    </button>
  );
};

반환 값 (`AgentState`)

이 훅은 다음 속성을 가진 AgentState 객체를 반환합니다:

isConnected

boolean

SDK가 백엔드에 성공적으로 연결되었는지 여부를 나타냅니다.

isChatOpen

boolean

메인 채팅 모달이 현재 열려 있는지 여부를 나타냅니다.

messages

ChatMessage[]

현재 세션의 채팅 메시지 배열입니다.

sendMessage

(text: string) => Promise<void>

사용자로부터 어시스턴트에게 메시지를 보내는 함수입니다.

toggleChat

() => void

채팅 모달을 열거나 닫는 함수입니다.

startNewChat

() => Promise<void>

현재 세션을 지우고 새 세션을 시작하는 함수입니다.

isWaitingForResponse

boolean

SDK가 현재 백엔드로부터 응답을 기다리고 있는지 여부를 나타냅니다.

useVision

boolean

현재 애플리케이션에 비전 기반 기능이 활성화되어 있는지 여부를 나타냅니다.

컴포넌트

SDK에는 빠른 설정을 위한 사전 빌드된 컴포넌트가 포함되어 있습니다.

`FloatingActionBar`

메인 어시스턴트 버튼을 포함하는 즉시 사용 가능한 플로팅 액션 버튼입니다. AgentProvider 내에서 자동으로 렌더링됩니다.

`AssistantButton`

채팅 인터페이스를 토글하는 데 사용할 수 있는 독립 실행형 버튼 컴포넌트입니다. FloatingActionBar 대신 수동으로 진입점을 배치하려는 경우 사용합니다.

타입 정의

`ChatMessage`

string

메시지의 고유 식별자입니다.

sender

'user' | 'assistant'

메시지가 사용자에 의해 전송되었는지 또는 어시스턴트에 의해 전송되었는지를 나타냅니다.

text

string

메시지의 내용입니다.

timestamp

number

메시지가 생성된 Unix 타임스탬프입니다.

`StabilityConfig`

DOM 안정성 감지를 구성하는 객체입니다.

표시 속성

strategy

'debounce' | 'fixed'

required

DOM이 안정적인지 판단하는 데 사용할 전략입니다.

debounceDelay

number

debounce 전략의 지연 시간(밀리초)입니다.

maxWaitTime

number

debounce 전략에서 안정성을 기다리는 최대 시간(밀리초)입니다.

waitTime

number

fixed 전략에서 기다릴 고정 시간(밀리초)입니다.

​React SDK 레퍼런스

​설치

​AgentProvider

​사용법

​설정 (MossSDKConfig)

​useAgent 훅

​사용법

​반환 값 (AgentState)

​컴포넌트

​FloatingActionBar

​AssistantButton

​타입 정의

​ChatMessage

​StabilityConfig

React SDK 레퍼런스

설치

`AgentProvider`

사용법

설정 (`MossSDKConfig`)

`useAgent` 훅

사용법

반환 값 (`AgentState`)

컴포넌트

`FloatingActionBar`

`AssistantButton`

타입 정의

`ChatMessage`

`StabilityConfig`