Vue


Integrating with Alan

To integrate a Vue app with Alan:

  1. Add the Alan 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 Web SDK with the npm package:

    1. In the Terminal, run the command:

      Terminal
      npm install @alan-ai/alan-sdk-web --save
      
    2. Import the alanBtn into your main.js file:

      Client app
      import alanBtn from "@alan-ai/alan-sdk-web";
      

    To load the Alan Web SDK in the browser library mode, add the alan_lib.min.js library to the index.html file using the <script> tag:

    Client app
    <script type="text/javascript" src="https://studio.alan.app/web/lib/alan_lib.min.js"></script>
    
  2. Add the Alan button to the main.js file in your project:

    Client app
    alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      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 button parameters

You can specify the following parameters for the Alan button added to your app:

Name

Type

Description

key

string

The Alan SDK key for a project in Alan Studio.

authData

JSON object

The authentication or configuration data to be sent to the voice script. For details, see authData.

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.

onConnectionStatus

function

A callback for receiving the connection state of the voice project run in the Alan Cloud. For details, see onConnectionStatus handler.

onEvent

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 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 the Alan button

Client app
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 Vue app:

setVisualState()

Use the setVisualState() method to inform the voice assistant about the app’s visual context. For details, see setVisualState().

main.js
import Vue from 'vue'
import App from './App.vue'
import alanBtn from "@alan-ai/alan-sdk-web";

Vue.config.productionTip = false

new Vue({
  render: h => h(App),
}).$mount('#app')

Vue.prototype.$alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
});
App.vue
<template>
  <div id="app">
    <button @click="setState">Set state</button>
  </div>
</template>

<script>
  export default {
    methods: {
      setState() {
        this.$alanBtnInstance.setVisualState({data: "yourdata"});
      }
    },
  }
</script>

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

Voice script
projectAPI.setClientData = function(p, param, callback) {
  console.log(param);
};
main.js
import Vue from 'vue'
import App from './App.vue'
import alanBtn from "@alan-ai/alan-sdk-web";

Vue.config.productionTip = false

new Vue({
  render: h => h(App),
}).$mount('#app')

Vue.prototype.$alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
});
App.vue
<template>
  <div id="app">
    <button @click="callMethod">Call setClientData</button>
  </div>
</template>

<script>
  export default {
    methods: {
      callMethod() {
        this.$alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
          // Handling error and result
        });
      }
    },
  }
</script>

playText()

Use the playText() method to play specific text in the client app. For details, see playText().

main.js
import Vue from 'vue'
import App from './App.vue'
import alanBtn from "@alan-ai/alan-sdk-web";

Vue.config.productionTip = false

new Vue({
  render: h => h(App),
}).$mount('#app')

Vue.prototype.$alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
});
App.vue
<template>
  <div id="app">
    <button @click="playText">Play text</button>
  </div>
</template>

<script>
  export default {
    methods: {
      playText() {
        this.$alanBtnInstance.playText("Hello, I am Alan!");
      }
    },
  }
</script>

playCommand()

Use the playCommand() method to execute a specific command in the client app. For details, see playCommand().

main.js
import Vue from 'vue'
import App from './App.vue'
import alanBtn from "@alan-ai/alan-sdk-web";

Vue.config.productionTip = false

new Vue({
  render: h => h(App),
}).$mount('#app')

Vue.prototype.$alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  onCommand: (commandData) => {
    if (commandData.command === 'goBack') {
      // Call client code that will react to the received command
    }
  }
});
App.vue
<template>
  <div id="app">
    <button @click="playCommand">Play command</button>
  </div>
</template>

<script>
  export default {
    methods: {
      playCommand() {
        this.$alanBtnInstance.playCommand({command: "goBack"});
      }
    },
  }
</script>

activate()

Use the activate() method to activate the Alan button programmatically. For details, see activate().

main.js
import Vue from 'vue'
import App from './App.vue'
import alanBtn from "@alan-ai/alan-sdk-web";

Vue.config.productionTip = false

new Vue({
  render: h => h(App),
}).$mount('#app')

Vue.prototype.$alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
});
App.vue
<template>
  <div id="app">
    <button @click="activateButton">Activate button</button>
  </div>
</template>

<script>
  export default {
    methods: {
      activateButton() {
        this.$alanBtnInstance.activate();
      }
    },
  }
</script>

deactivate()

Use the deactivate() method to deactivate the Alan button programmatically. For details, see deactivate().

main.js
import Vue from 'vue'
import App from './App.vue'
import alanBtn from "@alan-ai/alan-sdk-web";

Vue.config.productionTip = false

new Vue({
  render: h => h(App),
}).$mount('#app')

Vue.prototype.$alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
});
App.vue
<template>
  <div id="app">
    <button @click="deactivateButton">Deactivate button</button>
  </div>
</template>

<script>
  export default {
    methods: {
      deactivateButton() {
        this.$alanBtnInstance.deactivate();
      }
    },
  }
</script>

isActive()

Use the isActive() method to check the Alan button state: active or not. For details, see isActive().

main.js
import Vue from 'vue'
import App from './App.vue'
import alanBtn from "@alan-ai/alan-sdk-web";

Vue.config.productionTip = false

new Vue({
  render: h => h(App),
}).$mount('#app')

Vue.prototype.$alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
});
App.vue
<template>
  <div id="app">
    <button @click="checkState">Check button state</button>
  </div>
</template>

<script>
  export default {
    methods: {
      checkState() {
        console.log("The button is active: " + this.$alanBtnInstance.isActive());
      }
    },
  }
</script>

remove()

Use the remove() method to remove the Alan button from the parent element. For details, see remove().

main.js
import Vue from 'vue'
import App from './App.vue'
import alanBtn from "@alan-ai/alan-sdk-web";

Vue.config.productionTip = false

new Vue({
  render: h => h(App),
}).$mount('#app')

Vue.prototype.$alanBtnInstance = alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
});
App.vue
<template>
  <div id="app">
    <button @click="removeButton">Remove button</button>
  </div>
</template>

<script>
  export default {
    methods: {
      removeButton() {
        this.$alanBtnInstance.remove();
      }
    },
  }
</script>

Using handlers

You can use the following Alan handlers in your Vue app:

onCommand handler

Use the onCommand handler to handle commands sent from the voice script. For details, see onCommand handler.

Client app
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.

Client app
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.

Client app
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, voice assistant responses and so on. For details, see onEvent handler.

Client app
alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  onEvent: function (e) {
    console.info('onEvent', e);
  },
});

What’s next?

../../../_images/git-purple.svg

Example apps

Find and explore examples of voice-enabled apps on the Alan AI GitHub repository.

View on GitHub