> ## 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.
# Installation
> Install the Moss SDK via NPM or CDN script tag
# Installation
Choose the integration method that fits your application.
You'll need your **Application ID** from the [Moss Dashboard](https://dashboard.viamoss.ai). You'll also need a JWT signing key — see [Authentication](/en/sdk/authentication).
## NPM Package (React)
For React 17+ applications.
### Install
```bash theme={null}
npm install @viamoss/moss-sdk
```
### Basic Setup
Add `AgentProvider` and `AssistantButton` to your app. The provider does **not** need to wrap your entire application — just the Moss components.
```tsx App.tsx theme={null}
import { AgentProvider, AssistantButton } from '@viamoss/moss-sdk';
function App() {
return (
<>
fetchMossToken(),
}}>
);
}
```
`AgentProvider` only needs to wrap the Moss UI components (`AssistantButton`). It observes the full page DOM regardless of where it sits in the React tree.
### Peer Dependencies
The SDK requires React 17 or 18 as a peer dependency:
```json theme={null}
{
"peerDependencies": {
"react": "^17.0.0 || ^18.0.0",
"react-dom": "^17.0.0 || ^18.0.0"
}
}
```
***
## CDN Script Tag
For any web application, regardless of framework.
### Basic Setup
Add the script tag to your HTML. The SDK auto-initializes and renders the assistant button.
```html theme={null}
```
### Configuration via JavaScript
For more control, configure via `window.mossSettings` before the script loads:
```html theme={null}
```
### Global API
After initialization, a global `window.MossSDK` object is available:
```javascript theme={null}
// Reinitialize with new config
await window.MossSDK.boot({ userId: 'new-user' });
// Update user identity (triggers reinitialization)
window.MossSDK.identify('user-456', { plan: 'premium' });
// Update config at runtime
window.MossSDK.updateConfig({ language: 'ko' });
// Tear down completely
window.MossSDK.shutdown();
```
***
## Custom Triggers
Open the assistant from any element using the `data-moss-trigger` attribute — no hooks required.
```html theme={null}
```
This works with any element: buttons, links, nav items, or custom components. The SDK listens for clicks on elements with this attribute and toggles the chat modal.
### Examples
```html theme={null}
How do I find my API key?
```
### React Component
```tsx theme={null}
function HelpButton() {
return (
);
}
```
The attribute works inside React components without needing `useAgent()`. Useful for simple triggers without state management.
### Without AssistantButton
You can use custom triggers instead of the built-in button:
```tsx theme={null}
{/* Custom trigger only - no AssistantButton */}
```
### TypeScript Constant
The SDK exports the attribute name for programmatic use:
```tsx theme={null}
import { MOSS_TRIGGER_ATTR } from '@viamoss/moss-sdk';
// MOSS_TRIGGER_ATTR = 'data-moss-trigger'
```
***
## Framework Examples
```tsx app/layout.tsx theme={null}
import { AgentProvider, AssistantButton } from '@viamoss/moss-sdk';
import { auth } from '@/lib/auth';
export default async function RootLayout({ children }) {
const session = await auth();
return (
{children}
);
}
// Client component for Moss
'use client';
function MossAssistant({ userId }: { userId: string }) {
return (
fetch('/api/moss-token').then(r => r.json()).then(d => d.token),
}}>
);
}
```
```tsx app/layout.tsx theme={null}
import Script from 'next/script';
export default function RootLayout({ children }) {
return (
{children}
);
}
```
```vue App.vue theme={null}
```
```typescript app.component.ts theme={null}
import { Component, OnInit, OnDestroy } from '@angular/core';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
})
export class AppComponent implements OnInit, OnDestroy {
private script: HTMLScriptElement | null = null;
ngOnInit() {
(window as any).mossSettings = {
apiUrl: 'https://moss-api.viamoss.ai',
userId: 'USER_ID',
jwt: 'YOUR_JWT_TOKEN',
};
this.script = document.createElement('script');
this.script.src = 'https://cdn.viamoss.ai/moss-sdk@latest.min.js?applicationId=YOUR_APP_ID';
this.script.async = true;
document.head.appendChild(this.script);
}
ngOnDestroy() {
if (this.script && document.head.contains(this.script)) {
document.head.removeChild(this.script);
}
}
}
```
## Next Steps
Set up JWT token authentication
Configure SDK behavior and options