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()

• callProjectApi()

• playText()

• playCommand()

• activate()

• deactivate()

• isActive()

• (Web platform) remove()

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

Web (React, Angular, etc.)

//this is how you can set up a visual state
alanBtnInstance.setVisualState({data:"your data"});

Objective-C

/// Set up a visual state
- (void)setVisualState {
  /// Provide any params
  [self.button setVisualState:@{@"data":@"your data"}];
}

Swift

/// Set up a visual state
func setVisualState() {
  /// Provide any params
  self.button.setVisualState(["data":"your data"])
}

Kotlin

/// 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())
}

Java

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

Flutter

_MyHomePageState() {
  /// Set up a visual state
  void _setVisualState() {
    /// Provide any params with json
    var visualState = jsonEncode({"data":"your data"});
    AlanVoice.setVisualState(visualState);
  }
}

Ionic

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

myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.setVisualState({screen: 'homePage'});
});

React Native

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

Web (React, Angular, etc.)

// This is how you can call clientAPI.setClientData function
alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
  // handle error and result here
});

Objective-C

/// Call projectAPI.funcName from Alan Studio script
- (void)callProjectApi {
  /// Provide any params
  [self.button callProjectApi:@"script::funcName" withData:@{@"data":@"your data"} callback:nil];
}

Swift

/// Call projectAPI.funcName from Alan Studio script
func callProjectApi() {
  /// Provide any params
  self.button.callProjectApi("script::funcName", withData: ["data":"your data"], callback: nil)
}

Kotlin

/// 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())
}

Java

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

Flutter

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

Ionic

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

React Native

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

Web (React, Angular, etc.)

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

Objective-C

/// Play any text via Alan Button
- (void)playText {
  /// Provide text as string param
  [self.button playText:@"Hi"];
}

Swift

/// Play any text via Alan Button
func playText() {
  /// Provide text as string param
  self.button.playText("Hi")
}

Kotlin

/// Play any text via Alan Button
fun playText() {
  /// Provide text as string param
  alanButton?.playText("Hi")
}

Java

/// Play any text via Alan Button
void playText() {
  /// Provide text as string param
  alanButton.playText("Hi");
}

Flutter

_MyHomePageState() {
/// Play any text via Alan Button
  void _playText() {
    /// Provide text as string param
    AlanVoice.playText("Hi");
  }
}

Ionic

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

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

React Native

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

Web (React, Angular, etc.)

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

Objective-C

/// Execute any command locally
- (void)playCommand {
  /// Provide any params
  [self.button playCommand:@{@"action":@"openSomePage"}];
}

Swift

/// Execute any command locally
func playCommand() {
  /// Provide any params
  self.button.playCommand(["action":"openSomePage"])
}

Kotlin

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

Java

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

Flutter

_MyHomePageState() {
  /// Execute any command locally
  void _playCommand() {
    /// Provide any params with json
    var command = jsonEncode({"action":"openSomePage"});
    AlanVoice.playCommand(command);
  }
}

Ionic

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

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

React Native

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

Web (React, Angular, etc.)

alanBtnInstance.activate();

Objective-C

/// Activate Alan button programmatically
- (void)activate {
  [self.button activate];
}

Swift

/// Activate Alan button programmatically
func activate() {
  self.button.activate()
}

Kotlin

/// Activate Alan button programmatically
fun activate() {
  alanButton?.activate()
}

Java

/// Activate Alan button programmatically
void activate() {
  alanButton.activate();
}

Flutter

_MyHomePageState() {
  /// Activate Alan button programmatically
  void _activate() {
    AlanVoice.activate();
  }
}

Ionic

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

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

React Native

/// Activate Alan button programmatically
activate() {
  AlanManager.activate();
}

deactivate()

Method for turning off the Alan button programmatically.

Syntax

Function syntax

deactivate()

Example

Web (React, Angular, etc.)

alanBtnInstance.deactivate();

Objective-C

/// Deactivate Alan button programmatically
- (void)deactivate {
  [self.button deactivate];
}

Swift

/// Deactivate Alan button programmatically
func deactivate() {
  self.button.deactivate()
}

Kotlin

/// Deactivate Alan button programmatically
fun deactivate() {
  alanButton?.deactivate()
}

Java

/// Deactivate Alan button programmatically
void deactivate() {
  alanButton.deactivate();
}

Flutter

_MyHomePageState() {
  /// Deactivate Alan button programmatically
  void _deactivate() {
    AlanVoice.deactivate();
  }
}

Ionic

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

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

React Native

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

Web (React, Angular, etc.)

alanBtnInstance.isActive();

Objective-C

[alanBtnInstance isActive];

Swift

alanBtnInstance.isActive()

Android

alanBtnInstance.isActive();

Flutter

void _checkIsActive() async {
  var isActive = await AlanVoice.isActive();
  if (isActive) {
    _showDialog("Active");
  } else {
    _showDialog("NOT active");
  }
}

Ionic

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

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

React Native

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

Web (React, Angular, etc.)

alanBtnInstance.remove();

Ionic

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

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