ultron-ai-sdk/README.md

This package is for integrating Ultron AI Characters as website Companions on a website

```markdown
# Ultron AI SDK

```

## Installation

### Via npm

```bash
npm install ultron-ai-sdk

```

## Quick Start

```javascript
// Import the SDK
    import {SceneCanvas, Character} from 'ultron-ai-sdk';        
        
    let sceneCanvas
    let character
    
    const init = async() => {
        sceneCanvas = new SceneCanvas('target-html-element')
        const initializationSetting= {
            avatarId: "AVATAR_ID",       // AvatarId and Request Id are same
            config:{
                apiKey: "YOUR_ULTRON_API_KEY"
            },
            options:{
                alwaysListen: false // For Push to talk conversation
            }
        }
        await sceneCanvas.init(initializationSetting)
        character = sceneCanvas.character
                    
    }
    init()

```

### In HTML Via CDN like [jsDelivr](https://www.jsdelivr.com/).


```html

<script type="importmap">
        {
          "imports": {
            "ultron-ai-sdk": "https://cdn.jsdelivr.net/npm/ultron-ai-sdk@1.0.4/dist/index.mjs?module"            
          }
        }
</script>

<script type="module">
    import {SceneCanvas, Character} from 'ultron-ai-sdk';        
        
    let sceneCanvas
    let character
    
    const init = async() => {
        sceneCanvas = new SceneCanvas('target-html-element')
        const initializationSetting= {
            avatarId: "AVATAR_ID",       // AvatarId and Request Id are same
            config:{
                apiKey: "YOUR_ULTRON_API_KEY"               // Not required if you can create and access "sessionId" 
                // sessionId: "SESSION_ID_FOR_CURRENT_USER" // Recomended method for secure access
            },
            options:{
                hideClickMessage: true //remove default "Click message" on the avatar
                alwaysListen: false    // For Push to talk conversation
            }
        }
        await sceneCanvas.init(initializationSetting)
        character = sceneCanvas.character

        // Use "character" object to call various methods like .chat() or .say()

        // character.say("Hello world")
        // character.chat("Please introduce yourself")

        //IMPORTANT --->
        // User interaction like click is necessory for the talking of the Avatar to work due to inbuilt security in variuos browser
                    
    }
    init()  // You can also call this on user interaction like clicking on support/chat icon.

</script>

```

#### Quick Demo

Check out our website for demo at: [🔗Talk to Avatar in metabrix website](https://dev-website.ultronai.me)



---


## Target HTML Element

```html

<div id="target-html-element"></div>

```

## API Reference

### Initialization

```javascript

const sceneCanvas = new SceneCanvas('target-html-element')
sceneCanvas.init({sessionId: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxx"})

```

---


### Configuration Options

| Option      | Description |
|-------------|--------------|
| `sessionId` (optional) | Session Id obtained using API key |
| `apiKey` | You ultron key which can be found in your profile in Ultron App |

#### API key (apiKey) 

To get API key of your ultron account follow the steps below

### STEP 1: Click on account at top right corner

![Avatar ID step 1](https://media.ultronai.me/Images/website/apikeysh1.png)

### STEP 2: Select API key from dropdown

![Avatar ID step 1](https://media.ultronai.me/Images/website/apikey2.png)

### STEP 3: Copy your API key

![Avatar ID step 1](https://media.ultronai.me/Images/website/apishe3.png)

#### Session Id (sessionId)

## 🔑 Create Session API

This API allows you to create a new session.

### 📌 Endpoint
**POST** `/session/create`

### 🔧 Headers:
| Key       | Value            |
|-----------|-----------------|
| `x-api-key` | your_api_key    |
| `Content-Type` | application/json |

### 📤 Request Body:
```json
{
    "expiresIn": "100",
    "requestID": "xxxxx"
}
```
### Response:
```json

{
  "sessionId": "string",
  "status": "string"
}

```

```javascript
async function createSession(apiKey, requestID, expiresIn) {
    const response = await fetch('https://api.ultronai.me/session/create', {
        method: 'POST',
        headers: {
            'x-api-key': apiKey,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ requestID, expiresIn })
    });

    const data = await response.json();
    console.log('Session Created:', data);
}

createSession('your_api_key', '123', 10);

// Use this sessionId in the SDK in your Web App
// Call this method on your server side for security and avoid exposing your API key

```
Note: Please use the method above to get session id on your server side for a secure workflow

---


## Options

## Always listen

Makes the character listen all the time once click  for continous conversation (voice to voice)

- `alwaysListen`: **Boolean** - The unique identifier for the avatar

## Hide default click message

Hides the default text message on the avatar to prompt user to click as an initial click is required for any audio to play in any browser

- `hideClickMessage`: **Boolean** - The unique identifier for the avatar


## Core Methods

### loadAvatar(avatarId)

Loads a specific avatar into the container.

- `avatarId`: **String** - The unique identifier for the avatar


### AvatarId

To get avatarId follow the steps below

### Step 1: Open the desired avatar in ultron app (app.ultronai.me)

Click share on top right corner

![Avatar ID step 1](https://media.ultronai.me/Images/website/avateridshar1.png)

### Step 1: Open the desired avatar in ultron app (app.ultronai.me)

Step 2: Select the avatar id value as from share url

![Avatar ID step 2](https://media.ultronai.me/Images/website/avartaridshare2.png)

---


## Audio Input Device Settings

```javascript

// to get all microphone input devices
const devices = ultronSDK.getAudioInputDevices()

// You can also use the devices to allow user to choose from the list

let myDevice = devices.find(device=> device.label.includes("My_preffered_device_name"))

// to set the desired Audio input device
if(myDevice)
ultronSDK.setAudioInputDevice(myDevice.deviceId)


```




## Browser Support

✅ Chrome (latest)  
✅ Firefox (latest)  
✅ Safari (latest)  
✅ Edge (latest)

---


## Requirements

- WebGL-enabled browser
- JavaScript enabled
- Minimum screen resolution: 800x600

---


## Best Practices

- Always initialize the SDK with a valid API key
- Implement error handling for load failures
- Clean up resources when removing the avatar
- Optimize container size for better performance
- Test across different browsers and devices

---


## Examples

### Basic Implementation

```javascript
    import {SceneCanvas, Character} from 'ultron-ai-sdk';        
        
    let sceneCanvas
    let character
    
    const init = async() => {
        sceneCanvas = new SceneCanvas('target-html-element')
        const initializationSetting= {
            avatarId: "AVATAR_ID/REQUEST_ID",
            config:{
                sessionId: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxx"
            },
            options:{
                alwaysListen: false // For Push to talk conversation
            }
        }
        await sceneCanvas.init(initializationSetting)
        character = sceneCanvas.character
                    
    }
    init()
```

---


### Chat with character using AI

```javascript
// once you have the "character" object from sceneCanvas after init() you can use it to chat

character.chat("your text query to AI")

//This will generate a response from AI as per Avatar backstory and character will speak the response


```

### Make the character say

```javascript

character.say("your text that character will speak")

// This will simply make the character speak the text you provide

```

### Switch camera

```javascript
//Switch camera to potrait (closer to face)

sceneCanvas.switchCameraToPotrait()

//Switch camera to normal position (full body view)

sceneCanvas.switchCameraToNormal()



```

### Support

For technical support or questions, please contact our support team or visit our documentation portal.

### License

This SDK is provided under the terms of our software license agreement.



This README.md provides comprehensive documentation for your Ultron AI SDK. You can save this content directly to your project's README.md file. The documentation includes:

1. Basic introduction
2. Feature list
3. Installation instructions
4. Quick start guide
5. Detailed API reference
6. Usage examples
7. Browser support
8. Requirements
9. Best practices
10. Support information
11. License information

Would you like me to modify any section or add more specific details about certain features?