Documentation 3.0 Beta
Creating Custom Client Actions
The Akula Server includes several built-in client actions that you can trigger in the client app. However, you can also create custom client actions that can also be triggered by an Akula administrator.
This section describes the following topics:
For information a list of client actions that are included with Akula, see Pre-built Client Actions.
Defining event listeners
Custom client actions are defined entirely in the client app. For a custom action, you can implement event listeners for all three stages of action execution:
Custom actions differ from built-in actions in that you must implement the execution logic for the action in the app, and optionally the pre-action and post-action logic. You can define multiple listeners for the pre-action and post-action stages. You can only define one listener for the execute stage.
During the execute stage, you typically set the status of the custom action. You can set it to one of the following: COMPLETED, FAILED, or IGNORED, depending on whether the action successfully processes. To set the status of the action, use the following methods of the AKActionCompleteCallback (Android) or AKActionCompleteDelegate (iOS) classes:
complete()– Sets the action status to COMPLETE. You typically set the status to COMPLETE when the execute event listener successfully processes the action.
failed()– Sets the action status to FAILED. You typically set the status to FAILED when one of the listeners throws an error during action execution.
ignored()– Sets the action status to IGNORED. You can set the status to IGNORED if you have some condition in which an action might not be processed on the client. In addition, the client SDK sets your action status to IGNORED if the custom action does not define an execute event listener.
These status methods make a network call to update the Akula Action Service with the status, and can optionally include a message which is stored in the Akula database. For more information about action statuses, see Action Statuses.
resolve()– Sets the status to either COMPLETED or IGNORED, depending on which string you pass.
reject()– Sets the status to FAILED.
The following example defines custom listeners for an action on Android, and sets the action status to COMPLETED if the action successfully executes (otherwise, FAILED):
The following example defines a custom execute listener for an action on iOS, and sets the action status to COMPLETED if the action successfully executes (otherwise, FAILED):
Triggering a custom action
Triggering a custom action is the same as triggering a pre-built action. You can issue a new action request from the Management Console, via the REST API, with the Command-line Management Utility, or in a custom module. For more information, see Creating a Client Action Request.
The client can receive the action in the same manner: either when polling or requesting new actions. For more information, see Polling for New Actions.
As with pre-built actions, you must ensure that the name of the action you specify is the exact same String that the client app registers its listeners for. For example, if your action name is "com.example.rinse", then your listener registration must use that name:
The same rules apply to custom actions as built-in actions when matching actions by name: A less specific name matches more actions. For example, "com.example" matches the "com.example.wash" and "com.example.rinse" actions.
If the Akula administrator issues a new action request for an action whose name does not match the action in the client app, then the action execution fails silently on the client and the Akula Action Service changes the status to IGNORED on the server.