Alan Web SDK


Alan Web SDK can bring voice to any website. It’s a lightweight JavaScript library for adding a voice experience to your website or web application.

Integration

The Alan button can be added to your application as:

  • NPM package

  • JavaScript library

Check the instructions on how you can add the Alan button to the page:

  1. In the Terminal, run the command:

    npm install @alan-ai/alan-sdk-web --save
    
  2. Add a <div> for appending the Alan button:

    <div class="alan-btn"></div>
    
  3. Import the alanBtn function from the @alan-ai/alan-sdk-web package and add the Alan button to the page:

    import alanBtn from "@alan-ai/alan-sdk-web";
    
    alanBtn({
      key: "ALAN_STUDIO_API_KEY",
      rootEl: document.getElementById("alan-btn"),
    });
    
  1. Add the script to the page:

    <script type="text/javascript" src="https://studio.alan.app/web/lib/alan_lib.js"></script>
    
  2. Add a <div> for appending the Alan button:

    <div class="alan-btn"></div>
    
  3. It will now be available as a global variable named alanBtn:

    var alanBtnInstance = alanBtn({
      key: "ALAN_STUDIO_API_KEY",
      rootEl: document.getElementById("alan-btn"),
    });
    

Alan button parameters

Name

Type

Description

key

string

The Alan SDK key for the Alan Studio project.

rootEl

HTMLElement

The element where Alan button will be added. If no rootEl is provided, the Alan button is added to the body.

showOverlayOnMicPermissionPrompt

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 voice assistant.

onCommand

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.

onButtonState

function

A callback for receiving the connection state of the Alan button. For details, see onButtonState handler.

onEventHandler

function

A callback Responsible for handling events received from Alan. For details, see onEvent handler.

Example of using the onCommandCb callback:

// Voice script
intent('Go back', 'Go back to the previous screen', (p) => {
   p.play('Opening the previous screen');
   p.play({command:'go:back'});
});

// Client app
var alanBtnInstance = alanBtn({
  key: "0717498b05e694d0b083b897e50a49102e956eca572e1d8b807a3e2338fdd0dc/stage",
  onCommand: function (commandData) {
    if (commandData.command === "go:back") {
      // Call client code that will react to the received command
    }
  },
  rootEl: document.getElementById("alan-btn"),
});

Example of using the onConnectionStatus callback:

var alanBtnInstance = alanBtn({
  key: "0717498b05e694d0b083b897e50a49102e956eca572e1d8b807a3e2338fdd0dc/stage",
  onConnectionStatus: function (status) {
     // status could be connected or disconnected
  },
  rootEl: document.getElementById("alan-btn"),
});

Alan button methods

For details on methods exposed for the Alan Web SDK, see Client API methods.

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 edge

  • right: sets the Alan button position from the right edge

  • top: sets the Alan button position from the top edge

  • bottom: sets the Alan button position from the bottom edge

  • zIndex: sets the z-order of a the Alan button

var alanBtnInstance = alanBtn({
   key: "0717498b05e694d0b083b897e50a49102e956eca572e1d8b807a3e2338fdd0dc/stage",
   onConnectionStatus: function(status) {
      // status could be connected or disconnected
   },
   rootEl: document.getElementById("alan-btn"),
   bottom: '50px',
   left: '50px',
   zIndex: 10
});