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.

Installation

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();

Web Component API

The Alan Button can be added to your application as a Web Component. This is an instruction of how you can add the Alan Button to the page as a Web Component:

  1. Add source code of the Alan Button Web Component to your page/project. Install @alan-button package from npm (npm install @alan-button):

    • Use it in your project with import statement
    • or add the following script tag to you HTML page: <script src="(path_to_node_modules)/@alan-button/dist/alancomponents.js"></script>
  2. Add the following tag to the HTML page, your view, or template.
<alan-btn id="myAlanBtn"
          alan-key="0717498b05e694d0b083b897e50a49102e956eca572e1d8b807a3e2338fdd0dc/stage"></alan-btn>

Add the Alan Button Web Component doesn't differ from adding any other Web Component. We support several frameworks: Ionic, Angular, React, Vue, Ember.

Also you can use the Alan Button Web Component in your Electron app or Vanilla JS app.

Web Component Attributes

Name Type Description
alan-key string The Alan Studio project key.

Methods

setVisualState (visualStateData: object)

Method for setting the visual state

visualStateData - data that represents a visual state

  var myAlanBtn = document.getElementById('myAlanBtn');

  myAlanBtn.componentOnReady().then(function () {
      myAlanBtn.setVisualState({screen: 'homePage'});
  });

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

  //(in the script in AT project)
  projectAPI.myFunc = (p, param, callback) => {
    p.play("myFunc was called");
    p.play(param);
    callback(null,{"newParam":111});
  };

  //(in the JS script)
  var myAlanBtn = document.getElementById('myAlanBtn');
  myAlanBtn.componentOnReady().then(function () {
    myAlanBtn.callProjectApi("myFunc", {myData: 123}, function (error, result) {
      console.log("cb from myFunc was received", error, result);
    });

  });

playText(text:string)

Method for playing voice

text - text that should be played

  var myAlanBtn = document.getElementById('myAlanBtn');

  myAlanBtn.componentOnReady().then(function () {
      myAlanBtn.playText("Hi! I am Alan");
  });

playCommand(command:object)

Method for sending a command

command - object that represents a command

  var myAlanBtn = document.getElementById('myAlanBtn');

  myAlanBtn.componentOnReady().then(function () {
      myAlanBtn.playCommand({command:"navigate", screen: "settings"});
  });

activate()

Method for turning on the Alan Button programmatically

  var myAlanBtn = document.getElementById('myAlanBtn');

  myAlanBtn.componentOnReady().then(function () {
      myAlanBtn.activate();
  });

deactivate()

Method for turning off the Alan Button programmatically

  var myAlanBtn = document.getElementById('myAlanBtn');

  myAlanBtn.componentOnReady().then(function () {
      myAlanBtn.deactivate();
  });

Events

command

Received when command is received from the AT script.

  var myAlanBtn = document.getElementById('myAlanBtn');

  myAlanBtn.addEventListener('command', function (data) {
      console.info('Received command:', data.detail);
  });

сonnectionStatus

Received when new connection status for Alan Button was gotten.

  var myAlanBtn = document.getElementById('myAlanBtn');

  myAlanBtn.addEventListener('connectionStatus', function (data) {
      console.info('Received status:', data.detail);
  });