SDK 옵션

개요

SDK 설정 옵션을 사용하면 애플리케이션 코드에서 직접 Moss 동작을 사용자 정의할 수 있습니다. 이러한 설정은 지정 시 대시보드 기본값을 재정의하여 개발자에게 배포, 환경 또는 사용자 세그먼트별로 세밀한 제어를 제공합니다.

우선순위 알림: SDK 설정 옵션은 대시보드 설정보다 우선합니다. 코드에서 옵션을 구성하면 대시보드에서 설정한 값을 재정의합니다. 이를 통해 개발자는 대시보드 설정을 기본값으로 사용하면서 배포별로 동작을 사용자 정의할 수 있습니다.

필수 옵션

AgentProvider config에 다음 옵션을 제공해야 합니다:

import { AgentProvider, AssistantButton } from '@viamoss/moss-sdk';

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
}}>
  <AssistantButton />
</AgentProvider>

옵션	타입	설명
`apiUrl`	`string`	Moss API 엔드포인트 URL
`applicationId`	`string`	대시보드의 고유 애플리케이션 ID
`userId`	`string`	현재 사용자의 고유 식별자
`getJwt`	`() => Promise<string>`	JWT 토큰을 반환하는 함수

userId는 사용자의 안정적인 식별자여야 합니다. PII(이메일, 이름)를 직접 사용하지 마세요 - 대신 해시되거나 익명화된 식별자를 사용하세요.

일반 옵션

SDK 동작을 사용자 정의하는 데 자주 사용되는 옵션입니다:

언어

SDK 인터페이스의 UI 언어를 설정합니다.

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  language: 'ko',  // 'en', 'ko' 또는 자동 감지를 위해 undefined
}}>
  <AssistantButton />
</AgentProvider>

기본값: undefined (브라우저 언어 자동 감지)

사용자의 브라우저 언어 기본 설정을 자동으로 사용하려면 undefined로 두세요.

비전

스크린샷 분석 기능을 활성화 또는 비활성화합니다.

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  useVision: true,  // 시각적 컨텍스트 활성화
}}>
  <AssistantButton />
</AgentProvider>

기본값: true (대시보드에서)

세션 녹화

사용자 세션이 리플레이를 위해 녹화되는지 여부를 제어합니다.

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  enableSessionRecording: false,  // 개인정보에 민감한 사용자를 위해 비활성화
}}>
  <AssistantButton />
</AgentProvider>

기본값: true (대시보드에서)

화면 히스토리

AI 컨텍스트에 사용자 액션 히스토리를 포함합니다.

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  enableScreenHistoryRecording: true,
}}>
  <AssistantButton />
</AgentProvider>

기본값: true (대시보드에서)

외관 (Appearance)

Moss 어시스턴트 UI의 비주얼 테마를 사용자 정의합니다.

프리셋 사용

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  appearance: 'blue',  // 프리셋 테마 사용
}}>
  <AssistantButton />
</AgentProvider>

사용 가능한 프리셋:

프리셋	설명
`'blue'`	글래스모피즘 효과가 있는 기본 블루 테마
`'purple'`	단색 배경의 퍼플 테마

커스텀 외관

부분 객체를 전달하여 특정 속성을 재정의합니다:

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  appearance: {
    colors: {
      primary: '#3b82f6',
      primaryLight: '#60a5fa',
    },
    modal: {
      defaultPosition: { right: 20, bottom: 20 },
      defaultSize: { width: 400, height: 600 },
    },
    effects: {
      glassmorphism: true,
    },
  },
}}>
  <AssistantButton />
</AgentProvider>

사용자 정의 가능한 속성

카테고리	속성
`colors`	`primary`, `primaryLight`, `primaryLighter`, `userMessage`, `assistantMessage`, `headerBackground`, `inputAreaBackground`, `modalBackground`, `text.*`, `border`, `success`, `error`
`typography`	`fontFamily`, `fontSize.`, `lineHeight.`
`spacing`	`3xs`, `2xs`, `xs`, `sm`, `md` 등
`radius`	`sm`, `md`, `lg`, `xl`
`shadows`	`sm`, `md`, `lg`
`effects`	`glassmorphism`, `glassBlur`, `glassOpacity`
`inputBar`	`roundedTop`, `topShadow`
`progressBar`	`height`
`modal`	`defaultPosition`, `defaultSize`

부분 객체는 기본 테마와 깊은 병합(deep-merge)됩니다. 재정의하려는 속성만 지정하면 됩니다.

세션 옵션

세션 관리 동작을 구성합니다:

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  sessionConfig: {
    inactivityTimeout: 60,
    maxSessionAge: 4,
    showNotification: true,
  },
}}>
  <AssistantButton />
</AgentProvider>

옵션	타입	기본값	설명
`inactivityTimeout`	`number`	`30`	세션 만료 전 비활성 시간(분)
`maxSessionAge`	`number`	`2`	최대 세션 지속 시간(시간)
`showNotification`	`boolean`	`true`	새 세션 시 알림 표시

개발자 옵션

디버깅 및 사용자 정의를 위한 고급 설정입니다:

스크린샷 모드

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  screenshotMode: 'viewport',  // 'fullpage' 또는 'viewport'
}}>
  <AssistantButton />
</AgentProvider>

기본값: 'fullpage'

값	설명
`fullpage`	전체 스크롤 가능한 페이지를 캡처
`viewport`	보이는 부분만 캡처

페이지가 매우 긴 앱의 경우 처리 시간을 줄이기 위해 viewport를 사용하세요.

로그 레벨

import { AgentProvider, AssistantButton, LogLevel } from '@viamoss/moss-sdk';

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  logLevel: LogLevel.DEBUG,  // DEBUG, INFO, WARN, ERROR, SILENT
}}>
  <AssistantButton />
</AgentProvider>

기본값: LogLevel.INFO logLevel은 문자열이 아니라 SDK가 내보내는 LogLevel 열거형 값을 받습니다. 각 레벨은 자신보다 심각한 레벨을 모두 포함합니다 (DEBUG는 모든 것을 표시하고, SILENT은 로깅을 비활성화합니다).

디버그 모드

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  debugMode: true,
}}>
  <AssistantButton />
</AgentProvider>

기본값: false 문제 해결을 위한 자세한 로깅 및 디버그 기능을 활성화합니다.

DOM 대상 셀렉터

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  observeTargetSelector: '#main-content',
}}>
  <AssistantButton />
</AgentProvider>

기본값: 'body' 관찰할 DOM 요소의 CSS 셀렉터입니다. 페이지의 특정 부분으로 관찰을 제한하려면 이를 변경하세요.

DOM 안정성

SDK가 페이지가 안정화되기를 기다리는 방식을 구성합니다:

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  stability: {
    maxTotalWaitMs: 15000,
    layers: {
      networkIdle: true,
      domMutations: true,
      loadingIndicators: false,
      frameReadiness: true,
      resourceQuiet: true,
      layoutShift: false,
      browserIdle: true,
      finalFrame: true,
    },
    domMutations: {
      quietPeriodMs: 1000,
    },
  },
}}>
  <AssistantButton />
</AgentProvider>

자세한 레이어별 문서는 SDK 고급 설정 가이드를 참조하세요.

전체 TypeScript 인터페이스

SDK 설정을 위한 전체 TypeScript 인터페이스입니다:

interface MossConfig {
  // 필수
  apiUrl: string;
  applicationId: string;
  userId: string;
  getJwt: () => Promise<string>;

  // 애플리케이션 기능
  useVision?: boolean;
  language?: 'en' | 'ko';
  appearance?: AppearanceInput;  // 'blue' | 'purple' | 커스텀 객체

  // 녹화 및 히스토리
  enableSessionRecording?: boolean;
  enableScreenHistoryRecording?: boolean;

  // 세션 관리
  sessionConfig?: {
    inactivityTimeout?: number;
    maxSessionAge?: number;
    showNotification?: boolean;
  };

  // 기술 설정
  logLevel?: LogLevel;  // 열거형: DEBUG, INFO, WARN, ERROR, SILENT
  debugMode?: boolean;
  screenshotMode?: 'fullpage' | 'viewport';
  observeTargetSelector?: string;

  // DOM 안정성
  stability?: {
    maxTotalWaitMs?: number;
    layers?: {
      networkIdle?: boolean;
      domMutations?: boolean;
      loadingIndicators?: boolean;
      frameReadiness?: boolean;
      resourceQuiet?: boolean;
      layoutShift?: boolean;
      browserIdle?: boolean;
      finalFrame?: boolean;
    };
    domMutations?: {
      quietPeriodMs?: number;
    };
  };
}

SDK에서 사용할 수 없는 설정

다음 설정은 대시보드를 통해서만 구성할 수 있습니다:

AI 어시스턴트 지침 - AI를 위한 사용자 정의 지침
API 키 - 인증 자격 증명
도메인 접근 제어 - 허용 도메인 목록
벡터 저장소 설정 - RAG 시스템 설정

이러한 설정은 보안상의 이유로 대시보드 전용입니다. 애플리케이션 전체 동작 및 인증에 영향을 미칩니다.

시작하기

SDK

대시보드

설정

보안

가이드

리소스

개요

필수 옵션

일반 옵션

언어

비전

세션 녹화

화면 히스토리

외관 (Appearance)

프리셋 사용

커스텀 외관

사용자 정의 가능한 속성

세션 옵션

개발자 옵션

스크린샷 모드

로그 레벨

디버그 모드

DOM 대상 셀렉터

DOM 안정성

전체 TypeScript 인터페이스

SDK에서 사용할 수 없는 설정

다음 단계

예시

대시보드 설정

​개요

​필수 옵션

​일반 옵션

​언어

​비전

​세션 녹화

​화면 히스토리

​외관 (Appearance)

​프리셋 사용

​커스텀 외관

​사용자 정의 가능한 속성

​세션 옵션

​개발자 옵션

​스크린샷 모드

​로그 레벨

​디버그 모드

​DOM 대상 셀렉터

​DOM 안정성

​전체 TypeScript 인터페이스

​SDK에서 사용할 수 없는 설정

​다음 단계

예시

대시보드 설정

개요

필수 옵션

일반 옵션

언어

비전

세션 녹화

화면 히스토리

외관 (Appearance)

프리셋 사용

커스텀 외관

사용자 정의 가능한 속성

세션 옵션

개발자 옵션

스크린샷 모드

로그 레벨

디버그 모드

DOM 대상 셀렉터

DOM 안정성

전체 TypeScript 인터페이스

SDK에서 사용할 수 없는 설정

다음 단계