Ember


Integrating with Alan AI

To integrate an Ember app with Alan AI:

  1. Install the @alan-ai/alan-sdk-web package:

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

    Terminal
    npm install ember-auto-import --save
    
  3. Add the following code to the app.js file in your project:

    Client app
    window.alanBtnInstance = alanBtn({
      key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
      host: 'v1.alan.app',
      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 AI button parameters

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

Name

Type

Description

key

string

The Alan AI SDK key for a project in Alan AI Studio.

host

string

The Alan AI Studio host to which the AI assistant button must connect, for example: 'v1.alan.app'.

authData

JSON object

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

rootEl

HTMLElement

The element where Alan AI button will be added. If no rootEl is provided, the Alan AI 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 AI agent.

onCommand

function

A callback for handling commands from the dialog script. In this callback, you can set up logic on how your app must react to commands received from the dialog script. For details, see onCommand handler.

onButtonState

function

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

onConnectionStatus

function

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

onEvent

function

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

Changing the Alan AI button position

By default, the Alan AI button is placed in the bottom right corner of the window. To change the Alan AI button position, you can use the following options for the alanBtn variable:

  • left: sets the Alan AI button position from the left edge

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

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

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

  • zIndex: sets the z-order of the Alan AI 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()

Use the setVisualState() method to inform the AI agent 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 dialog script and trigger activities without voice and text commands. For details, see callProjectApi().

Dialog 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");

sendText()

Use the sendText() method to send a text message to Alan AI as the user’s input. For details, see sendText().

Client app
window.alanBtnInstance.sendText("Hello Alan, can you help me?");

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 AI button programmatically. For details, see activate().

Client app
window.alanBtnInstance.activate()

deactivate()

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

Client app
window.alanBtnInstance.deactivate()

isActive()

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

Client app
window.alanBtnInstance.isActive()

remove()

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

Client app
window.alanBtnInstance.remove()

textChat.isAudioOutputEnabled()

Use the textChat.isAudioOutputEnabled() method to get the state of audio output for the Alan AI Chat. For details, see textChat.isAudioOutputEnabled().

Client app
alanBtnInstance.textChat.isAudioOutputEnabled()

textChat.setAudioOutputEnabled()

Use the textChat.setAudioOutputEnabled() method to enable or disable audio output for the Alan AI Chat. For details, see textChat.setAudioOutputEnabled().

Client app
alanBtnInstance.textChat.setAudioOutputEnabled(true)

textChat.setFullScreenMode()

Use the textChat.setFullScreenMode() method allows switching the Alan AI Chat interface between full-screen and normal view. For details, see textChat.setFullScreenMode().

Client app
alanBtnInstance.textChat.setFullScreenMode(true);

Using handlers

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

onCommand handler

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

Client app
alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  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 AI button state changes. For details, see onButtonState handler.

Client app
alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  onButtonState: function (e) {
    console.info('onButtonState', e);
  },
});

onConnectionStatus handler

Use the onConnectionStatus handler to capture and handle the connection status for the AI agent project. For details, see onConnectionStatus handler.

Client app
alanBtn({
  key: 'YOUR_KEY_FROM_ALAN_STUDIO_HERE',
  host: 'v1.alan.app',
  onConnectionStatus: function(status) {
    console.log("The status is " + status);
  },
});

onEvent handler

Use the onEvent handler to capture and handle events emitted by Alan AI: get user’s utterances, agent responses and so on. For details, see onEvent handler.

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

What’s next?

Example apps

Find and explore examples of AI agents in Alan AI GitHub.