Alan Ionic Framework

Available on: Web platform Android iOS

Integrating with Alan

Alan can be integrated with apps based on the following platforms:

  • Angular

  • React

  • Vue

To integrate an Ionic Angular app with Alan:

  1. 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.

  2. Navigate to the folder where your app resides:

    Terminal
    cd appName
    
  3. Install the Alan SDK Cordova component:

    Terminal
    npm install @alan-ai/cordova-plugin-alan-voice --save
    
  4. Install the Alan 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 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.

  5. Modify the app to add the Alan button:

    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 button 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 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 button HTML tag, replace YOUR_KEY_FROM_ALAN_STUDIO_HERE with the Alan SDK key for your Alan Studio project. To get the key, in Alan 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>
      
  6. In the src/app folder, in app.component.ts, make the following changes:

    1. Add the import statement for the Alan button Web Component:

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

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

      app.component.ts
      import { Component, ElementRef, ViewChild } from '@angular/core';
      
    4. In the AppComponent class, in the ngAfterViewInit() method, add a listener for the command event. All commands sent from the voice 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 voice 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 Studio, run the app, click the Alan 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.

To integrate an Ionic React app with Alan:

  1. 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.

  2. Navigate to the folder where your app resides:

    Terminal
    cd appName
    
  3. Install the Alan SDK Cordova component:

    Terminal
    npm install @alan-ai/cordova-plugin-alan-voice --save
    
  4. Install the Alan 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 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.

  5. Create a wrapper component for the Alan button. In the src/components app folder, create the AlanBtn.tsx file:

    AlanBtn.tsx
    import React, {
      useEffect,
      useRef,
    } from 'react';
    import { withRouter } from 'react-router';
    
    const AlanBtn: React.FC = (props: any) => {
      const alanBtnComponent = useRef<any>(null);
    
      useEffect(() => {
        alanBtnComponent.current.addEventListener('command', (data: CustomEvent) => {
          const commandData = data.detail;
    
          if (commandData.command === 'command') {
            /* Call client code that will react to the received command */
          }
        });
      }, []);
    
      return <alan-button ref={alanBtnComponent} alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />;
    };
    
    export default withRouter(AlanBtn);
    

    The Effect Hook in the Alan button component lets you subscribe to command events from Alan. It’s a place where you can set up logic on how your app will react to commands received from the voice script.

  6. In alan-key, replace YOUR_KEY_FROM_ALAN_STUDIO_HERE with the Alan SDK key for your Alan Studio project. To get the key, in Alan Studio, at the top of the code editor, click Integrations and copy the value from the Alan SDK Key field.

    AlanBtn.tsx
    ...
    const AlanBtn: React.FC = (props: any) => {
      ...
      return <alan-button ref={alanBtnComponent} alan-key="6f60897fd223a4367d43485dbc3cb44a2e956eca572e1d8b807a3e2338fdd0dc/stage" />;
    };
    
    export default withRouter(AlanBtn);
    
  7. In the App.tsx file, add the following import statement to import the Alan button component:

    App.tsx
    import AlanBtn from './components/AlanBtn';
    

    see full source

  8. In the App.tsx file, add the Alan button component:

    App.tsx
    ...
    const App: React.FC = () => (
      <IonApp>
        <IonReactRouter>
          ...
          <AlanBtn />
        </IonReactRouter>
      </IonApp>
    );
    ...
    

    see full source

  9. In the src folder, create a typescript declaration file named alan-btn.d.ts:

    alan-btn.d.ts
    declare namespace JSX {
      interface IntrinsicElements {
        [tagName:string]: any
      }
    }
    
  10. In the index.tsx file, import the Alan button component and bind it to the window object:

    index.tsx
    ...
    import {
      applyPolyfills,
      defineCustomElements,
    } from '@alan-ai/alan-button/dist/loader';
    
    ...
    applyPolyfills().then(_ => {
      defineCustomElements();
    });
    

    see full source

That’s it. You can now add voice commands to the script in Alan Studio, run the app, click the Alan 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.

To integrate an Ionic Vue app with Alan:

  1. 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> --type vue
    

    For details, see Ionic documentation.

  2. Navigate to the folder where your app resides:

    Terminal
    cd appName
    
  3. Install the Alan SDK Cordova component:

    Terminal
    npm install @alan-ai/cordova-plugin-alan-voice --save
    
  4. Install the Alan 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 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.

  5. In the main.ts file, import the Alan button component and bind it to the window object:

    main.ts
    // Importing the Alan button component
    import {
      applyPolyfills,
      defineCustomElements,
    } from '@alan-ai/alan-button/dist/loader';
    
    // Binding custom components to the window object
    applyPolyfills().then(() => {
      defineCustomElements();
    });
    
  6. In your Vue component, add the Alan button:

    HomePage.vue
    <ion-content :fullscreen="true">
      ...
      <alan-button  alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
    </ion-content>
    
  7. In alan-key, replace YOUR_KEY_FROM_ALAN_STUDIO_HERE with the Alan SDK key for your Alan Studio project. To get the key, in Alan Studio, at the top of the code editor, click Integrations and copy the value from the Alan SDK Key field.

    HomePage.vue
    <ion-content :fullscreen="true">
      ...
      <alan-button  alan-key="1c885a6adb85e9d57d43485dbc3cb44a2e956eca572e1d8b807a3e2338fdd0dc/stage" />
    </ion-content>
    

That’s it. You can now add voice commands to the script in Alan Studio, run the app, click the Alan 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.

Running Ionic apps on iOS and Android

To build and deploy your Ionic project as a native iOS or Android app, you can use Capacitor.

Capacitor is installed in new Ionic apps by default. To use it in existing projects, make sure you have installed and initialized Capacitor with your app name and bundle ID. For details, see Capacitor documentation.

After Capacitor is installed:

  1. Add the native platform to your app:

    Terminal
    # iOS platform
    ionic capacitor add ios
    
    # Android platform
    ionic capacitor add android
    
  2. (For iOS) In iOS, the user must explicitly grant permission for an app to access the user’s data and resources. An app with the Alan button requires access to:

    • User’s device microphone for voice interactions

    • User’s device camera for testing Alan projects on mobile

    To comply with this requirement, you must add NSMicrophoneUsageDescription and NSCameraUsageDescription keys to the Info.plist file of your app and provide a message why your app requires access to the microphone and camera. The message will be displayed only when Alan needs to activate the microphone or camera. Do the following:

    1. In the app folder, go to iOS > App folder and open the generated XCode workspace file: <appname>.xcworkspace.

    2. In Xcode, go to the Info tab.

    3. In the Custom iOS Target Properties section, hover over any key in the list and click the plus icon to the right.

    4. From the list, select Privacy - Microphone Usage Description.

    5. In the Value field to the right, provide a description for the added key. This description will be displayed to the user when the app is launched.

    6. Repeat the steps above to add the Privacy - Camera Usage Description key.

    ../../../_images/pods-mic.png
  3. Use the following commands to open your app in the IDE, run it on the device or simulator or build it for the native platform:

    Terminal
    # iOS platform
    ionic capacitor open ios
    ionic capacitor run ios
    ionic capacitor build ios
    
    # Android platform
    ionic capacitor open android
    ionic capacitor run android
    ionic capacitor build android
    

Specifying the Alan button parameters

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

Name

Type

Description

alan-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.

Using the Alan button methods

For details on methods exposed by the Alan Ionic framework, see Client API methods.

Handling events

When you run an app with Alan voice, multiple events come from the Alan backend. You can handle the following events:

  • onCommand: this callback is invoked when the app receives a command from the voice script. For details, see onCommand handler.

  • onButtonState: this callback is invoked when the Alan button state changes. For details, see onButtonState handler.

  • onEvent: this callback is invoked on Alan events. For details, see onEvent handler.

Communicating between components

To enable communication between the app components and the Alan button wrapper, we recommend that you send events from your components and set up event listeners in AlanBtn.tsx.

For example, you want to send some data to the voice script with Alan’s callProjectApi() method when a button in the app is clicked. For that, you need to:

  1. Send the call-project-api event from the button component with the dispatchEvent() method:

    Button.tsx
    import React, { useCallback, useEffect, useRef } from 'react';
    
    const Button: React.FC = (props: any) => {
      const callProjectApi = useCallback(() => {
        window.dispatchEvent(new CustomEvent("call-project-api", { detail: { data: 'some-data' } }));
      },[]);
      return <button onClick={callProjectApi}>Send data to the voice script</button>;
    };
    
    export default Button;
    
  2. In the Alan button wrapper, register an event listener to listen for the call-project-api event and call the myApi callProjectApi() method defined in the voice script:

    AlanBtn.tsx
    import React, { useEffect, useRef } from 'react';
    import { withRouter } from 'react-router';
    
    const AlanBtn: React.FC = (props: any) => {
      const alanBtnComponent = useRef<any>(null);
      ...
      useEffect(() => {
        window.addEventListener('call-project-api', (e: any) => {
          alanBtnComponent.current.callProjectApi(
            'myApi',
            e.detail.data,
            (e: any, r: any) => {
              alert('Project API was called');
            }
          );
        });
      }, []);
    
      return (
        <alan-button
          ref={alanBtnComponent}
          alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE"
        />
      );
    };
    
    export default withRouter(AlanBtn);
    

Note

For larger projects, you can dispatch actions via Redux or any event-bus JavaScript library.

Troubleshooting

To troubleshoot problems you may have with your Ionic app, check the solutions below:

  • For Mac or Linux, you may need to run commands with sudo.

  • On the iOS platform, you need to disable Bitcode for your app builds. For details, see Disable Bitcode for Capacitor iOS.

  • You can encounter the following problem while running Capacitor: unknown option ‘–npm-client’. Uninstall Ionic and install its latest version:

    Terminal
    npm uninstall -g ionic
    npm install -g @ionic/cli@latest
    

Trying Alan sample apps

In our GitHub repository, you can find sample Ionic apps already integrated with Alan. Download these apps to get an idea of how you can voice enable your app and trigger activities in the app with voice commands.