Accounting Assistant Guide

Steps to integrate the retail assistant into your app

Slang’s Android accounting assistant (aka SlangAccountingAssistant) is a fully trained voice assistant specialized for Android apps in the Accounting domain. By integrating with this assistant, apps can help their users perform the following types of tasks through voice:

• Add 'sale' transaction with details of the customer, sale amount, paid amount, and notes for the transaction.

The following guide describes the steps that apps need to take in order to integrate with the assistant.

Integration Details

Step 1: Update Gradle dependencies

Update the project level build.gradle file to include the following repository.

allprojects {  
    repositories {    
        maven { url "http://maven.slanglabs.in:8080/artifactory/gradle-release" }  
    }
}

Then, add the following library to your app’s build.gradle file:

dependencies {  
    implementation 'in.slanglabs.assistants:slang-accounting-assistant:0.0.9'
}

Step 2: Add UI elements to your activities

In your app’s activities where you’d like to provide the option to enable/disable the active voice mode, you will need to add the assistant’s UI elements into the appropriate XML layouts like this:

activity_main.xml

<LinearLayout … >
  <in.slanglabs.assistants.accounting.SlangAccountingAssistantToggleButton
    android:clickable="true"
    app:active_voice_mode_img_src="<voice-on-resource>"
    app:inactive_voice_mode_img_src="<voice-off-resource>"
    app:enable_voice_mode="true"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content" />
  …
</LinearLayout>

Behaviour of SlangAccountingAssistantToggleButton

The SlangAccountingAssistantToggleButton is the assistant's UI element which the users can click to start a voice transaction. The behaviour of the ToggleButton is sticky in nature, i.e. it persists with the user's choice. The default value of the enable_voice_mode is true, which means when the app calls the SlangAccountingAssistant.startVoiceTransaction() API, it would successfully start a new voice transaction. If the user choses to cancel the voice session, the voice mode will be turned off, and all further calls to startVoiceTransaction() would return false. The voice mode will continue to remain turned off, until the user clicks on the ToggleButton and completes a new voice transaction.

Step 3: Register actions to be performed

Firstly, you will need to register action methods that will be called by the assistant on behalf of the end-users to service their requirements.

SlangAccountingAssistant.setAction(new SlangAccountingAssistant.Action() {
    @Override    
    public Status onSaleTransaction(Transaction transaction, in.slanglabs.assistants.accounting.AssistantSession session) {
            // Transaction object contains fields customerName, totalAmount, paidAmount and notes 
            // extracted from the voice input and ready to be processed by the app.
            
            // App should return one of the following values.
            // UNSUPPORTED - if search use case is not supported by the app        
            // SUCCESS - If the transaction was handled successfully
            // FAILURE - If the transaction was handled successfully
            // WAIT - If the transaction will be handled asynchronously 
            // and app will be notifying the assistant about the success/failure on a different thread.
    }        
    
    public void onAssistantError(AssistantError error) {        
            // handle errors reported by the assistant
    }
});

Asynchronous action handling

In the scenario where the app cannot complete the processing of the action synchronously inside the action method, it can do so by asking the assistant to wait and notify it once the action handling is done. This need can be achieved using the 'AssistantSession' passed in the action methods. Refer to the below example code snippet to understand how to achieve this.

@Override
public Status onSaleTransaction(Transaction transaction, AssistantSession session) {
    //Launch your asynchronous processing here.
    processTransaction(transaction, session)
    return Status.WAIT;
}

//Below method mimicks the asynchronous processing of transaction.
private void processTransaction(Transaction transaction, final AssistantSession session) {
  new Handler().postDelayed(new Runnable() {
        @Override
        public void run() {
            //Notify assistant about the status of the action.
            session.notifyActionCompleted(Status.SUCCESS);
        }
    }, 1000);
}

Step 4: Initializing the accounting assistant

If your app has an Application class, then initialize the assistant in the onCreate() method of the Application. You’d need <API_KEY> and <ASSISTANT_ID> for this. You should’ve received this from the Slang team. If not, please ask :)

public void onCreate() {  
    …  
    AssistantConfiguration configuration = new AssistantConfiguration.Builder()    
        .setAPIKey(<API_KEY>)    
        .setBuddyId(<ASSISTANT_ID>)    
        .build();  
    SlangAccountingAssistant.initialize(this, configuration);
}

If your app does not have an Application class, then you can initialize the assistant in the main activity instead.

protected void onCreate(Bundle savedInstance) {  
    …  
    AssistantConfiguration configuration = new AssistantConfiguration.Builder()    
        .setAPIKey(<API_KEY>)    
        .setBuddyId(<ASSISTANT_ID>)    
        .build();  
    SlangAccountingAssistant.initialize(this, configuration);
}

Step 5: Starting the voice conversation

In order for the assistant to automatically prompt for taking voice input and record the transaction, the app needs to call the API "startVoiceTransaction()" on the screen where the assistant trigger is embedded. However, if the voice mode is disabled, the assistant will not honor the request. So, the app should check the return value of this API and handle accordingly (for example: showing the keyboard automatically if voice mode is disabled) like below

if (!SlangAccountingAssistant.startVoiceTransaction()) {
    // Voice mode is disabled by user, app should handle appropriately.
}