Ember¶

Integrating with Alan¶

To integrate an Ember app with Alan:

Install the @alan-ai/alan-sdk-web package:
Terminal¶
```
npm install @alan-ai/alan-sdk-web --save
```
Install the ember-auto-import package to have an ability to use packages from npm:
Terminal¶
```
npm install ember-auto-import --save
```

Add the following code to the app.js file in your project:

Client app¶

window.alanBtnInstance = 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

Mind the following:

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.
For simplicity, in the examples provided in this section, we store the alanBtnInstance in the window variable. In your project, you can use any method that suits you best.

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 Ember app:

setVisualState()
callProjectApi()
playText()
playCommand()
activate()
deactivate()
isActive()
remove()

setVisualState()¶

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

Client app¶

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

Voice script¶

projectAPI.setClientData = function(p, param, callback) {
  console.log(param);
};

Client app¶

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

Client app¶

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

playCommand()¶

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

Client app¶

window.alanBtnInstance.playCommand({command: "goBack"});

activate()¶

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

Client app¶

window.alanBtnInstance.activate()

deactivate()¶

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

Client app¶

window.alanBtnInstance.deactivate()

isActive()¶

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

Client app¶

window.alanBtnInstance.isActive()

remove()¶

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

Client app¶

window.alanBtnInstance.remove()

Using handlers¶

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

onCommand handler
onButtonState handler
onConnectionStatus handler
onEvent handler

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?¶

Example apps

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

View on GitHub