# 라이선싱

## Content

SpreadJS 동시 작업 기능은 **동시 작업 서버(collaboration server)** 에 대한 서버 측 라이선스 검증을 지원합니다.
이 기능은 서버에 유효한 라이선스 키가 등록되었는지 확인하고, 라이선스 키의 도메인 화이트리스트 및 기능 권한에 따라 프런트엔드 접근을 제어합니다.

>type=note
> 한편, SpreadJS를 사용하여 프런트엔드에서 동시 작업 스프레드시트 기능을 사용할 경우, SpreadJS 라이선스 방식에 따라 별도의 인증이 필요합니다. 자세한 내용은 다음을 참고하십시오: [라이선싱](/spreadjs/docs/v19/getstarted/trial_SpreadJS).

## 사용 방법

**서버 측**
**server** 인스턴스에 ***licenseKey*** 속성을 설정하여 인증합니다.

```javascript
import express from 'express';
import { createServer } from 'http';
import { Server } from '@mescius/js-collaboration';

const app = express();
const httpServer = createServer(app);
const server = new Server({ httpServer });

server.licenseKey = "valid license key";
```

**클라이언트 측**
클라이언트 애플리케이션에 SpreadJS licenseKey를 반드시 적용해야 합니다.
이 키를 통해 클라이언트에서 동시 작업 기능이 활성화됩니다.
이로써 라이선스가 정상 적용된 동시 작업 서버와 클라이언트를 사용할 수 있습니다.
**라이선스 상태 확인**
라이선스 상태를 확인하려면 **connection** 인스턴스의 **licenseValidation** 이벤트를 수신하여 라이선스 정보를 확인할 수 있습니다.

```javascript
import { Client } from "@mescius/js-collaboration-client";
const url = 'xxxxxxxxxxxxxxx', roomId = 'xxxxxxxx';
const client = new Client(url);
const connection = client.connect(roomId);

// 라이선스 상태 확인이 필요할 때 LicenseValidation 이벤트를 사용할 수 있습니다.
connection.on('licenseValidation', (data: ILicenseValidationResult) => {
  console.log('License Validation result:', data);
});
```

***ILicenseValidationResult***의 데이터 구조는 다음과 같이 정의됩니다.

```typescript
interface ILicenseValidationResult {
  type: 'evaluation' | 'production' | 'invalid' | 'no key';
  expiredDate?: string; //20251215
  message?: string;
  status: number; // 0 = 실패, 1 = 성공
}
```

>type=note
> licenseValidation 이벤트는 서버가 라이선스 검증을 완료했을 때 트리거됩니다.

## 기능 설명

**라이선스 키 관리**

* 공개 API를 사용하여 라이선스 키를 등록합니다.

    ```javascript
    import { Server } from '@mescius/js-collaboration';
    const server = new Server();
    server.licenseKey = "valid license key";
    ```
* 지원되는 키 유형:
    * **평가(Evaluation) 라이선스 키:** 테스트용 임시 라이선스
    * **프로덕션(Production) 라이선스 키:** 실제 운영 환경에서 사용하는 영구 라이선스

**라이선스 검증 규칙**
**1\. 일반 규칙**

* 라이선스 키는 서버에 연결할 수 있는 프런트엔드 도메인을 정의합니다.
* 라이선스 키가 유효하지 않은 경우, 시스템은 프런트엔드 연결을 거부하고 오류 메시지를 반환합니다.
* 라이선스 키가 설정되지 않은 경우, 서버는 테스트 환경으로 간주되며 `localhost`에서의 접근만 허용합니다.
    * 이 경우 localhost가 아닌 모든 연결은 **거부**됩니다.

**2\. 프런트엔드 도메인 화이트리스트**

* **프런트엔드 호스트명**은 라이선스 키에 지정된 도메인 제한을 충족해야 합니다.
* 프런트엔드가 localhost에서 실행되는 경우 테스트 환경으로 간주되며, 라이선스 제한이 적용되지 않습니다.

3\. 동시 작업 **기능 검증**

* 동시 작업 기능을 사용하려면 라이선스에 Collaboration 기능이 포함되어 있어야 합니다.
* 기능이 포함되지 않은 경우, 동시 작업 관련 요청은 거부됩니다.

**4\. 라이선스 키 공용성**

* 유효한 Collaboration 라이선스는 서버와 프런트엔드 모두에서 사용할 수 있으며, 통합 환경 간에 공유됩니다.
    이는 서버와 클라이언트의 제한이 클라이언트 애플리케이션의 호스트명만을 기준으로 하기 때문입니다.

## 문제 해결 가이드

| 오류 유형 | Localhost 접근 | Non-Localhost 접근 | 권장 해결 방법 |
| ----- | ------------ | ---------------- | -------- |
| **라이선스 키 없음** | 허용 | *License Not Found* 메시지와 함께 거부 | 서버 설정에 유효한 라이선스 키를 추가하십시오. |
| **유효한 평가 키** | 허용 | 허용 | 조치 필요 없음 |
| **유효한 프로덕션 키** | 허용 | 허용 | 조치 필요 없음 |
| **키 파싱 실패** | 거부 | 거부 | 키 문자열 전체가 누락 없이 정확히 입력되었는지 확인하십시오. |
| **만료된 평가 키** | 거부 | 거부 | 새로운 평가 키 또는 프로덕션 키를 발급받으십시오. |
| **버전 불일치 키** | 거부 | 거부 | SpreadJS 버전에 맞는 라이선스 키를 사용하십시오. |
| **Collaboration 기능 없음** | 거부 | 거부 | Collaboration 기능이 포함된 라이선스로 업그레이드하거나 적용하십시오. |
| **기타 유효하지 않은 키** | 거부 | 거부 | 라이선스 형식과 유효성을 확인하십시오. |
| **화이트리스트에 없는 도메인** | 허용 | 거부 | 프런트엔드 도메인 또는 화이트리스트 설정을 업데이트하십시오. |