JavaScript¶
You can integrate a simple HTML page with Alan using JavaScript without any frameworks.
Integrating with Alan¶
You can add the Alan button to your page in two ways:
With the npm package
In the browser library mode
In the Terminal, run the command:
Terminal¶npm install @alan-ai/alan-sdk-web --save
Add a
<div>
for appending the Alan button:Client app¶<div class="alan-btn"></div>
Import the
alanBtn
function from the@alan-ai/alan-sdk-web
package and add the Alan button to the page:Client app¶import alanBtn from "@alan-ai/alan-sdk-web"; var alanBtnInstance = alanBtn({ key: "YOUR_KEY_FROM_ALAN_STUDIO_HERE", onCommand: function (commandData) { if (commandData.command === "go:back") { // Call the client code that will react to the received command } }, rootEl: document.getElementById("alan-btn"), });
Add the
<script>
tag to the page:Client app¶<script type="text/javascript" src="https://studio.alan.app/web/lib/alan_lib.min.js"></script>
Add a
<div>
for appending the Alan button:Client app¶<div class="alan-btn"></div>
Add the Alan button in the
<script>
tag like this:Client app¶<script> var alanBtnInstance = alanBtn({ key: "YOUR_KEY_FROM_ALAN_STUDIO_HERE", onCommand: function (commandData) { if (commandData.command === "go:back") { // Call the client code that will react to the received command } }, rootEl: document.getElementById("alan-btn"), }); </script>
Note
Mind the following:
Regularly update the
@alan-ai/alan-sdk-web
package your project depends on. To check if a newer version is available, runnpm outdated
. To update the alan package, runnpm update @alan-ai/alan-sdk-web
. For more details, see npm documentation.If you add the Alan button to a multi-page app or website, the Alan button will be reloaded on every redirect or page refresh. To store and access the data required for the dialog session, use the localStorage and sessionStorage objects. Alternatively, you can design your project as a single-page app.
Specifying the Alan button parameters¶
You can specify the following parameters for the Alan button added to your app:
Name |
Type |
Description |
---|---|---|
|
string |
The Alan SDK key for a project in Alan Studio. |
|
JSON object |
The authentication or configuration data to be sent to the voice script. For details, see authData. |
|
HTMLElement |
The element where Alan button will be added. If no |
|
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 in-app assistant. |
|
function |
A callback for handling commands from the Alan voice script. In this callback, you can set up logic on how your app must react to commands received from the voice script. For details, see onCommand handler. |
|
function |
A callback for receiving the connection state of the Alan button. For details, see onButtonState handler. |
|
function |
A callback for receiving the connection state of the voice project run in the Alan Cloud. For details, see onConnectionStatus handler. |
|
function |
A callback responsible for handling events received from Alan. For details, see onEvent handler. |
Changing the Alan button position¶
By default, the Alan button is placed in the bottom right corner of the window. To change the Alan button position, you can use the following options for the alanBtn
variable:
left
: sets the Alan button position from the left edgeright
: sets the Alan button position from the right edgetop
: sets the Alan button position from the top edgebottom
: sets the Alan button position from the bottom edgezIndex
: sets the z-order of the Alan button
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 page or app:
setVisualState()¶
Use the setVisualState()
method to inform the in-app assistant about the app’s visual context. For details, see setVisualState().
alanBtnInstance.setVisualState({data:"your data"});
callProjectApi()¶
Use the callProjectApi()
method to send data from the client app to the voice script and trigger activities without voice commands. For details, see callProjectApi().
projectAPI.setClientData = function(p, param, callback) {
console.log(param);
};
alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
// Handling error and result
});
playText()¶
Use the playText()
method to play specific text in the client app. For details, see playText().
alanBtnInstance.playText("Hi! I am Alan");
sendText()¶
Use the sendText()
method to send a text message to Alan as the user’s input. For details, see sendText().
alanBtnInstance.sendText("Hello, Alan, can you help me?");
playCommand()¶
Use the playCommand()
method to execute a specific command in the client app. For details, see playCommand().
alanBtnInstance.playCommand({command:"navigate", screen: "settings"});
activate()¶
Use the activate()
method to activate the Alan button programmatically. For details, see activate().
alanBtnInstance.activate();
deactivate()¶
Use the deactivate()
method to deactivate the Alan button programmatically. For details, see deactivate().
alanBtnInstance.deactivate();
isActive()¶
Use the isActive()
method to check the Alan button state: active or not. For details, see isActive().
alanBtnInstance.isActive();
Using handlers¶
You can use the following Alan handlers in your page or app:
onCommand handler¶
Use the onCommand
handler to handle commands sent from the voice script. For details, see onCommand handler.
alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
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 button state changes. For details, see onButtonState handler.
alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
onButtonState: function (e) {
console.info('onButtonState', e);
},
});
onConnectionStatus handler¶
Use the onConnectionStatus
handler to capture and handle the connection status for the voice project. For details, see onConnectionStatus handler.
alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
onConnectionStatus: function(status) {
console.log("The status is " + status);
},
});
onEvent handler¶
Use the onEvent
handler to capture and handle events emitted by Alan: get user’s utterances, assistant responses and so on. For details, see onEvent handler.
alanBtn({
key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
onEvent: function (e) {
console.info('onEvent', e);
},
});