Project API

You can use the project API if you need to send information from the client app to the dialog script or want to perform some logic without a command from the user. For example, you may want Alan AI to play a message, call a function or set variable values when the user performs certain activities in the app UI.

To use the project API, you need to define a project API method with an arbitrary name in the dialog script. In the example below, the setClientData method is defined:

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

The defined project API method must then be called in the client app with callProjectApi(). callProjectApi() takes the following arguments:

  • Name of the project API method defined in the dialog script

  • Data to be sent to the dialog script

  • Callback that needs to be invoked from the project API method

Client app
alanBtnInstance.callProjectApi("setClientData", {value:"your data"}, function (error, result){
  // Handling error and result
});
Client app
- (void)callProjectApi {
  /// Providing any params
  [self.button callProjectApi:@"script::funcName" withData:@{@"data":@"your data"} callback:nil];
}
Client app
func callProjectApi() {
  /// Providing any params
  self.button.callProjectApi("script::funcName", withData: ["data":"your data"], callback: nil)
}
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())
}
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());
}
Client app
_MyHomePageState() {
  void _callProjectApi() {
    /// Providing any params with json
    var params = jsonEncode({"data":"your data"});
    AlanVoice.callProjectApi("script::funcName", params);
  }
}
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);
  });
});
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);
      }
    },
  )
}

Let’s assume we want to pass the user’s name to the dialog script and greet the user when the user logs in to the system. To do this, we will define the greetUser() project API method in the dialog script:

Dialog script
projectAPI.greetUser = function(p, param, callback) {
    if (param) {
        p.play(`Nice to see you again, ${param.user}`);
    } else {
        p.play('Welcome to our app');
    }
    callback();
};

In the app, we will call the greetUser() method when the Log in button is clicked and send the user’s name with it. Now, when the user logs in to the system, the Alan AI button will be activated automatically; Alan AI will send the user’s name to the dialog script and play: Nice to see you again, John Smith or Welcome to our app, if no name is provided.

Client app
function sendData() {
  alanBtnInstance.activate();
  // Calling the project API method on button click
  alanBtnInstance.callProjectApi("greetUser", {
    user: 'John Smith'
  }, function(error, result) {});
};
Client app
- (void)callProjectApi {
  [self.button activate];
  // Calling the project API method on button click
  [self.button callProjectApi:@"script::greetUser" withData:@{@"user":@"John Smith"} callback:nil];
}
Client app
func callProjectApi() {
  self.button.activate()
  // Calling the project API method on button click
  self.button.callProjectApi("script::greetUser", withData: ["user":"John Smith"], callback: nil)
}
Client app
fun callProjectApi() {
  alanButton?.activate()
  val params = JSONObject()
  try {
    params.put("user", "John Smith")
  } catch (e: JSONException) {
    Log.e("AlanButton", e.message)
  }
  // Calling the project API method on button click
  alanButton?.callProjectApi("script::greetUser", params.toString())
}
Client app
void callProjectApi() {
  alanButton.activate();
  JSONObject params = new JSONObject();
  try {
    params.put("user","John Smith");
  } catch (JSONException e) {
    Log.e("AlanButton", e.getMessage());
  }
  // Calling the project API method on button click
  alanButton.callProjectApi("script::greetUser", params.toString());
}
Client app
_MyHomePageState() {
  void _callProjectApi() {
    AlanVoice.activate();
    // Calling the project API method on button click
    var params = jsonEncode({"user":"John Smith"});
    AlanVoice.callProjectApi("script::greetUser", params);
  }
}
Client app
var myAlanBtn = document.getElementById('myAlanBtn');
myAlanBtn.componentOnReady().then(function () {
  myAlanBtn.activate();
  // Calling the project API method on button click
  myAlanBtn.callProjectApi("greetUser", {user: "John Smith"}, function (error, result) {
    console.log("project API function has been called", error, result);
  });
});
Client app
import { AlanView } from '@alan-ai/alan-sdk-react-native';
import { NativeEventEmitter, NativeModules } from 'react-native';

const {AlanManager, AlanEventEmitter} = NativeModules;

export default class MyApp extends Component {
  onPress = {() =>
    AlanManager.activate();
    // Calling the project API method on button click
    AlanManager.callProjectApi(
      'greetUser',
      {user: 'John Smith'},
      (error, result) => {
        if (error) {
          console.error(error);
        } else {
          console.log(result);
        }
      },
    )
  }

Note

You can test project API methods defined in the dialog script directly in Alan AI Studio. For details, see Testing project API methods.