Ionic Angular

Available on: Web platform Android iOS

Integrating with Alan AI

To integrate an Ionic Angular app with Alan AI, you need to do the following:

  1. Create an Ionic Angular app

  2. Install Alan AI packages

  3. Add the Alan AI button

Step 1. Create an Ionic Angular app

If you want to create a voice-enabled app from scratch, in the Terminal, run the following commands. Otherwise move on to step 2.

Terminal
npm install -g ionic
cd <appFolder>
ionic start <appName> <template> [options]

For details, see Ionic documentation.

Step 2. Install Alan AI packages

You need to install the Alan AI SDK Cordova component and Alan AI Web Component package.

  1. Navigate to the folder where your app resides:

    Terminal
    cd appName
    
  2. Install the Alan AI SDK Cordova component:

    Terminal
    npm install @alan-ai/cordova-plugin-alan-voice --save
    
  3. Install the Alan AI Web Component package:

    Terminal
    npm install @alan-ai/alan-button --save
    

Note

To be able to run Ionic apps on mobile devices, you must install the Alan AI button as the Web Component using the following packages: @alan-ai/alan-button and @alan-ai/cordova-plugin-alan-voice. Do not use the @alan-ai/alan-sdk-web package: it is intended for non cross-platform web apps and pages.

Step 3. Add the Alan AI button

To add the Alan AI button to your app:

  1. Enable usage of custom HTML tags with AngularJS in the app. Include CUSTOM_ELEMENTS_SCHEMA in all modules where you will use custom elements:

    app.module.ts
    import {CUSTOM_ELEMENTS_SCHEMA} from '@angular/core';
    
    @NgModule({
      schemas: [CUSTOM_ELEMENTS_SCHEMA],
    })
    export class AppModule {}
    

    see full source

  2. Register the Alan AI Web Component. In main.ts, import the @alan-button component and call the defineCustomElements(window) method:

    main.ts
    import {defineCustomElements as alanBtnDefineCustomElements} from '@alan-ai/alan-button/dist/loader';
    
    alanBtnDefineCustomElements(window);
    

    see full source

  3. Add the Alan AI button HTML tag to the main app’s template. Open app.component.html and add the following tag:

    app.component.html
    <ion-app>
      <ion-router-outlet></ion-router-outlet>
      <alan-button #alanBtnEl alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE"></alan-button>
    </ion-app>
    
  4. In the Alan AI button HTML tag, replace YOUR_KEY_FROM_ALAN_STUDIO_HERE with the Alan AI SDK key for your Alan AI Studio project. To get the key, in Alan AI Studio, at the top of the code editor, click Integrations and copy the value from the Alan SDK Key field.

    app.component.html
    <ion-app>
      <ion-router-outlet></ion-router-outlet>
      <alan-button #alanBtnEl alan-key="ff4f9c03e405a5a07d43485dbc3cb44a2e956eca572e1d8b807a3e2338fdd0dc/prod"></alan-button>
    </ion-app>
    
  5. In the src/app folder, in app.component.ts, add the import statement for the Alan button Web Component:

    app.component.ts
    import "@alan-ai/alan-button";
    
  6. In the AppComponent class, use @ViewChild to add a reference to the Alan AI button element:

    app.component.ts
    @ViewChild('alanBtnEl', {static:false}) alanBtnComponent: ElementRef<HTMLAlanButtonElement>;
    
  7. Replace the first import statement with the following one:

    app.component.ts
    import { Component, ElementRef, ViewChild } from '@angular/core';
    
  8. In the AppComponent class, in the ngAfterViewInit() method, add a listener for the command event. All commands sent from the dialog script will be passed to this method. It’s a place where you can set up logic on how the app will react to commands from the dialog script.

    app.component.ts
    ngAfterViewInit() {
      this.alanBtnComponent.nativeElement.addEventListener('command', (data) => {
        const commandData = (<CustomEvent>data).detail;
    
        if (commandData.command === 'navigation') {
          /* Call client code that will react to the received command */
        }
      });
    }
    

    see full source

That’s it. You can now add voice commands to the script in Alan AI Studio, run the app, click the Alan AI button and interact with the app with voice.

Note

Regularly update the Alan AI packages your project depends on. To check if a newer version is available, run npm outdated. To update the package, run npm update <alan-package-name>. For more details, see npm documentation.

Specifying the Alan AI button parameters

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

Name

Type

Description

alan-key

string

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

authData

JSON object

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

Using client API methods

You can use the following client API methods in your app:

setVisualState()

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

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

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.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 commands. For details, see callProjectApi().

Dialog script
projectAPI.myFunc = function(p, param, callback) {
  console.log(param);
};
Client app
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()

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

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

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.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
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.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
var myAlanBtn = document.getElementById('myAlanBtn');

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

activate()

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

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

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

deactivate()

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

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

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

isActive()

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

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

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

remove()

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

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

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

getWakewordEnabled()

Use the getWakewordEnabled() method to check the state of the wake word for the Alan AI button. For details, see getWakewordEnabled().

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

myAlanBtn.componentOnReady().then(function () {
  const isWakewordEnabled = await myAlanBtn.getWakewordEnabled();
});

setWakewordEnabled()

Use the setWakewordEnabled() method to enable or disable the wake word for the Alan AI button. For details, see setWakewordEnabled().

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

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.setWakewordEnabled(true);
});

Using handlers

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

onCommand handler

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

Client app
this.alanBtnComponent.nativeElement.addEventListener('command', (data) => {
  const commandData = (<CustomEvent>data).detail;
  if (commandData.command === 'navigation') {
     // 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
this.alanBtnComponent.nativeElement.addEventListener('buttonState', (data) => {
  const buttonState = (<CustomEvent>data).detail;
  this.buttonStatusSectionEl.nativeElement.innerText = this.buttonStatusSectionEl.nativeElement.innerText + buttonState + '\n';
});

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
this.alanBtnComponent.nativeElement.addEventListener('connectionStatus', (data) => {
  const connectionData = (<CustomEvent>data).detail;
  console.info('Received status: ', connectionData);
});

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
this.alanBtnComponent.nativeElement.addEventListener('event', (data) => {
  const event = (<CustomEvent>data).detail;
  this.eventSectionEl.nativeElement.innerText = this.eventSectionEl.nativeElement.innerText + JSON.stringify(event) + '\n\n';
});

What’s next?

Example apps

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