Ionic React¶

Available on: Web platform Android iOS

Integrating with Alan¶

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

Create an Ionic React app
Install Alan packages
Add the Alan button

Step 1. Create an Ionic React 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 packages¶

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

Navigate to the folder where your app resides:
Terminal¶
```
cd appName
```

Install the Alan SDK Cordova component:

Terminal¶

npm install @alan-ai/cordova-plugin-alan-voice --save

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.

Step 3. Add the Alan button¶

You need to create a wrapper component for the Alan button and update your app to embed the button to it.

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.

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);
```
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

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

App.tsx¶

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

see full source

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
  }
}

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.

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 client API methods¶

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

setVisualState()
callProjectApi()
playText()
playCommand()
activate()
deactivate()
isActive()
remove()
getWakewordEnabled()
setWakewordEnabled()

setVisualState()¶

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

Client app¶

const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.setVisualState({data: 'your data'});

callProjectApi()¶

Use the callProjectApi() method to send data from the client app to the voice script and trigger activities without voice commands. For details, see callProjectApi().

Voice script¶

projectAPI.myFunc = function(p, param, callback) {
  console.log(param);
};

Client app¶

const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.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¶

const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.playText("Hi! I am Alan");

playCommand()¶

Use the playCommand() method to execute a specific command in the client app. For details, see playCommand().

Client app¶

const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.playCommand({command:"navigate", screen: "settings"});

activate()¶

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

Client app¶

const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.activate();

deactivate()¶

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

Client app¶

const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.deactivate();

isActive()¶

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

Client app¶

const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.isActive();

remove()¶

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

Client app¶

const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.removeButton();

getWakewordEnabled()¶

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

Client app¶

const alanBtnComponent = useRef<any>(null);

const isWakewordEnabled = await alanBtnComponent.current.getWakewordEnabled();

setWakewordEnabled()¶

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

Client app¶

const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.setWakewordEnabled(true);

Using handlers¶

You can use the following Alan handlers in your app:

onCommand handler
onButtonState handler
onConnectionStatus handler
onEvent handler

onCommand handler¶

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

Client app¶

alanBtnComponent.current.addEventListener('command', (data: CustomEvent) => {
  const commandData = 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 button state changes. For details, see onButtonState handler.

Client app¶

alanBtnComponent.current.addEventListener('buttonState', (data: CustomEvent) => {
  const stateData = data.detail;
  console.info('Button state:', stateData);
});

onConnectionStatus handler¶

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

Client app¶

alanBtnComponent.current.addEventListener('connectionStatus', (data: CustomEvent) => {
  const connectionData = data.detail;
  console.info('Received status: ', connectionData);
});

onEvent handler¶

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

Client app¶

alanBtnComponent.current.addEventListener('event', (data: CustomEvent) => {
  const eventData = data.detail;
  console.info('Received event: ', eventData.text);
});

What’s next?¶

Example apps

Find and explore examples of voice-enabled apps on the Alan AI GitHub repository.

View on GitHub