Client API methods¶
Alan exposes a set of client API methods that you can use to enable communication between the client app and Alan and trigger voice activities on the client side.
The client API methods are supported on all platforms:
setVisualState()¶
Sets the visual state for the client app. Use this method to inform the voice assistant about the app’s visual context, for example, the currently active screen, state of the cart and so on.
On the voice script side, the data passed with this method can be accessed through the visual object. For details, see Visual state.
Syntax
Function syntax
setVisualState(visualStateData:object)
Parameters
Name |
Type |
Description |
|---|---|---|
|
object |
JSON object that represents the visual state |
Examples
alanBtnInstance.setVisualState({data:"your data"});
See also
How-to: Send information about the app visual context to the voice script
- (void)setVisualState {
/// Providing any params
[self.button setVisualState:@{@"data":@"your data"}];
}
See also
How-to: Send information about the app visual context to the voice script
func setVisualState() {
/// Providing any params
self.button.setVisualState(["data":"your data"])
}
See also
fun setVisualState() {
/// Providing any params
val params = JSONObject()
try {
params.put("data", "your data")
} catch (e: JSONException) {
Log.e("AlanButton", e.message)
}
alanButton?.setVisualState(params.toString())
}
See also
How-to: Send information about the app visual context to the voice script
void setVisualState() {
/// Providing any params
JSONObject params = new JSONObject();
try {
params.put("data","your data");
} catch (JSONException e) {
Log.e("AlanButton", e.getMessage());
}
alanButton.setVisualState(params.toString());
}
See also
How-to: Send information about the app visual context to the voice script
_MyHomePageState() {
void _setVisualState() {
/// Providing any params with json
var visualState = jsonEncode({"data":"your data"});
AlanVoice.setVisualState(visualState);
}
}
See also
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.setVisualState({data: 'your data'});
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.setVisualState({data: 'your data'});
Ionic Vue
<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>
See also
setVisualState() {
/// Providing any params with json
AlanManager.setVisualState({"data":"your data"});
}
See also
callProjectApi()¶
Calls a project API method defined in the voice script in the Alan Studio project. Use the project API functionality to:
Pass arbitrary data from the app to the voice script
Trigger activities without a voice command
For details, see Project API.
Syntax
Function syntax
callProjectApi(method:string, data:object, callback:function)
Parameters
Name |
Type |
Description |
|---|---|---|
|
string |
Project API method name that is defined in the voice script |
|
object |
Any object with arbitrary data that must be sent to the voice script |
|
function |
Callback to be called from the project API method |
projectAPI.setClientData = function(p, param, callback) {
p.userData.data = param.data;
callback();
};
Examples
alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
// Handling error and result
});
See also
- (void)callProjectApi {
/// Providing any params
[self.button callProjectApi:@"script::funcName" withData:@{@"data":@"your data"} callback:nil];
}
See also
func callProjectApi() {
/// Providing any params
self.button.callProjectApi("script::funcName", withData: ["data":"your data"], callback: nil)
}
See also
fun callProjectApi() {
/// Providind any params
val params = JSONObject()
try {
params.put("data", "your data")
} catch (e: JSONException) {
Log.e("AlanButton", e.message)
}
alanButton?.callProjectApi("script::funcName", params.toString())
}
See also
void callProjectApi() {
/// Providing any params
JSONObject params = new JSONObject();
try {
params.put("data","your data");
} catch (JSONException e) {
Log.e("AlanButton", e.getMessage());
}
alanButton.callProjectApi("script::funcName", params.toString());
}
See also
_MyHomePageState() {
void _callProjectApi() {
/// Providing any params with json
var params = jsonEncode({"data":"your data"});
AlanVoice.callProjectApi("script::funcName", params);
}
}
See also
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.callProjectApi("myFunc", {myData: 123}, function (error, result) {
console.log("cb from myFunc was received", error, result);
});
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.callProjectApi("myFunc", {myData: 123}, function (error, result) {
console.log("cb from myFunc was received", error, result);
});
Ionic Vue
<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>
See also
callProjectApi() {
/// Providing any params with json
AlanManager.callProjectApi(
'script::funcName', {"data":"your data"},
(error, result) => {
if (error) {
console.error(error);
} else {
console.log(result);
}
},
)
}
See also
playText()¶
Plays a text string passed to the method.
For the voice assistant to play the text message, make sure the Alan button is activated. To check the button state and activate the button programmatically, use the onButtonState handler, isActive() and activate() client API methods.
Syntax
Function syntax
playText(text:string)
Parameters
Name |
Type |
Description |
|---|---|---|
|
string |
Text string to be played |
Examples
alanBtnInstance.playText("Hi! I am Alan");
See also
How-to: Activate the Alan button programmatically and play a greeting
/// Playing any text message
- (void)playText {
/// Providing text as string param
[self.button playText:@"Hi"];
}
/// Playing any text message
func playText() {
/// Providing text as string param
self.button.playText("Hi")
}
See also
Tutorial: Playing a greeting in an iOS Swift app
/// Playing any text message
fun playText() {
/// Providing text as string param
alanButton?.playText("Hi")
}
/// Playing any text message
void playText() {
/// Providing text as string param
alanButton.playText("Hi");
}
_MyHomePageState() {
/// Playing any text message
void _playText() {
/// Providing text as string param
AlanVoice.playText("Hi");
}
}
See also
How-to: Activate the Alan button programmatically and play a greeting
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.playText("Hi! I am Alan");
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.playText("Hi! I am Alan");
Ionic Vue
<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>
See also
/// Playing any text message
playText() {
/// Providing text as string param
AlanManager.playText("Hi");
}
playCommand()¶
Executes a command locally in the client app. The command is handled by the onCommand handler.
For the voice assistant to play messages provided in the command, make sure the Alan button is activated. To check the button state and activate the button programmatically, use the onButtonState handler, isActive() and activate() client API methods.
Syntax
Function syntax
playCommand(command:object)
Parameters
Name |
Type |
Description |
|---|---|---|
|
object |
JSON object that represents a command |
Examples
alanBtnInstance.playCommand({command:"navigate", screen: "settings"});
/// Executing a command locally
- (void)playCommand {
/// Providing any params
[self.button playCommand:@{@"action":@"openSomePage"}];
}
/// Executing a command locally
func playCommand() {
/// Providing any params
self.button.playCommand(["action":"openSomePage"])
}
/// Executing a command locally
fun playCommand() {
/// Providing any params
val params = JSONObject()
try {
params.put("action", "openSomePage")
} catch (e: JSONException) {
e.message?.let { Log.e("AlanButton", it) }
}
alanButton?.playCommand(params.toString(), null)
}
/// Executing a command locally
void playCommand() {
/// Providing any params
JSONObject params = new JSONObject();
try {
params.put("action","openSomePage");
} catch (JSONException e) {
Log.e("AlanButton", e.getMessage());
}
alanButton.playCommand(params.toString(), null);
}
_MyHomePageState() {
/// Executing a command locally
void _playCommand() {
/// Providing any params with json
var command = jsonEncode({"action":"openSomePage"});
AlanVoice.playCommand(command);
}
}
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.playCommand({command:"navigate", screen: "settings"});
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.playCommand({command:"navigate", screen: "settings"});
Ionic Vue
<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>
See also
/// Executing a command locally
playCommand() {
/// Providing any params with json
AlanManager.playCommand({"action":"openSomePage"})
}
activate()¶
Activates the Alan button programmatically.
Syntax
Function syntax
activate()
Example
alanBtnInstance.activate();
See also
How-to: Activate the Alan button programmatically and play a greeting
/// Activating the Alan button programmatically
- (void)activate {
[self.button activate];
}
/// Activating the Alan button programmatically
func activate() {
self.button.activate()
}
See also
Tutorial: Playing a greeting in an iOS Swift app
/// Activating the Alan button programmatically
fun activate() {
alanButton?.activate()
}
/// Activating the Alan button programmatically
void activate() {
alanButton.activate();
}
_MyHomePageState() {
/// Activating the Alan button programmatically
void _activate() {
AlanVoice.activate();
}
}
See also
How-to: Activate the Alan button programmatically and play a greeting
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.activate();
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.activate();
Ionic Vue
<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>
See also
/// Activating the Alan button programmatically
activate() {
AlanManager.activate();
}
deactivate()¶
Deactivates the Alan button programmatically.
Syntax
Function syntax
deactivate()
Example
alanBtnInstance.deactivate();
/// Deactivating the Alan button programmatically
- (void)deactivate {
[self.button deactivate];
}
/// Deactivating the Alan button programmatically
func deactivate() {
self.button.deactivate()
}
/// Deactivating the Alan button programmatically
fun deactivate() {
alanButton?.deactivate()
}
/// Deactivating the Alan button programmatically
void deactivate() {
alanButton.deactivate();
}
_MyHomePageState() {
/// Deactivating the Alan button programmatically
void _deactivate() {
AlanVoice.deactivate();
}
}
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.deactivate();
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.deactivate();
Ionic Vue
<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>
See also
/// Deactivating the Alan button programmatically
deactivate() {
AlanManager.deactivate();
}
isActive()¶
Checks the Alan button state. Returns true if the Alan button is activated by the user or programmatically or false if the Alan button is deactivated by the user or programmatically.
Syntax
Function syntax
isActive()
Example
alanBtnInstance.isActive();
See also
How-to: Activate the Alan button programmatically and play a greeting
[alanBtnInstance isActive];
alanBtnInstance.isActive();
alanBtnInstance.isActive();
void _checkIsActive() async {
var isActive = await AlanVoice.isActive();
if (isActive) {
_showDialog("Active");
} else {
_showDialog("NOT active");
}
}
See also
How-to: Activate the Alan button programmatically and play a greeting
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.isActive();
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.isActive();
Ionic Vue
<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>
See also
AlanManager.isActive((error, result) => {
if (error) {
console.error(error);
} else {
console.log(result);
}
})
remove()¶
Removes the Alan button.
Use this method to completely remove the Alan button from the parent element (page).
Note
At present, this method is supported only on the Web platform.
Syntax
Function syntax
remove()
Example
alanBtnInstance.remove();
Ionic Angular
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
myAlanBtn.removeButton();
});
Ionic React
const alanBtnComponent = useRef<any>(null);
alanBtnComponent.current.removeButton();
Ionic Vue
<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>
See also