Ionic Vue¶

Available on: Web platform Android iOS

Integrating with Alan AI¶

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

Create an Ionic Vue app
Install Alan AI packages
Add the Alan AI agentic interface

Step 1. Create an Ionic Vue app¶

If you want to create an app with a conversational experience 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.

Step 2. Install Alan AI packages¶

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

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

Install the Alan AI SDK Cordova component:

Terminal¶

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

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 agentic interface 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 agentic interface¶

You need to update your app to embed the Alan AI agentic interface to it.

In the main.ts file, import the Alan AI agentic interface component and bind it to the window object:

main.ts¶

// Importing the Alan AI agentic interface component
import {
  applyPolyfills,
  defineCustomElements,
} from '@alan-ai/alan-button/dist/loader';

// Binding custom components to the window object
applyPolyfills().then(() => {
  defineCustomElements();
});

In your Vue component, add the Alan AI agentic interface:

HomePage.vue¶

<ion-content :fullscreen="true">
  <alan-button  alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

In alan-key, 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.
HomePage.vue¶
```
<ion-content :fullscreen="true">
  <alan-button  alan-key="1c885a6adb85e9d57d43485dbc3cb44a2e956eca572e1d8b807a3e2338fdd0dc/stage" />
</ion-content>
```

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

You can specify the following parameters for the Alan AI agentic interface 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()
callProjectApi()
playText()
sendText()
playCommand()
activate()
deactivate()
isActive()
remove()
getWakewordEnabled()
setWakewordEnabled()

setVisualState()¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

<script lang="ts">
  import {Components} from '@alan-ai/alan-button';

  export default defineComponent({
    mounted : function() {
      const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
      alanBtnInst.setVisualState({data: 'your data'});
    }
  });
</script>

callProjectApi()¶

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

Dialog script¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

<script lang="ts">
  import {Components} from '@alan-ai/alan-button';

  export default defineComponent({
    methods: {
      callProjectApi() {
        const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
        alanBtnInst.callProjectApi("setClientData", {data: "myData"}, function (error:any, result:any) {
          console.log("cb from myFunc was received", error, result);
        });
      },
    }
  });
</script>

playText()¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

<script lang="ts">
  import {Components} from '@alan-ai/alan-button';

  export default defineComponent({
    methods: {
      playText() {
        const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
        alanBtnInst.playText("Hi there!");
      },
    }
  });
</script>

sendText()¶

Use the sendText() method to send a text message to Alan AI as the user’s input. For details, see sendText().

Client app¶

<ion-content :fullscreen="true">
  <alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

<script lang="ts">
  import {Components} from '@alan-ai/alan-button';

  export default defineComponent({
    methods: {
      sendText() {
        const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
        alanBtnInst.sendText("Hello, Alan, can you help me?");
      },
    }
  });
</script>

playCommand()¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

<script lang="ts">
  import {Components} from '@alan-ai/alan-button';

  export default defineComponent({
    methods: {
      navigate() {
        const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
        alanBtnInst.playCommand({command:"navigate", screen: "settings"});
      },
    }
  });
</script>

activate()¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

<script lang="ts">
  import {Components} from '@alan-ai/alan-button';

  export default defineComponent({
    mounted : function() {
      const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
      alanBtnInst.activate();
    }
  });
</script>

deactivate()¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

<script lang="ts">
  import {Components} from '@alan-ai/alan-button';

  export default defineComponent({
    methods: {
      deactivate() {
        const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
        alanBtnInst.deactivate();
      },
    }
  });
</script>

isActive()¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

<script lang="ts">
  import {Components} from '@alan-ai/alan-button';

  export default defineComponent({
    const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
    alanBtnInst.isActive();
  });
</script>

remove()¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

<script lang="ts">
  import {Components} from '@alan-ai/alan-button';

  export default defineComponent({
    const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
    alanBtnInst.removeButton();
  });
</script>

getWakewordEnabled()¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

<script lang="ts">
  import {Components} from '@alan-ai/alan-button';

  export default defineComponent({
    const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
    const isWakewordEnabled = await alanBtnInst.getWakewordEnabled();
  });
</script>

setWakewordEnabled()¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button ref="alanBtn" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

<script lang="ts">
  import {Components} from '@alan-ai/alan-button';

  export default defineComponent({
    const alanBtnInst = this.$refs["alanBtn"] as Components.AlanButton;
    alanBtnInst.setWakewordEnabled(true);
  });
</script>

Using handlers¶

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

onCommand handler
onButtonState handler
onConnectionStatus handler
onEvent handler

onCommand handler¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button v-on:command="command" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

export default defineComponent({
  methods: {
    command: function(data:any) {
      console.info('Received command: ', data.detail);
    }
  },
});

Note

To define the onCommand handler in Ionic Vue, use lowercase: v-on:command. Otherwise the handler will not be working.

onButtonState handler¶

Use the onButtonState handler to capture and handle the Alan AI agentic interface state changes. For details, see onButtonState handler.

Client app¶

<ion-content :fullscreen="true">
  <alan-button v-on:buttonstate="onButtonState" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
 </ion-content>

 export default defineComponent({
   methods: {
     onButtonState: function(data:any) {
       console.info('Button state is: ', data.detail);
     }
   },
 });

Note

To define the onButtonState handler in Ionic Vue, use lowercase: v-on:buttonstate. Otherwise the handler will not be working.

onConnectionStatus handler¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button v-on:connectionstatus="connectionstatus" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

export default defineComponent({
  methods: {
    connectionstatus: function(data:any) {
      console.info('Received status: ', data.detail);
    }
  },
});

onEvent handler¶

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

Client app¶

<ion-content :fullscreen="true">
  <alan-button v-on:event="event" alan-key="YOUR_KEY_FROM_ALAN_STUDIO_HERE" />
</ion-content>

export default defineComponent({
  methods: {
    event: function(data:any) {
      console.info('Received event: ', data.detail);
    }
  },
});

Note

To define the onEvent handler in Ionic Vue, use lowercase: v-on:event. Otherwise the handler will not be working.

What’s next?¶

Example apps

Find and explore examples of Agentic Interfaces in Alan AI GitHub.