Client API methods

Alan exposes a set of its Client API methods that you can use to enable communication between the client app and Alan and to trigger voice activities on the client side.

The methods below are supported on all platforms:

setVisualState()

Method for setting the visual state to inform the voice assistant about the app’s visual context. For details, see Visual state.

Syntax

Function syntax

setVisualState(visualStateData:object)

Parameters

Name

Type

Description

visualStateData

object

Object that represents the visual state

Examples

//this is how you can set up a visual state
alanBtnInstance.setVisualState({data:"your data"});
/// Set up a visual state
- (void)setVisualState {
  /// Provide any params
  [self.button setVisualState:@{@"data":@"your data"}];
}
/// Set up a visual state
func setVisualState() {
  /// Provide any params
  self.button.setVisualState(["data":"your data"])
}
/// Set up a visual state
fun setVisualState() {
  /// Provide any params
  val params = JSONObject()
  try {
        params.put("data", "your data")
  } catch (e: JSONException) {
        Log.e("AlanButton", e.message)
  }
  alanButton?.setVisualState(params.toString())
}
/// Set up a visual state
void setVisualState() {
  /// Provide any params
  JSONObject params = new JSONObject();
  try {
        params.put("data","your data");
  } catch (JSONException e) {
        Log.e("AlanButton", e.getMessage());
  }
  alanButton.setVisualState(params.toString());
}
_MyHomePageState() {
  /// Set up a visual state
  void _setVisualState() {
    /// Provide any params with json
    var visualState = jsonEncode({"data":"your data"});
    AlanVoice.setVisualState(visualState);
  }
}
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.setVisualState({screen: 'homePage'});
});
/// Set up a visual state
setVisualState() {
  /// Provide any params with json
  AlanManager.setVisualState({"data":"your data"});
}

callProjectApi()

Method for calling a project API defined in the script in the Alan Studio project. 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 custom data that must be sent to the voice script

callback

function

Callback that can be called from the project API method

// Voice script where your method defined like this:
projectAPI.setClientData = function(p, param, callback) {
  p.userData = param;
  callback();
};

Examples

// This is how you can call clientAPI.setClientData function
alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
  // handle error and result here
});
/// Call projectAPI.funcName from Alan Studio script
- (void)callProjectApi {
  /// Provide any params
  [self.button callProjectApi:@"script::funcName" withData:@{@"data":@"your data"} callback:nil];
}
/// Call projectAPI.funcName from Alan Studio script
func callProjectApi() {
  /// Provide any params
  self.button.callProjectApi("script::funcName", withData: ["data":"your data"], callback: nil)
}
/// Call projectAPI.funcName from Alan Studio script
fun callProjectApi() {
  /// Provide 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())
}
/// Call projectAPI.funcName from Alan Studio script
void callProjectApi() {
  /// Provide 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());
}
_MyHomePageState() {
  /// Call projectAPI.funcName from Alan Studio script
  void _callProjectApi() {
    /// Provide any params with json
    var params = jsonEncode({"data":"your data"});
    AlanVoice.callProjectApi("script::funcName", params);
  }
}
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);
  });
});
/// Call projectAPI.funcName from Alan Studio script
callProjectApi() {
  /// Provide any params with json
  AlanManager.callProjectApi(
    'script::funcName', {"data":"your data"},
    (error, result) => {
      if (error) {
        console.error(error);
      } else {
        console.log(result);
      }
    },
  )
}

playText()

Method for playing voice.

Syntax

Function syntax

playText(text:string)

Parameters

Name

Type

Description

text

string

Text that must be played

Examples

alanBtnInstance.playText("Hi! I am Alan");
/// Play any text via Alan Button
- (void)playText {
  /// Provide text as string param
  [self.button playText:@"Hi"];
}
/// Play any text via Alan Button
func playText() {
  /// Provide text as string param
  self.button.playText("Hi")
}
/// Play any text via Alan Button
fun playText() {
  /// Provide text as string param
  alanButton?.playText("Hi")
}
/// Play any text via Alan Button
void playText() {
  /// Provide text as string param
  alanButton.playText("Hi");
}
_MyHomePageState() {
/// Play any text via Alan Button
  void _playText() {
    /// Provide text as string param
    AlanVoice.playText("Hi");
  }
}
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.playText("Hi! I am Alan");
});
/// Play any text via Alan Button
playText() {
  /// Provide text as string param
  AlanManager.playText("Hi");
}

playCommand()

Method for executing a command locally in the client app. The command is handled with the onCommand handler.

Syntax

Function syntax

playCommand(command:object)

Parameters

Name

Type

Description

command

object

JSON object that represents a command

Examples

alanBtnInstance.playCommand({command:"navigate", screen: "settings"});
/// Execute any command locally
- (void)playCommand {
  /// Provide any params
  [self.button playCommand:@{@"action":@"openSomePage"}];
}
/// Execute any command locally
func playCommand() {
  /// Provide any params
  self.button.playCommand(["action":"openSomePage"])
}
/// Execute any command locally
fun playCommand() {
  /// Provide any params
  val params = JSONObject()
  try {
        params.put("action", "openSomePage")
  } catch (e: JSONException) {
        Log.e("AlanButton", e.message)
  }
  alanButton?.playCommand(params.toString(), null)
}
/// Execute any command locally
void playCommand() {
  /// Provide 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() {
  /// Execute any command locally
  void _playCommand() {
    /// Provide any params with json
    var command = jsonEncode({"action":"openSomePage"});
    AlanVoice.playCommand(command);
  }
}
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.playCommand({command:"navigate", screen: "settings"});
});
/// Execute any command locally
playCommand() {
  /// Provide any params with json
  AlanManager.playCommand({"action":"openSomePage"})
}

activate()

Method for turning on the Alan button programmatically.

Syntax

Function syntax

activate()

Example

alanBtnInstance.activate();
/// Activate Alan button programmatically
- (void)activate {
  [self.button activate];
}
/// Activate Alan button programmatically
func activate() {
  self.button.activate()
}
/// Activate Alan button programmatically
fun activate() {
  alanButton?.activate()
}
/// Activate Alan button programmatically
void activate() {
  alanButton.activate();
}
_MyHomePageState() {
  /// Activate Alan button programmatically
  void _activate() {
    AlanVoice.activate();
  }
}
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.activate();
});
/// Activate Alan button programmatically
activate() {
  AlanManager.activate();
}

deactivate()

Method for turning off the Alan button programmatically.

Syntax

Function syntax

deactivate()

Example

alanBtnInstance.deactivate();
/// Deactivate Alan button programmatically
- (void)deactivate {
  [self.button deactivate];
}
/// Deactivate Alan button programmatically
func deactivate() {
  self.button.deactivate()
}
/// Deactivate Alan button programmatically
fun deactivate() {
  alanButton?.deactivate()
}
/// Deactivate Alan button programmatically
void deactivate() {
  alanButton.deactivate();
}
_MyHomePageState() {
  /// Deactivate Alan button programmatically
  void _deactivate() {
    AlanVoice.deactivate();
  }
}
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.deactivate();
});
/// Deactivate Alan button programmatically
deactivate() {
  AlanManager.deactivate();
}

isActive()

Method for checking 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();
[alanBtnInstance isActive];
alanBtnInstance.isActive()
alanBtnInstance.isActive();
void _checkIsActive() async {
  var isActive = await AlanVoice.isActive();
  if (isActive) {
    _showDialog("Active");
  } else {
    _showDialog("NOT active");
  }
}
var myAlanBtn = document.getElementById('myAlanBtn');

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.isActive();
});
AlanManager.isActive((error, result) => {
  if (error) {
    console.error(error);
  } else {
    console.log(result);
  }
})

remove()

Method for removing the Alan button. This method can be used, for example, if you need to remove the Alan button from specific pages in the app.

Syntax

Function syntax

remove()

Note

At present, this method is supported only for the Web platform.

Example

alanBtnInstance.remove();
var myAlanBtn = document.getElementById('myAlanBtn');

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