React¶
Integrating with Alan AI¶
To integrate a React app with Alan AI:
Add the Alan AI Web SDK to your app. You can do it in two ways:
With the npm package
In the browser library mode
To install the Alan AI Web SDK with the npm package:
To load the Alan AI Web SDK in the browser library mode, add the
alan_lib.min.js
library to theindex.html
file using the<script>
tag:Client app¶<script type="text/javascript" src="https://studio.alan.app/web/lib/alan_lib.min.js"></script>
Add the Alan AI agentic interface to your React component:
React functional component
React class component
Client app¶import React, { useEffect } from 'react'; useEffect(() => { alanBtn({ key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE', host: 'v1.alan.app', onCommand: (commandData) => { if (commandData.command === 'go:back') { // Call the client code that will react to the received command } } }); }, []);
If you want to access the component state (or props) inside the callbacks that are passed to the AlanButton, please remember that you may face the «stale closure» problem that occurs because of the closure. To avoid this problem, you may use refs to store your state as shown in the example below:
Client app¶function useStateReference(value) { const ref = useRef(value); const [, forceRender] = useState(false); function updateState(newState) { if (!Object.is(ref.current, newState)) { ref.current = newState; forceRender(s => !s); } } return [ref, updateState]; } function App() { const [count, setCount] = useStateReference({}); useEffect(() => { alanBtn({ key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE', host: 'v1.alan.app', onCommand: () => { console.info('Actual count value:', count.current); } }); }, []); return ( <div className="App"> </div> ); }
With the code above, the count variable will hold the «actual» value.
Client app¶componentDidMount() { this.alanBtnInstance = alanBtn({ key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE', host: 'v1.alan.app', onCommand: (commandData) => { if (commandData.command === 'go:back') { // Call the client code that will react to the received command } }, }); }
Note
Regularly update the @alan-ai/alan-sdk-web
package your project depends on. To check if a newer version is available, run npm outdated
. To update the alan package, run npm update @alan-ai/alan-sdk-web
. For more details, see npm documentation.
Specifying the Alan AI agentic interface parameters¶
You can specify the following parameters for the Alan AI agentic interface added to your app:
Name |
Type |
Description |
---|---|---|
|
string |
The Alan AI SDK key for a project in Alan AI Studio. |
|
string |
The Alan AI Studio host to which the AI assistant button must connect, for example: |
|
string |
The default theme to be used for the Alan AI agentic interface and Text Chat, for example: |
|
JSON object |
The authentication or configuration data to be sent to the dialog script. For details, see authData. |
|
HTMLElement |
The element where Alan AI agentic interface will be added. If no |
|
string |
Specifies how the Agentic Interface should be rendered. Use |
|
HTMLElement |
The element where the Agentic Interface should be added if the |
|
Boolean |
The property signaling whether the overlay fade effect must be used when the microphone permission prompt in the browser is displayed. The overlay effect makes the prompt more noticeable and helps make sure users provide microphone access to the Agentic Interface. |
|
function |
A callback for handling commands from the dialog script. In this callback, you can set up logic on how your app must react to commands received from the dialog script. For details, see onCommand handler. |
|
function |
A callback for receiving the connection state of the Alan AI agentic interface. For details, see onButtonState handler. |
|
function |
A callback for receiving the connection state of the Agentic Interface project run in the Alan AI Cloud. For details, see onConnectionStatus handler. |
|
function |
A callback responsible for handling events received from Alan AI. For details, see onEvent handler. |
|
object |
Provides additional configuration options and handlers for managing the Alan AI Agentic Interface. For details, see the table below. |
textChat Properties
Name |
Type |
Description |
---|---|---|
|
number |
Specifies the delay (in milliseconds) for the close animation in inline mode. |
|
boolean |
Determines whether the Agentic Interface should be shown in inline mode. |
|
boolean |
Indicates whether the Agentic Interface should be open or closed by default when rendered in inline mode. |
|
function |
A callback function that is triggered when the Agentic Interface is opened. |
|
function |
A callback function that is triggered when the Agentic Interface is closed. |
|
function |
A callback function that is triggered when the Agentic Interface is minimized. |
Changing the Alan AI agentic interface position¶
By default, the Alan AI agentic interface is placed in the bottom right corner of the window. To change the Alan AI agentic interface position, you can use the following options for the alanBtn
variable:
left
: sets the Alan AI agentic interface position from the left edgeright
: sets the Alan AI agentic interface position from the right edgetop
: sets the Alan AI agentic interface position from the top edgebottom
: sets the Alan AI agentic interface position from the bottom edgezIndex
: sets the z-order of the Alan AI agentic interface
alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
bottom: '50px',
left: '50px',
zIndex: 10
});
Using client API methods¶
You can use the following client API methods in your React app:
setVisualState()¶
Use the setVisualState()
method to inform the Agentic Interface about the app’s visual context. For details, see setVisualState().
import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';
function App() {
const alanBtnRef = useRef({}).current;
useEffect(() => {
alanBtnRef.btnInstance = alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
});
}, []);
return (
<div className="App">
<button onClick={() => {
alanBtnRef.btnInstance.setVisualState({ data: 'your data' });
}}>Send visual state</button>
</div>
);
}
export default App;
callProjectApi()¶
Use the callProjectApi()
method to send data from the client app to the dialog script and trigger activities without voice and text commands. For details, see callProjectApi().
projectAPI.setClientData = function(p, param, callback) {
console.log(param);
};
import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';
function App() {
const alanBtnRef = useRef({}).current;
useEffect(() => {
alanBtnRef.btnInstance = alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
});
}, []);
return (
<div className="App">
<button onClick={() => {
alanBtnRef.btnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
// handle error and result here
});
}}>Call setClientData method</button>
</div>
);
}
export default App;
playText()¶
Use the playText()
method to play specific text in the client app. For details, see playText().
import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';
function App() {
const alanBtnRef = useRef({}).current;
useEffect(() => {
alanBtnRef.btnInstance = alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
});
}, []);
return (
<div className="App">
<button onClick={() => {
alanBtnRef.btnInstance.playText("Hi there, I am Alan");
}}>Play text</button>
</div>
);
}
export default App;
sendText()¶
Use the sendText()
method to send a text message to Alan AI as the user’s input. For details, see sendText().
import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';
function App() {
const alanBtnRef = useRef({}).current;
useEffect(() => {
alanBtnRef.btnInstance = alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
});
}, []);
return (
<div className="App">
<button onClick={() => {
alanBtnRef.btnInstance.sendText("Hello Alan, can you help me?");
}}>Play text</button>
</div>
);
}
export default App;
playCommand()¶
Use the playCommand()
method to execute a specific command in the client app. For details, see playCommand().
import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';
function App() {
const alanBtnRef = useRef({}).current;
useEffect(() => {
alanBtnRef.btnInstance = alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
onCommand: (commandData) => {
if (commandData.command === 'goBack') {
// Call client code that will react to the received command
}
},
});
}, []);
return (
<div className="App">
<button onClick={() => {
alanBtnRef.btnInstance.playCommand({command: "goBack"});
}}>Play command</button>
</div>
);
}
export default App;
activate()¶
Use the activate()
method to activate the Alan AI agentic interface programmatically. For details, see activate().
import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';
function App() {
const alanBtnRef = useRef({}).current;
useEffect(() => {
alanBtnRef.btnInstance = alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
});
}, []);
return (
<div className="App">
<button onClick={() => {
alanBtnRef.btnInstance.activate();
}}>Activate the Alan AI agentic interface</button>
</div>
);
}
export default App;
deactivate()¶
Use the deactivate()
method to deactivate the Alan AI agentic interface programmatically. For details, see deactivate().
import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';
function App() {
const alanBtnRef = useRef({}).current;
useEffect(() => {
alanBtnRef.btnInstance = alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
});
}, []);
return (
<div className="App">
<button onClick={() => {
alanBtnRef.btnInstance.deactivate();
}}>Deactivate the Alan AI agentic interface</button>
</div>
);
}
export default App;
isActive()¶
Use the isActive()
method to check the Alan AI agentic interface state: active or not. For details, see isActive().
import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';
function App() {
const alanBtnRef = useRef({}).current;
useEffect(() => {
alanBtnRef.btnInstance = alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
});
}, []);
return (
<div className="App">
<button onClick={() => {
console.log('Button is active: ' + alanBtnRef.btnInstance.isActive());
}}>Check the button state</button>
</div>
);
}
export default App;
remove()¶
Use the remove()
method to remove the Alan AI agentic interface from the parent element. For details, see remove().
import alanBtn from '@alan-ai/alan-sdk-web';
import React, { useEffect, useRef } from 'react';
function App() {
const alanBtnRef = useRef({}).current;
useEffect(() => {
alanBtnRef.btnInstance = alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
});
}, []);
return (
<div className="App">
<button onClick={() => {
alanBtnRef.btnInstance.remove();
}}>Remove the Alan AI agentic interface</button>
</div>
);
}
export default App;
textChat.isAudioOutputEnabled()¶
Use the textChat.isAudioOutputEnabled()
method to get the state of audio output for the Alan AI Agentic Interface. For details, see textChat.isAudioOutputEnabled().
alanBtnInstance.textChat.isAudioOutputEnabled()
textChat.setAudioOutputEnabled()¶
Use the textChat.setAudioOutputEnabled()
method to enable or disable audio output for the Alan AI Agentic Interface. For details, see textChat.setAudioOutputEnabled().
alanBtnInstance.textChat.setAudioOutputEnabled(true)
textChat.setFullScreenMode()¶
Use the textChat.setFullScreenMode()
method allows switching the Alan AI Agentic Interface between full-screen and normal view. For details, see textChat.setFullScreenMode().
alanBtnInstance.textChat.setFullScreenMode(true);
textChat.open()¶
Use the textChat.open()
method to open the Alan AI Agentic Interface. For details, see textChat.open().
alanBtnInstance.textChat.open(); // Opens the Alan AI Agentic Interface
textChat.close()¶
Use the textChat.close()
method to close the Alan AI Agentic Interface. For details, see textChat.close().
alanBtnInstance.textChat.close(); // Closes the Alan AI Agentic Interface
textChat.minimize()¶
Use the textChat.minimize()
method to minimize the Alan AI Agentic Interface. For details, see textChat.minimize().
alanBtnInstance.textChat.minimize(); // Minimizes the Alan AI Agentic Interface
textChat.clear()¶
Use the textChat.clear()
method to clear the Alan AI Agentic Interface. For details, see textChat.clear().
alanBtnInstance.textChat.clear(); // Clears the Agentic Interface history.
theme.setTheme(theme)¶
Use the theme.setTheme(theme)
method to set the Alan AI Agentic Interface theme to either light
and dark
. For details, see theme.setTheme(theme).
alanBtnInstance.theme.setTheme('light');
theme.getTheme()¶
Use the theme.getTheme()
method to retrieve the current theme of the Alan AI Agentic Interface. For details, see theme.getTheme().
alanBtnInstance.theme.getTheme(); // returns 'light' or 'dark'
Using handlers¶
You can use the following Alan AI handlers in your React app:
onCommand handler¶
Use the onCommand
handler to handle commands sent from the dialog script. For details, see onCommand handler.
alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
onCommand: (commandData) => {
if (commandData.command === 'go:back') {
// Call client code that will react to the received command
}
},
});
onButtonState handler¶
Use the onButtonState
handler to capture and handle the Alan AI agentic interface state changes. For details, see onButtonState handler.
alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
onButtonState: function (e) {
console.info('onButtonState', e);
},
});
onConnectionStatus handler¶
Use the onConnectionStatus
handler to capture and handle the connection status for the Agentic Interface project. For details, see onConnectionStatus handler.
alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
onConnectionStatus: function(status) {
console.log("The status is " + status);
},
});
onEvent handler¶
Use the onEvent
handler to capture and handle events emitted by Alan AI: get user’s utterances, Agentic Interface responses and so on. For details, see onEvent handler.
alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
host: 'v1.alan.app',
onEvent: function (e) {
console.info('onEvent', e);
},
});
textChat parameter¶
Use the textChat
to provide additional configuration options and handlers for managing the Alan AI Agentic Interface in “inlined” mode. For details, see textChat parameter.