Documentation

Powered by Algolia

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 an NPM package or a javascript library. Check the instructions on how you can add the Alan button to the page:

NPM module

  1. Install @alan-ai/alan-sdk-web using NPM.

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

    <div class="alan-btn"></div>
  3. Import 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")
      });

Browser library mode

Alan Web SDK can be also added to the page via the script tag. To do this:

  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 Studio project key.
rootEl HTMLElement The element where Alan button will be added. If no rootEl provided, the Alan button is added to the body.
onCommand function Callback for receiving commands from the Alan Studio script. In this callback you can set the reaction of your app on the commands which will be received form the Alan Studio script. Learn more
onConnectionStatus function Callback for receiving the connection status of the Alan button. Learn more

Example of using the onCommandCb callback:

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

  // Client-side script
  var alanBtnInstance = alanBtn({
    key: "0717498b05e694d0b083b897e50a49102e956eca572e1d8b807a3e2338fdd0dc/stage",
    onCommand: function (commandData) {
      if (commandData.command === "go:back") {
        //call client code that will react on 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

setVisualState (visualStateData: object)

Method for setting the visual state

visualStateData - data that represents a visual state

  //this is how you can set up a visual state
  alanBtnInstance.setVisualState({data:"your data"});

callProjectApi (method:string, data:object, callback:function)

Method for calling a project api that was defined in Alan Studio project’s script

method - projectAPI method name that was defined in the voice script

data - data that should be passed

callback - callback that could be called from project API method

  // Voice script
  projectAPI.setClientData = function(p, param, callback) {
    p.userData.value = param.value;
    callback();
  };

  // this is how you can call clientAPI.setClientData function
  alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
    //handle error and result here
  });

playText(text:string)

Method for playing voice

text - text that should be played

  alanBtnInstance.playText("Hi! I am Alan");

playCommand(command:object)

Method for sending a command

command - object that represents a command

  alanBtnInstance.playCommand({command:"navigate", screen: "settings"});

activate()

Method for turning on the Alan button programmatically

  alanBtnInstance.activate();

deactivate()

Method for turning off the Alan button programmatically

  alanBtnInstance.deactivate();

isActive()

Method for checking the Alan button state. Returns true if the Alan button is activated by the user or programmatically or false if the Alan button is deactivated by the user or programmatically.

  alanBtnInstance.isActive();

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