고급 설정

안정성 튜닝

페이지 컨텍스트를 캡처하기 전에 SDK는 페이지가 안정화될 때까지 대기합니다. 이를 통해 불완전하거나 렌더링 중인 스냅샷이 AI에 전송되는 것을 방지합니다. 안정성 시스템은 여러 감지 레이어를 순차적으로 실행하며, 각 레이어는 개별적으로 켜고 끌 수 있습니다:

레이어	감지 대상	기본값
Network Idle	대기 중인 fetch/XHR 요청	활성화
DOM Mutations	DOM 변경 (MutationObserver 사용)	활성화
Loading Indicators	스피너, 스켈레톤, `[aria-busy]`	비활성화
Frame Readiness	동일 출처 프레임 문서가 `readyState: 'complete'`에 도달	활성화
Resource Quiet	마지막 리소스 완료 이후 Resource Timing 항목이 잠잠해짐	활성화
Layout Shifts	시각적 레이아웃 변경 (PerformanceObserver 사용)	비활성화
Browser Idle	CPU 유휴 (requestIdleCallback 사용)	활성화
Final Frame	requestAnimationFrame 1회	활성화

로딩 인디케이터와 레이아웃 시프트 레이어는 기본적으로 비활성화되어 있습니다. 많은 사이트에 지속적인 로딩 애니메이션이 있어 불필요한 지연을 유발할 수 있기 때문입니다. 애플리케이션이 확실히 사라지는 스켈레톤 스크린을 사용하는 경우 활성화하세요.

추가 레이어 활성화

<AgentProvider config={{
  // ...
  stability: {
    layers: {
      loadingIndicators: true,  // 로딩 인디케이터 감지 활성화
      layoutShift: true,        // 레이아웃 시프트 감지 활성화
    },
  },
}}>

레이어별 설정

각 레이어를 개별적으로 설정할 수 있습니다:

stability: {
  // 글로벌 타임아웃
  maxTotalWaitMs: 15000,       // 모든 레이어의 최대 총 대기 시간 (기본값: 15초)
  networkTimeoutMs: 10000,     // 네트워크 유휴 타임아웃 (기본값: 10초)
  browserIdleTimeoutMs: 500,   // 브라우저 유휴 타임아웃 (기본값: 500ms)

  // DOM 뮤테이션 레이어
  domMutations: {
    quietPeriodMs: 800,        // 이 시간 동안 변경 없음 = 안정 (기본값: 800ms)
    excludeSelectors: ['.live-clock', '.notification-badge'],
  },

  // 로딩 인디케이터 레이어 (layers.loadingIndicators도 활성화해야 함)
  loadingIndicators: {
    selectors: ['[class*="skeleton"]', '.spinner', '[aria-busy="true"]'],
    excludeSelectors: ['.permanent-loader'],
    timeoutMs: 5000,
  },

  // 레이아웃 시프트 레이어 (layers.layoutShift도 활성화해야 함)
  layoutShift: {
    quietPeriodMs: 200,        // 이 시간 동안 시프트 없음 = 안정 (기본값: 200ms)
    ignoreThreshold: 0.01,     // 작은 시프트 무시 (기본값: 0.01)
  },
}

안정성 검사 비활성화

테스트용이나 매우 단순한 페이지의 경우 레이어를 비활성화할 수 있습니다:

stability: {
  layers: {
    networkIdle: false,
    domMutations: false,
    browserIdle: false,
    finalFrame: false,
  },
}

안정성 레이어를 비활성화하면 AI가 불완전한 페이지 컨텍스트를 받을 수 있습니다. 테스트 용도이거나 페이지가 완전히 렌더링되었다고 확신하는 경우에만 비활성화하세요.

리로드 후 처리

가이드 단계 중에 전체 페이지 리로드가 발생하는 경우 afterReload 옵션을 활성화하여 상태를 보존하세요:

stability: {
  afterReload: {
    enabled: true,          // 명시적으로 활성화하지 않으면 꺼져 있음
    pendingTTL: 30000,      // 대기 상태가 유효한 시간 (기본값: 30000ms)
    storageKey: 'my-app-moss-pending',  // 대기 상태를 저장하는 키 재정의
  },
}

필드	타입	기본값	설명
`enabled`	`boolean`	`false`	전체 페이지 리로드를 거쳐 대기 중인 가이드 상태를 보존
`pendingTTL`	`number`	`30000`	대기 마커가 폐기되기 전까지 유효한 시간(밀리초)
`storageKey`	`string`	SDK 기본값	대기 마커를 저장하는 데 사용하는 스토리지 키

Shadow DOM

SDK는 모든 UI를 document.body에 첨부된 Shadow DOM 내부에 렌더링합니다. 이는 다음을 의미합니다:

여러분의 CSS가 Moss UI에 영향을 줄 수 없습니다 — 스타일이 완전히 캡슐화됨
Moss CSS가 여러분의 앱에 영향을 줄 수 없습니다 — 스타일 누출 없음
여러분의 앱에서 DOM 쿼리로 Moss 요소를 찾을 수 없습니다 — document.querySelector가 Shadow Root 내부의 요소를 매칭하지 않음

자동화된 테스트 도구(Cypress, Playwright 등)를 사용하는 경우 Moss 요소와 상호 작용하려면 Shadow DOM을 관통해야 합니다. #moss-shadow-host 호스트 요소를 찾으세요(0.16 이하 SDK 버전에서는 #clippy-shadow-host).

Content Security Policy (CSP)

애플리케이션에서 엄격한 CSP 헤더를 사용하는 경우 다음을 허용해야 할 수 있습니다:

디렉티브	값	이유
`connect-src`	Moss 백엔드 URL	API 요청
`script-src`	CDN URL (스크립트 태그 사용 시)	SDK 스크립트
`style-src`	`'unsafe-inline'`	Shadow DOM 스타일
`img-src`	`blob:` `data:`	스크린샷 처리

CSP 헤더 예시:

Content-Security-Policy:
  connect-src 'self' https://moss-api.viamoss.ai;
  style-src 'self' 'unsafe-inline';
  img-src 'self' blob: data:;

DOM 관찰 범위

기본적으로 SDK는 document.body의 변경을 관찰합니다. 페이지의 특정 부분으로 관찰을 제한하려면:

<AgentProvider config={{
  // ...
  observeTargetSelector: '#main-content',
}}>

다음과 같은 경우에 유용합니다:

앱에 재캡처를 트리거하지 말아야 할 복잡한 사이드바나 헤더가 있는 경우
관련 없는 DOM 변경으로 인한 노이즈를 줄이고 싶은 경우
어시스턴트가 페이지의 특정 섹션만 도와야 하는 경우

네이티브 모달 다이얼로그

애플리케이션이 네이티브 <dialog>를 showModal()로 열면, 브라우저는 다이얼로그 바깥의 모든 요소를 비활성(inert) 상태로 만듭니다. Moss 위젯도 예외가 아닙니다. 사용자는 어시스턴트를 클릭할 수 없고, 진행 중이던 가이드도 이어갈 수 없습니다. 애플리케이션에서 showModal()을 사용한다면, 위젯을 마운트한 요소를 넘겨 모달 다이얼로그 이스케이프를 설치하세요:

import { installModalDialogEscape } from '@viamoss/moss-sdk';

const uninstall = installModalDialogEscape(widgetMountElement);

// 나중에 위젯을 해제할 때:
uninstall();

모달 다이얼로그가 열려 있는 동안 SDK 호스트는 다이얼로그의 트리 안으로 임시 이동되며(그 위로 올라갑니다), 덕분에 위젯은 계속 조작 가능한 상태로 뷰포트 위치를 유지합니다. 다이얼로그가 닫히면 호스트는 원래 DOM 위치로 복원됩니다. 반환된 함수는 리스너를 제거하고 호스트를 복원합니다.

통합에서 온전히 소유한 요소, 즉 Moss 위젯을 마운트한 컨테이너를 넘기세요. 애플리케이션 프레임워크가 관리하는 노드는 절대 넘기지 마세요. 이스케이프는 요소를 다른 위치로 옮기므로 프레임워크의 렌더링과 충돌합니다.

제한 사항:

Shadow root 내부에 렌더링된 다이얼로그는 추적되지 않습니다.
Popover API를 지원하지 않는 브라우저에서는 위젯이 조작 가능한 상태로 유지되지만, overflow: hidden이나 transform이 적용된 다이얼로그 안에서는 잘려 보일 수 있습니다.

민감 콘텐츠 편집

`data-moss-redact`를 이용한 선언적 편집

HTML 요소에 data-moss-redact 속성을 지정하면 Moss 백엔드로 전송되는 모든 데이터에서 해당 요소가 편집됩니다. 민감한 콘텐츠를 보호하는 가장 간단한 방법입니다.

<div data-moss-redact>
  <p>계좌 잔액: $12,340.56</p>
  <p>주민등록번호: 123-45-6789</p>
</div>

편집되는 대상:

텍스트 콘텐츠 — 백엔드로 전송되는 구조화된 컨텍스트에서 [REDACTED]로 대체
민감한 속성 — value, placeholder, title, alt, aria-label, href, src, name이 모두 편집됨
하위 요소 — 편집 대상 요소의 모든 하위 요소가 제외됨

편집은 표시된 요소와 그 상위 10단계까지의 조상에 적용되므로, 컨테이너 하나만 표시해 내부 전체를 편집할 수 있습니다.

<!-- 이 섹션 안의 모든 폼 필드가 편집됩니다 -->
<section data-moss-redact>
  <input type="text" placeholder="카드 번호" />
  <input type="text" placeholder="CVV" />
</section>

입력값 편집 (기본 활성화)

input, textarea, select, contenteditable 영역을 포함한 모든 입력 요소의 값은 기본적으로 편집됩니다. 사용자가 폼에 입력한 내용은 페이지 컨텍스트로 브라우저를 벗어나지 않습니다. 내용이 안전하고 어시스턴트에게 유용하다고 확인된 특정 필드(예: 검색창)를 대상에서 제외하려면 data-moss-unredact를 지정하세요:

<input type="search" data-moss-unredact placeholder="상품 검색…" />

입력값 편집을 완전히 비활성화하려면 redactAllInputs: false로 설정하세요:

<AgentProvider config={{
  // ...
  redactAllInputs: false,  // 기본값: true
}}>

애플리케이션의 모든 폼을 검토하지 않았다면 redactAllInputs를 켜 둔 채로 두세요. 비활성화하면 사용자가 입력한 폼 값이 Moss로 전송되는 페이지 컨텍스트에 포함됩니다.

CSS 선택자를 이용한 편집

애플리케이션이 이미 다른 도구를 위해 민감한 요소를 표시하고 있다면(예: FullStory의 .fs-exclude / .fs-mask 클래스), 모든 곳에 data-moss-redact를 추가하는 대신 기존 표시를 그대로 재사용하세요. redactionSelectors에 일치하는 요소는 data-moss-redact와 동일하게 편집됩니다:

<AgentProvider config={{
  // ...
  redactionSelectors: ['.fs-exclude', '.fs-mask', '[data-private]'],
}}>

data-moss-redact는 이 설정과 관계없이 항상 인식됩니다. 한 요소가 허용 규칙과 편집 규칙에 모두 해당하면 편집 규칙이 우선합니다.

편집이 적용되는 범위

편집은 컨텍스트로 전송되는 페이지 텍스트와 구조, 그리고 단계별 가이드 진행 중 기록되는 상호작용 리포트에 적용됩니다. 사용자가 입력하는 채팅 메시지, 스크린샷, 세션 기록, 화면 히스토리는 편집되지 않습니다. 해당 결과물이 여러분의 환경에서 허용되지 않는다면 각 기능을 개별적으로 비활성화하세요.

프로그래매틱 정리

더 복잡한 정리 로직이 필요하다면 pageSanitizationScript로 캡처 전에 복제된 DOM을 수정하세요:

<AgentProvider config={{
  // ...
  pageSanitizationScript: (doc) => {
    // 신용카드 필드 제거
    doc.querySelectorAll('[data-sensitive]').forEach(el => {
      el.textContent = '[편집됨]';
    });
    // 트래킹 픽셀 제거
    doc.querySelectorAll('img[width="1"]').forEach(el => el.remove());
  },
}}>

두 방식 모두 AI가 보는 내용에만 영향을 줍니다. 실제 DOM은 변경되지 않으므로 사용자에게는 아무런 변화가 보이지 않습니다.

문제 해결

어시스턴트 버튼이 나타나지 않음

브라우저 콘솔에서 [MossSDK] 오류를 확인하세요
applicationId가 대시보드의 유효한 애플리케이션과 일치하는지 확인하세요
apiUrl이 브라우저에서 접근 가능한지 확인하세요
JWT 서명 키가 활성 상태이고 폐기되지 않았는지 확인하세요

”Failed to fetch config” 오류

SDK가 백엔드에 연결할 수 없습니다. apiUrl 및 네트워크/CORS 설정을 확인하세요.
CSP를 사용하는 경우 connect-src에 백엔드 URL이 포함되어 있는지 확인하세요.

스크린샷이 빈 화면이거나 불완전함

screenshotMode를 'viewport'로 전환해 보세요
페이지에 느린 애니메이션이 있는 경우 stability.domMutations.quietPeriodMs를 늘리세요
iframe이나 교차 출처 콘텐츠가 캡처를 차단하고 있는지 확인하세요

호스트 애플리케이션과 스타일 충돌

이것은 발생하지 않아야 합니다 — SDK는 Shadow DOM 격리를 사용합니다. 충돌이 보이는 경우:

앱에서 * 또는 body 선택자에 !important를 사용하고 있는지 확인하세요
JavaScript가 Shadow Root를 수정하고 있지 않은지 확인하세요

디버그 모드

문제 진단을 위해 상세 로깅을 활성화하세요:

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

<AgentProvider config={{
  // ...
  debugMode: true,
  logLevel: LogLevel.DEBUG,
}}>

안정성 레이어 타이밍, 네트워크 요청, 컨텍스트 캡처 세부 정보 및 API 응답이 브라우저 콘솔에 기록됩니다.

시작하기

SDK

대시보드

설정

보안

가이드

리소스

고급

고급 설정

안정성 튜닝

추가 레이어 활성화

레이어별 설정

안정성 검사 비활성화

리로드 후 처리

Shadow DOM

Content Security Policy (CSP)

DOM 관찰 범위

네이티브 모달 다이얼로그

민감 콘텐츠 편집

`data-moss-redact`를 이용한 선언적 편집

입력값 편집 (기본 활성화)

CSS 선택자를 이용한 편집

편집이 적용되는 범위

프로그래매틱 정리

문제 해결

어시스턴트 버튼이 나타나지 않음

”Failed to fetch config” 오류

스크린샷이 빈 화면이거나 불완전함

호스트 애플리케이션과 스타일 충돌

디버그 모드

​고급 설정

​안정성 튜닝

​추가 레이어 활성화

​레이어별 설정

​안정성 검사 비활성화

​리로드 후 처리

​Shadow DOM

​Content Security Policy (CSP)

​DOM 관찰 범위

​네이티브 모달 다이얼로그

​민감 콘텐츠 편집

​data-moss-redact를 이용한 선언적 편집

​입력값 편집 (기본 활성화)

​CSS 선택자를 이용한 편집

​편집이 적용되는 범위

​프로그래매틱 정리

​문제 해결

​어시스턴트 버튼이 나타나지 않음

​”Failed to fetch config” 오류

​스크린샷이 빈 화면이거나 불완전함

​호스트 애플리케이션과 스타일 충돌

​디버그 모드

고급 설정

안정성 튜닝

추가 레이어 활성화

레이어별 설정

안정성 검사 비활성화

리로드 후 처리

Shadow DOM

Content Security Policy (CSP)

DOM 관찰 범위

네이티브 모달 다이얼로그

민감 콘텐츠 편집

`data-moss-redact`를 이용한 선언적 편집

입력값 편집 (기본 활성화)

CSS 선택자를 이용한 편집

편집이 적용되는 범위

프로그래매틱 정리

문제 해결

어시스턴트 버튼이 나타나지 않음

”Failed to fetch config” 오류

스크린샷이 빈 화면이거나 불완전함

호스트 애플리케이션과 스타일 충돌

디버그 모드