Retail Assistant Guide

Steps to integrate the retail assistant into your app

Slang’s Android retail assistant (aka SlangRetailAssistant) is a fully trained voice assistant specialized for Android apps in the Retail domain. By integrating with this assistant, apps can help their users perform the following user journey through voice:

• Search for the grocery retail items

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

Update the app’s build.gradle files to include the following repository

top-level build.gradle

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

Then, add the following library to your app’s dependencies:

app's build.gradle

dependencies {  
    …   
    implementation 'in.slanglabs.assistants:slang-retail-assistant:0.0.51'
}

Step 2: Register actions to be performed (mandatory)

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 as shown below.

MainActivity.java

SlangRetailAssistant.setAction(new SlangRetailAssistant.Action() {
    @Override    
    public SearchResult onSearch(SearchInfo searchInfo, AssistantSession session) {
            // @param SearchInfo - Contains the search details. Refer 'SearchInfo' section below for details.
            // @param AssistantSession - Assistant session object that corresponds to current conversation.
            
            // @return SearchResult - Status of the onSearch action. Refer the below section for the details.              
    }        
    
    public void onAssistantError(AssistantError error) {        
            // @param AssistantError - Contains the details of the error.
    }
});

onSearch action handler is called once the assistant collects the details of the search from the user. It passes SearchInfo and AssistantSession objects are parameter and the handler is expected to return SearchResult once taking necessary action.

SearchInfo: Contains the details about the search made by the user. RetailItem is the key member of this object that contains the details about the item being searched. RetailItem provides below APIs to get granular details of the item being searched.

RetailItem.java

public String getBrand() {
    //Returns the brand name of the item if specified.
    //Eg: Britannia, Head and shoulders, Tide, etc.
}

public String getProductType() {
    //Returns the item name
    //Eg: rice, shampoo, juice, etc.
}

public String[] getVariants() {
    //returns the array of variants of the item.
    //Eg: cool menthol, blue, organic, etc.
}

public Quantity getQuantity() {
    //Returns if any quantity is mentioned in the query.
    //Eg: 10 packs, 5 bottles, etc.
}

public Size getSize() {
    //Returns the size details if mentioned in the query.
    //Eg: 2 kg, 500 ml, etc.
}

public Price getPrice() {
    //Returns the price details if mentioned in the query.
    //Eg: 2 rupees (sachet), 10 ruppes (bar), etc.
}

public String getDescription() {
    //Utility method that returns the item description that is ready to be used in the search.
    //This is typically done by appending brand, variants and item name.
    //If the needs of the app isn't fulfilled with this, you should be using the individual API (mentioned above) and generate your own search string.
}

SearchResult: The SearchStatus value that you return from the onSearch() API allows you to have fine-grained control over the behavior of the SlangAssistant in the following ways:

• UNSUPPORTED - Indicates that the app is not handling this particular user journey. Slang assistant will speak an appropriate message to the user and exit.

• SEARCH_SUCCESS - Indicates that the search was successful. Slang assistant will speak an appropriate success message to the user and exit.

• SEARCH_FAILURE - Indicates that the search was not successful. Optionally, the reason for the failure can be set in the AssistantSession object. Slang assistant will speak an appropriate failure message to the user and exit. Supported failure reasons are:

  • ITEM_NOT_FOUND - Indicates that the requested item is not sold on the app.

  • ITEM_OUT_OF_STOCK - Indicates that the requested item is not in stock currently.

• WAIT_FOR_ACTION_COMPLETE- Indicates that the app cannot return the search result/status right away and needs to do something else before notifying the assistant about the result/status of the action. When this happens, the assistant will wait until the app notifies the result/status of the search action through the API provided in the AssistantSession object which gets passed as a parameter to the onSearch action handler.

AssistantSession: This is the assistant's session object for the current interaction with the user. This should be used in conjunction with the search result. Mainly to communicate failure reasons and notifying the search result asynchronously. Below are the APIs to be used for these purposes.

setSearchFailureReason(SlangRetailAssistant.SearchFailureReason failureReason);
notifyActionCompleted(SlangRetailAssistant.SearchResult result);

Step 3: Initialize the assistant (mandatory)

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

MyApplication.java

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

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

MainActivity.java

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

Step 4: Showing/Hiding the assistant UI (mandatory).

Display the assistant UI on the appropriate activity. From this point onwards, the assistant UI will automatically appear on all the activities launched by the app.

MainActivity.javaprotected void onCreate(Bundle savedInstance) {  
    …  
    SlangRetailAssistant.getUI().show(this);    
    
    // To hide the UI, do the following:  
    SlangRetailAssistant.getUI().hide(this);
}

Step 5: Starting the conversation automatically (optional).

By default, the Slang assistant will prompt the user to speak the item to search on the user clicking the trigger. However, if the app would like to prompt users automatically when landed on a specific page, it could do so by using the below API.

SlangRetailAssistant.startConversation(AssistantUserJourney.SEARCH);

Step 6: Notifying assistant about non-voice item search (optional)

In order to learn and improve the voice assistant, it is recommended to notify the assistant about any search action performed by the user using the touch/UI instead of voice. You can do this by using the below API

Map<String, String> journeyProperties = new HashMap();
//add all search details to journeyProperties map.
SlangRetailAssistant.notifyNonVoiceUserJourney(AssistantUserJourney.SEARCH, journeyProperties);