Documentation

Powered by Algolia

Alan Ionic Framework


Available on Web, iOS, Android platforms.


Integration

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

Integrate with an Ionic Angular app

To integrate an Ionic Angular app with Alan:

  1. Navigate to the folder where your app resides:

    $ cd /myApp
  2. Install the Alan SDK Cordova component:

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

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

    For Ionic apps, you need to install the @alan-ai/alan-button and @alan-ai/cordova-plugin-alan-voice packages, not the @alan-ai/alan-sdk-web package. Ionic apps can be run on mobile devices with Cordova; they require special versions of the Alan button.

  4. Modify the app to enable the Alan button:

    a. 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 file
    ...
    import {CUSTOM_ELEMENTS_SCHEMA} from '@angular/core';
    ...
    
    @NgModule({
    ...
      schemas: [CUSTOM_ELEMENTS_SCHEMA],
    ...
    })
    export class AppModule {}

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

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

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

    d. 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 the 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>
  5. In the src/app folder, in app.component.ts, make the following changes:

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

    import "@alan-ai/alan-button";

    b. In the AppComponent class, use @ViewChild to add a reference to the Alan button element:

    @ViewChild('alanBtnEl', {static:false}) alanBtnComponent: ElementRef<HTMLAlanButtonElement>;

    c. Replace the first import statement with the following one:

    import { Component, ElementRef, ViewChild } from '@angular/core';

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

    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 the Alan Studio, run the app, click the Alan button and interact with the app with voice.

Integrate with an Ionic React app

To integrate an Ionic React app with Alan:

  1. Navigate to the folder where your app resides:

    $ cd /myApp
  2. Install the Alan SDK Cordova component:

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

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

    For Ionic apps, you need to install the @alan-ai/alan-button and @alan-ai/cordova-plugin-alan-voice packages, not the @alan-ai/alan-sdk-web package. Ionic apps can be run on mobile devices with Cordova; they require special versions of the Alan button.

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

    //AlanBtn.tsx file
    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.

  5. 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 the Alan Studio, at the top of the code editor, click Integrations and copy the value from the Alan SDK Key field.

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

    import AlanBtn from './components/AlanBtn';
  7. In the App.tsx file, add the Alan button component:

    //App.tsx file
    ...
    const App: React.FC = () => (
    	<IonApp>
    		<IonReactRouter>
    			...
    			<AlanBtn />
    		</IonReactRouter>
    	</IonApp>
    );
    ...
  8. In the src folder, create a typescript declaration file named alan-btn.d.ts:

    //alan-btn.d.ts file
    declare namespace JSX {
    	interface IntrinsicElements {
    		[tagName:string]: any
    	}
    }
  9. In the index.tsx file, import the Alan button component loader and call the loader:

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

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

Run demo commands

To run an Ionic app on a device or simulator, use the following commands:

  1. Run ionic cordova platform add ios or ionic cordova platform add android
  2. Run ionic cordova plugin add @alan-ai/cordova-plugin-alan-voice
  3. Run ionic cordova plugin add cordova-plugin-ios-microphone-permissions
  4. Run ionic cordova build ios or ionic cordova build android
  5. Run ionic cordova run ios or ionic cordova run android

Please note that the Alan Button won't work if you run your application via Ionic DevApp. The Ionic DevApp works with the limited list of Cordova plugins, and while there is no @alan-ai/cordova-plugin-alan-voice in this list, the button won't appear.