> ## 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 설치

> React를 사용하지 않는 애플리케이션이나 간단한 스크립트 태그 통합을 위한 Moss SDK의 CDN 설치 방법입니다. Intercom과 유사한 설치 방식입니다.

# CDN 설치 가이드

Moss SDK는 React를 사용하지 않는 애플리케이션이나 간단한 스크립트 태그 방식을 선호하는 경우를 위해 CDN 설치를 지원합니다. 이 방법은 Moss 대시보드의 애플리케이션 설정을 사용하여 SDK를 자동으로 구성합니다.

## 사전 요구사항

* [Moss 대시보드](https://dashboard.moss.ai)에 등록된 애플리케이션
* 애플리케이션 ID (UUID 형식)
* SDK를 설치할 웹사이트

## 🚀 빠른 시작

### 기본 설치

가장 간단한 시작 방법은 단일 스크립트 태그를 사용하는 것입니다:

```html theme={null}
<!-- YOUR_APP_ID를 실제 애플리케이션 ID로 교체하세요 -->
<script src="https://cdn.moss.ai/moss-sdk@latest?applicationId=YOUR_APP_ID"></script>
```

이것만으로 충분합니다! SDK는 다음을 자동으로 수행합니다:

* ✅ 대시보드에서 구성을 자동으로 가져오기
* ✅ 익명 사용자 ID 생성 (또는 기존 ID 사용)
* ✅ 플로팅 어시스턴트 버튼 표시
* ✅ 모든 초기화 자동 처리

## 📋 애플리케이션 ID 얻기

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

## ⚙️ 구성 옵션

### 방법 1: 사전 로드 구성

SDK가 로드되기 전에 `window.mossSettings`를 설정하여 동작을 사용자 정의할 수 있습니다:

```html theme={null}
<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

사용자 정의 백엔드 배포를 사용하는 경우:

```html theme={null}
<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` 객체를 제공합니다:

### 사용자 식별

```javascript theme={null}
// 로그인된 사용자 식별
window.MossSDK.identify("user456", {
  name: "김영희",
  email: "kim@example.com",
  plan: "premium"
});
```

### 런타임 구성

```javascript theme={null}
// 런타임에 구성 업데이트
window.MossSDK.updateConfig({
  debugMode: true,
  language: "ko"
});
```

### 라이프사이클 관리

```javascript theme={null}
// 사용자 정의 구성으로 수동 초기화
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를 업데이트하세요:

```javascript theme={null}
// 라우트 변경 시
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. **디버그 모드**: 디버그 모드를 활성화하여 상세 로그 확인:
   ```javascript theme={null}
   window.mossSettings = { debugMode: true };
   ```

### 사용자 식별 문제

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

## 🔧 고급 구성

### 사용자 정의 구성 필드

구성 객체를 통해 사용자 정의 데이터를 전달할 수 있습니다:

```javascript theme={null}
window.mossSettings = {
  configuration: {
    // 사용자 정의 애플리케이션 데이터
    theme: "dark",
    features: ["chat", "voice", "screen-share"],
    apiVersion: "v2",
    
    // 사용자 기본 설정
    notifications: true,
    language: "ko-KR",
    
    // 비즈니스 컨텍스트
    accountType: "enterprise",
    permissions: ["read", "write", "admin"]
  }
};
```

이 데이터는 AI 어시스턴트가 상황에 맞는 도움을 제공하는 데 사용됩니다.

### 오류 처리

```javascript theme={null}
// 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 참조](/ko/sdk-reference/sdk) 탐색

## 📚 관련 문서

* [NPM 설치](/ko/installation) - React 애플리케이션용
* [빠른 시작 가이드](/ko/quickstart) - React로 시작하기
* [SDK 참조](/ko/sdk-reference/sdk) - 완전한 API 문서
* [대시보드 가이드](https://docs.moss.ai/dashboard) - 애플리케이션 관리