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 Ionic apps on iOS and Android

You can use Cordova to build and deploy your Ionic app as a native iOS or Android app. Do the following:

  1. Install the Cordova CLI
  2. Build and run the app

Step 1. Install the Cordova CLI

To install the Cordova CLI, run the following command:

$ npm install -g ionic cordova

For Mac or Linux, you may need to run the command with sudo.

Step 2. Build and run the app

To run an Ionic app on an iOS or Android device or simulator, use the commands below. For more details, see the Ionic CLI documentation.

  1. To add a platform for which you want to build the app, run the following commands:

    ionic cordova platform add ios
    ionic cordova platform add android
  2. To build the app for iOS or Android, run the following commands:

    ionic cordova platform build ios
    ionic cordova platform build android
  3. (For iOS) To set the NSMicrophoneUsageDescription and NSCameraUsageDescription in iOS, run the following commands. These commands will add declarations to the Info.plist file.

    ionic cordova plugin add cordova-plugin-ios-microphone-permissions
    ionic cordova plugin add cordova-plugin-ios-camera-permissions
  4. To launch the app on a device or simulator, run the following commands:

    ionic cordova platform run ios
    ionic cordova platform run android

    You may need to install the native-run globally. To do this, run npm i -g native-run.

The Alan button won't work if you run the app using 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.