메인 콘텐츠로 건너뛰기

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 얻기

  1. Moss 대시보드가입
  2. 새 애플리케이션 생성 또는 기존 애플리케이션 선택
  3. 애플리케이션 설정에서 애플리케이션 ID 복사
  4. 대시보드에서 SDK 설정 구성 (선택사항)

⚙️ 구성 옵션

방법 1: 사전 로드 구성

SDK가 로드되기 전에 window.mossSettings를 설정하여 동작을 사용자 정의할 수 있습니다:
<script>
  window.mossSettings = {
    // 사용자 식별
    userId: "user123",
    
    // UI 기본 설정
    language: "ko", // 'en' 또는 'ko'
    debugMode: false,
    
    // 사용자 정의 데이터
    configuration: {
      userName: "홍길동",
      userEmail: "[email protected]",
      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: "[email protected]",
  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가 로드되지 않음

  1. 네트워크 확인: DevTools 네트워크 탭에서 실패한 요청 확인
  2. 애플리케이션 ID 확인: 대시보드와 정확히 일치하는지 확인
  3. 도메인 확인: 도메인이 화이트리스트에 있는지 확인 (구성된 경우)
  4. 콘솔 오류: 브라우저 콘솔에서 JavaScript 오류 확인

구성이 적용되지 않음

  1. 타이밍: window.mossSettings가 스크립트 태그 전에 설정되었는지 확인
  2. 유효성 검사: 콘솔에서 구성 유효성 검사 오류 확인
  3. 디버그 모드: 디버그 모드를 활성화하여 상세 로그 확인:
    window.mossSettings = { debugMode: true };
    

사용자 식별 문제

  1. 로드 후 호출: SDK 초기화 후 identify() 호출 확인
  2. 저장소 확인: 사용자 ID가 localStorage에 저장되는지 확인
  3. 형식 확인: 사용자 데이터가 예상 형식을 따르는지 확인

🔧 고급 구성

사용자 정의 구성 필드

구성 객체를 통해 사용자 정의 데이터를 전달할 수 있습니다:
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 대시보드 분석 섹션에서 이러한 메트릭에 액세스할 수 있습니다.

🔗 다음 단계

  1. 설치 테스트: 브라우저 콘솔을 사용하여 window.MossSDK 존재 확인
  2. 설정 사용자 정의: Moss 대시보드에서 애플리케이션 구성
  3. 사용자 플로우 테스트: identify()updateConfig() 메서드 시도
  4. 사용량 모니터링: 대시보드에서 분석 확인
  5. 고급 기능: 전체 SDK 참조 탐색

📚 관련 문서