# Licensing

## Content

SpreadJS collaboration add-on supports server-side license validation for the **collaboration server**.
This feature ensures that a valid license key is registered on the server, and the corresponding frontend access is controlled based on the license key’s domain whitelist and add-on permissions.

>type=note
> Meanwhile, when using the collaborative spreadsheet feature in the frontend with SpreadJS, you also need to obtain authorization according to the SpreadJS Add-on Feature licensing method. For more details, please refer to: [Licensing](/spreadjs/docs/getstarted/trialSpreadJS).

## Usage Instructions

**Server Side**
Authorize by setting the ***licenseKey*** property on the **server** instance.

```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";
```

**Client Side**
Make sure you apply your SpreadJS licenseKey to your client-side application. This key will enable the collaboration features on the client.
That’s all you need to do to ensure a fully licensed Collaboration server and client.
**Check License Status**
If you want to get the license status, you can obtain license information by listening to the **licenseValidation** event of the **connection** instance.

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

//You can use the LicenseValidation event when you need to check the license status.
connection.on('licenseValidation', (data: ILicenseValidationResult) => {
  console.log('License Validation result:', data);
});
```

Regarding ***ILicenseValidationResult***, its data structure is defined as follows.

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

>type=note
> The licenseValidation event triggered when the server finishes validating the license.

## Feature Description

**License Key Management**

* License keys are registered using the public API:

    ```javascript
    import { Server } from '@mescius/js-collaboration';
    const server = new Server();
    server.licenseKey = "valid license key";
    ```
* Supported key types:
    * **Evaluation License Key:** Temporary license for testing.
    * **Production License Key:** Permanent license for production usage.

**License Validation Rules**
**1\. General Rules**

* The license key defines which frontend domains are authorized to connect to the server.
* If the license key is invalid, the system will reject frontend connections and return an error message.
* If no license key is configured, the server is treated as being in a test environment, which allows access only from `localhost`.
    * Any non-localhost connections in this case will be **rejected**.

**2\. Frontend Domain Whitelist**

* The **frontend hostname** must comply with the domain restrictions specified in the license key.
* When the frontend runs on localhost, it is treated as a test environment, and license restrictions are not enforced.

**3\. Collaboration Add\-on Validation**

* The license must include the Collaboration Add-on to enable collaborative features.
* If the add-on is not included, the system will reject collaboration-related requests.

**4\. License Key Universality**

* A valid Collaboration Add-on license can be used both on the server and the frontend — it is shared across integrations. This is because the server and client restrictions are based only on the hostname of the client application.

## Troubleshooting Guide

| Error Type | Access From Localhost | Access From Non-Localhost | Suggested Solution |
| ---------- | --------------------- | ------------------------- | ------------------ |
| **No License Key** | Accepted | Rejected with *License Not Found* message | Add a valid license key in your server configuration. |
| **Valid Evaluation Key** | Accepted | Accepted | No action required. |
| **Valid Production Key** | Accepted | Accepted | No action required. |
| **Cannot Parse Key** | Rejected | Rejected | Ensure the complete key string is pasted with no missing characters. |
| **Expired Evaluation Key** | Rejected | Rejected | Obtain a new evaluation or production key. |
| **Incorrect Version Key** | Rejected | Rejected | Use a license key that matches your SpreadJS version. |
| **No Collaboration Addon** | Rejected | Rejected | Upgrade or apply a license that includes the Collaboration Addon. |
| **Other Invalid Key** | Rejected | Rejected | Verify the license format and validity. |
| **Non-Whitelisted Domain** | Accepted | Rejected | Update the frontend domain or whitelist configuration. |