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

visualStateData

object

JSON object that represents the visual state

Examples

Client app
alanBtnInstance.setVisualState({data:"your data"});

See also

How-to: Send information about the app visual context to the voice script

Client app
- (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

Client app
func setVisualState() {
  /// Providing any params
  self.button.setVisualState(["data":"your data"])
}

See also

Client app
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

Client app
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

Client app
_MyHomePageState() {
  void _setVisualState() {
    /// Providing any params with json
    var visualState = jsonEncode({"data":"your data"});
    AlanVoice.setVisualState(visualState);
  }
}

See also

Ionic Angular

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.setVisualState({data: 'your data'});
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

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

Ionic Vue

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>

See also

Client app
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

method

string

Project API method name that is defined in the voice script

data

object

Any object with arbitrary data that must be sent to the voice script

callback

function

Callback to be called from the project API method

Voice script
projectAPI.setClientData = function(p, param, callback) {
  p.userData.data = param.data;
  callback();
};

Examples

Client app
alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
  // Handling error and result
});

See also

Client app
- (void)callProjectApi {
  /// Providing any params
  [self.button callProjectApi:@"script::funcName" withData:@{@"data":@"your data"} callback:nil];
}

See also

Client app
func callProjectApi() {
  /// Providing any params
  self.button.callProjectApi("script::funcName", withData: ["data":"your data"], callback: nil)
}

See also

Client app
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

Client app
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

Client app
_MyHomePageState() {
  void _callProjectApi() {
    /// Providing any params with json
    var params = jsonEncode({"data":"your data"});
    AlanVoice.callProjectApi("script::funcName", params);
  }
}

See also

Ionic Angular

Client app
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

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

Ionic Vue

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>

See also

Client app
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

text

string

Text string to be played

Examples

Client app
alanBtnInstance.playText("Hi! I am Alan");

See also

How-to: Activate the Alan button programmatically and play a greeting

Client app
/// Playing any text message
- (void)playText {
  /// Providing text as string param
  [self.button playText:@"Hi"];
}
Client app
/// 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

Client app
/// Playing any text message
fun playText() {
  /// Providing text as string param
  alanButton?.playText("Hi")
}
Client app
/// Playing any text message
void playText() {
  /// Providing text as string param
  alanButton.playText("Hi");
}
Client app
_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

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.playText("Hi! I am Alan");
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

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

Ionic Vue

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>

See also

Client app
/// 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

command

object

JSON object that represents a command

Examples

Client app
alanBtnInstance.playCommand({command:"navigate", screen: "settings"});
Client app
/// Executing a command locally
- (void)playCommand {
  /// Providing any params
  [self.button playCommand:@{@"action":@"openSomePage"}];
}
Client app
/// Executing a command locally
func playCommand() {
  /// Providing any params
  self.button.playCommand(["action":"openSomePage"])
}
Client app
/// 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)
}
Client app
/// 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);
}
Client app
_MyHomePageState() {
  /// Executing a command locally
  void _playCommand() {
    /// Providing any params with json
    var command = jsonEncode({"action":"openSomePage"});
    AlanVoice.playCommand(command);
  }
}

Ionic Angular

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.playCommand({command:"navigate", screen: "settings"});
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

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

Ionic Vue

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>

See also

Communicating between components

Client app
/// 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

Client app
alanBtnInstance.activate();

See also

How-to: Activate the Alan button programmatically and play a greeting

Client app
/// Activating the Alan button programmatically
- (void)activate {
  [self.button activate];
}
Client app
/// Activating the Alan button programmatically
func activate() {
  self.button.activate()
}

See also

Tutorial: Playing a greeting in an iOS Swift app

Client app
/// Activating the Alan button programmatically
fun activate() {
  alanButton?.activate()
}
Client app
/// Activating the Alan button programmatically
void activate() {
  alanButton.activate();
}
Client app
_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

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.activate();
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.activate();

Ionic Vue

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>

See also

Client app
/// Activating the Alan button programmatically
activate() {
  AlanManager.activate();
}

deactivate()

Deactivates the Alan button programmatically.

Syntax

Function syntax

deactivate()

Example

Client app
alanBtnInstance.deactivate();
Client app
/// Deactivating the Alan button programmatically
- (void)deactivate {
  [self.button deactivate];
}
Client app
/// Deactivating the Alan button programmatically
func deactivate() {
  self.button.deactivate()
}
Client app
/// Deactivating the Alan button programmatically
fun deactivate() {
  alanButton?.deactivate()
}
Client app
/// Deactivating the Alan button programmatically
void deactivate() {
  alanButton.deactivate();
}
Client app
_MyHomePageState() {
  /// Deactivating the Alan button programmatically
  void _deactivate() {
    AlanVoice.deactivate();
  }
}

Ionic Angular

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.deactivate();
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.deactivate();

Ionic Vue

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>

See also

Communicating between components

Client app
/// 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

Client app
alanBtnInstance.isActive();

See also

How-to: Activate the Alan button programmatically and play a greeting

Client app
[alanBtnInstance isActive];
Client app
alanBtnInstance.isActive()

See also

Tutorial: Playing a greeting in an iOS Swift app

Client app
alanBtnInstance.isActive();
Client app
alanBtnInstance.isActive();
Client app
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

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.isActive();
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.isActive();

Ionic Vue

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>

See also

Client app
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

Client app
alanBtnInstance.remove();

Ionic Angular

Client app
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.removeButton();
});

Ionic React

Client app
const alanBtnComponent = useRef<any>(null);

alanBtnComponent.current.removeButton();

Ionic Vue

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>

See also

Communicating between components