Documentation Index
Fetch the complete documentation index at: https://docs.viamoss.ai/llms.txt
Use this file to discover all available pages before exploring further.
CDN 설치 가이드
Moss SDK는 React를 사용하지 않는 애플리케이션이나 간단한 스크립트 태그 방식을 선호하는 경우를 위해 CDN 설치를 지원합니다. 이 방법은 Moss 대시보드의 애플리케이션 설정을 사용하여 SDK를 자동으로 구성합니다.
사전 요구사항
- Moss 대시보드에 등록된 애플리케이션
- 애플리케이션 ID (UUID 형식)
- SDK를 설치할 웹사이트
🚀 빠른 시작
기본 설치
가장 간단한 시작 방법은 단일 스크립트 태그를 사용하는 것입니다:
<!-- YOUR_APP_ID를 실제 애플리케이션 ID로 교체하세요 -->
<script src="https://cdn.moss.ai/moss-sdk@latest?applicationId=YOUR_APP_ID"></script>
이것만으로 충분합니다! SDK는 다음을 자동으로 수행합니다:
- ✅ 대시보드에서 구성을 자동으로 가져오기
- ✅ 익명 사용자 ID 생성 (또는 기존 ID 사용)
- ✅ 플로팅 어시스턴트 버튼 표시
- ✅ 모든 초기화 자동 처리
📋 애플리케이션 ID 얻기
- Moss 대시보드에 가입
- 새 애플리케이션 생성 또는 기존 애플리케이션 선택
- 애플리케이션 설정에서 애플리케이션 ID 복사
- 대시보드에서 SDK 설정 구성 (선택사항)
⚙️ 구성 옵션
방법 1: 사전 로드 구성
SDK가 로드되기 전에 window.mossSettings를 설정하여 동작을 사용자 정의할 수 있습니다:
<script>
window.mossSettings = {
// 사용자 식별
userId: "user123",
// UI 기본 설정
language: "ko", // 'en' 또는 'ko'
debugMode: false,
// 사용자 정의 데이터
configuration: {
userName: "홍길동",
userEmail: "hong@example.com",
userRole: "admin"
}
};
</script>
<!-- 구성 후 SDK 로드 -->
<script src="https://cdn.moss.ai/moss-sdk@latest?applicationId=YOUR_APP_ID"></script>
방법 2: 사용자 정의 API 기본 URL
사용자 정의 백엔드 배포를 사용하는 경우:
<script src="https://cdn.moss.ai/moss-sdk@latest?applicationId=YOUR_APP_ID"
data-api-base="https://your-api.example.com"></script>
🎮 글로벌 API
로드가 완료되면, SDK는 런타임 제어를 위한 글로벌 MossSDK 객체를 제공합니다:
사용자 식별
// 로그인된 사용자 식별
window.MossSDK.identify("user456", {
name: "김영희",
email: "kim@example.com",
plan: "premium"
});
런타임 구성
// 런타임에 구성 업데이트
window.MossSDK.updateConfig({
debugMode: true,
language: "ko"
});
라이프사이클 관리
// 사용자 정의 구성으로 수동 초기화
window.MossSDK.boot({
userId: "new-user",
debugMode: true
});
// 깔끔한 종료 (로그아웃 시 유용)
window.MossSDK.shutdown();
// SDK 상태 확인
if (window.MossSDK && window.MossSDK._initialized) {
console.log("SDK가 준비되었습니다!");
console.log("현재 사용자:", window.MossSDK._config.userId);
}
📱 단일 페이지 앱 통합
SPA의 경우, 라우트나 사용자 상태가 변경될 때 SDK를 업데이트하세요:
// 라우트 변경 시
function onRouteChange(newUserId) {
if (newUserId) {
window.MossSDK.identify(newUserId);
}
}
// 사용자 로그인 시
function onUserLogin(user) {
window.MossSDK.identify(user.id, {
name: user.name,
email: user.email,
plan: user.subscription
});
}
// 사용자 로그아웃 시
function onUserLogout() {
window.MossSDK.shutdown();
// 선택적으로 익명 사용자를 위해 재시작
window.MossSDK.boot();
}
🔒 보안 및 도메인 제한
대시보드에서 허용된 도메인을 구성하여 SDK가 로드될 수 있는 위치를 제한하세요:
SDK는 요청 도메인을 자동으로 확인하고 승인되지 않은 사용을 차단합니다.
🆚 CDN vs NPM 설치 비교
| 기능 | CDN 설치 | NPM 설치 |
|---|
| 설정 | 단일 스크립트 태그 | npm install + import |
| 번들 크기 | ~200KB (자체 포함) | ~50KB (peer deps) |
| React 필요 | 아니오 | 예 |
| 자동 구성 | 예 (대시보드에서) | 수동 구성 |
| 글로벌 API | 예 | 아니오 |
| TypeScript 지원 | 제한적 | 완전 |
| 트리 셰이킹 | 아니오 | 예 |
🚨 문제 해결
SDK가 로드되지 않음
- 네트워크 확인: DevTools 네트워크 탭에서 실패한 요청 확인
- 애플리케이션 ID 확인: 대시보드와 정확히 일치하는지 확인
- 도메인 확인: 도메인이 화이트리스트에 있는지 확인 (구성된 경우)
- 콘솔 오류: 브라우저 콘솔에서 JavaScript 오류 확인
구성이 적용되지 않음
- 타이밍:
window.mossSettings가 스크립트 태그 전에 설정되었는지 확인
- 유효성 검사: 콘솔에서 구성 유효성 검사 오류 확인
- 디버그 모드: 디버그 모드를 활성화하여 상세 로그 확인:
window.mossSettings = { debugMode: true };
사용자 식별 문제
- 로드 후 호출: SDK 초기화 후
identify() 호출 확인
- 저장소 확인: 사용자 ID가 localStorage에 저장되는지 확인
- 형식 확인: 사용자 데이터가 예상 형식을 따르는지 확인
🔧 고급 구성
사용자 정의 구성 필드
구성 객체를 통해 사용자 정의 데이터를 전달할 수 있습니다:
window.mossSettings = {
configuration: {
// 사용자 정의 애플리케이션 데이터
theme: "dark",
features: ["chat", "voice", "screen-share"],
apiVersion: "v2",
// 사용자 기본 설정
notifications: true,
language: "ko-KR",
// 비즈니스 컨텍스트
accountType: "enterprise",
permissions: ["read", "write", "admin"]
}
};
이 데이터는 AI 어시스턴트가 상황에 맞는 도움을 제공하는 데 사용됩니다.
오류 처리
// SDK 초기화 오류 감지
window.addEventListener('error', function(e) {
if (e.filename && e.filename.includes('moss-sdk')) {
console.error('Moss SDK 로드 실패:', e.message);
// SDK 로드 실패 처리
}
});
// 지연 후 초기화 확인
setTimeout(() => {
if (!window.MossSDK || !window.MossSDK._initialized) {
console.warn('Moss SDK가 제대로 초기화되지 않았습니다');
// 대체 UI 표시 또는 재시도
}
}, 5000);
📊 분석 및 모니터링
SDK는 다음을 자동으로 추적합니다:
- 초기화 성공/실패
- 사용자 식별 이벤트
- 구성 업데이트
- 세션 관리
- 오류 발생
Moss 대시보드 분석 섹션에서 이러한 메트릭에 액세스할 수 있습니다.
🔗 다음 단계
- 설치 테스트: 브라우저 콘솔을 사용하여
window.MossSDK 존재 확인
- 설정 사용자 정의: Moss 대시보드에서 애플리케이션 구성
- 사용자 플로우 테스트:
identify() 및 updateConfig() 메서드 시도
- 사용량 모니터링: 대시보드에서 분석 확인
- 고급 기능: 전체 SDK 참조 탐색
📚 관련 문서