CDN 설치 가이드
Moss SDK는 React를 사용하지 않는 애플리케이션이나 간단한 스크립트 태그 방식을 선호하는 경우를 위해 CDN 설치를 지원합니다. 이 방법은 Moss 대시보드의 애플리케이션 설정을 사용하여 SDK를 자동으로 구성합니다.사전 요구사항
- Moss 대시보드에 등록된 애플리케이션
- 애플리케이션 ID (UUID 형식)
- SDK를 설치할 웹사이트
🚀 빠른 시작
기본 설치
가장 간단한 시작 방법은 단일 스크립트 태그를 사용하는 것입니다:- ✅ 대시보드에서 구성을 자동으로 가져오기
- ✅ 익명 사용자 ID 생성 (또는 기존 ID 사용)
- ✅ 플로팅 어시스턴트 버튼 표시
- ✅ 모든 초기화 자동 처리
📋 애플리케이션 ID 얻기
- Moss 대시보드에 가입
- 새 애플리케이션 생성 또는 기존 애플리케이션 선택
- 애플리케이션 설정에서 애플리케이션 ID 복사
- 대시보드에서 SDK 설정 구성 (선택사항)
⚙️ 구성 옵션
방법 1: 사전 로드 구성
SDK가 로드되기 전에window.mossSettings를 설정하여 동작을 사용자 정의할 수 있습니다:
방법 2: 사용자 정의 API 기본 URL
사용자 정의 백엔드 배포를 사용하는 경우:🎮 글로벌 API
로드가 완료되면, SDK는 런타임 제어를 위한 글로벌MossSDK 객체를 제공합니다:
사용자 식별
런타임 구성
라이프사이클 관리
📱 단일 페이지 앱 통합
SPA의 경우, 라우트나 사용자 상태가 변경될 때 SDK를 업데이트하세요:🔒 보안 및 도메인 제한
대시보드에서 허용된 도메인을 구성하여 SDK가 로드될 수 있는 위치를 제한하세요: SDK는 요청 도메인을 자동으로 확인하고 승인되지 않은 사용을 차단합니다.🆚 CDN vs NPM 설치 비교
| 기능 | CDN 설치 | NPM 설치 |
|---|---|---|
| 설정 | 단일 스크립트 태그 | npm install + import |
| 번들 크기 | ~200KB (자체 포함) | ~50KB (peer deps) |
| React 필요 | 아니오 | 예 |
| 자동 구성 | 예 (대시보드에서) | 수동 구성 |
| 글로벌 API | 예 | 아니오 |
| TypeScript 지원 | 제한적 | 완전 |
| 트리 셰이킹 | 아니오 | 예 |
🚨 문제 해결
SDK가 로드되지 않음
- 네트워크 확인: DevTools 네트워크 탭에서 실패한 요청 확인
- 애플리케이션 ID 확인: 대시보드와 정확히 일치하는지 확인
- 도메인 확인: 도메인이 화이트리스트에 있는지 확인 (구성된 경우)
- 콘솔 오류: 브라우저 콘솔에서 JavaScript 오류 확인
구성이 적용되지 않음
- 타이밍:
window.mossSettings가 스크립트 태그 전에 설정되었는지 확인 - 유효성 검사: 콘솔에서 구성 유효성 검사 오류 확인
- 디버그 모드: 디버그 모드를 활성화하여 상세 로그 확인:
사용자 식별 문제
- 로드 후 호출: SDK 초기화 후
identify()호출 확인 - 저장소 확인: 사용자 ID가 localStorage에 저장되는지 확인
- 형식 확인: 사용자 데이터가 예상 형식을 따르는지 확인
🔧 고급 구성
사용자 정의 구성 필드
구성 객체를 통해 사용자 정의 데이터를 전달할 수 있습니다:오류 처리
📊 분석 및 모니터링
SDK는 다음을 자동으로 추적합니다:- 초기화 성공/실패
- 사용자 식별 이벤트
- 구성 업데이트
- 세션 관리
- 오류 발생
🔗 다음 단계
- 설치 테스트: 브라우저 콘솔을 사용하여
window.MossSDK존재 확인 - 설정 사용자 정의: Moss 대시보드에서 애플리케이션 구성
- 사용자 플로우 테스트:
identify()및updateConfig()메서드 시도 - 사용량 모니터링: 대시보드에서 분석 확인
- 고급 기능: 전체 SDK 참조 탐색