Asynchronous Action Handling

While handling a user journey, the app might not be able to identify the state or the condition of the journey in a synchronous way. For example, the app could open a new activity (or page) which could then fire up a search to the back-end and show the results. So the callback itself would not be aware of the result unless it blocks till the entire activity is loaded. This is not desirable and leads to poor UX.

To solve this problem, the Slang Assistant programming model provides ways for the app to asynchronously signal the Assistant about the app state changes and conditions.

This can be done by using the "wait" and "notify" semantics. The process is quite straightforward. In order to deal with asynchronous operations within the callback:

• The app must return the AppState WAITING to inform the Assistant that it's not yet ready to identify the state or the condition of the app. The Assistant goes into a "waiting" state without blocking the UI or other threads and continues wait for further notification from the app.

• When the app has completed the asynchronous operation, it can then call notifyAppState to notify the Assistant to proceed further.

Returning WAITING AppState

The app should return WAITING from the user journey callback. This would keep the Assistant in a "processing" (which is what it would have been when it invoked the callback).

public SearchUserJourney.AppState onSearch(SearchInfo searchInfo, SearchUserJourney searchJourney) {        
    // Fire an async search request
    // ...
    return SearchUserJourney.AppState.WAITING;
}

onSearch: async (searchInfo, searchUserJourney) => {
    // Fire an async search request
    // ...
        
    return SlangRetailAssistant.SearchAppState.WAITING;
  },

Notifying the Assistant

Once the Assistant is asked to wait, it will continue to remain in the "processing" state until the app notifies it to stop waiting, or the user cancels the operation through the UI. For best results, the app should ensure that every path that returns WAITING has an accompanying call to notify the Assistant.

To notify the Assistant with the AppState, the app needs access to the UserJourney object that was passed to the callback. This can be accessed via a global helper method getLastSearchUserJourney and then call notifyAppState on that object.

SearchUserJourney userJourney = SlangRetailAssistant.getLastSearchUserJourney();
​
userJourney.setSearchSuccess();
userJourney.notifyAppState(SearchUserJourney.AppState.SEARCH_RESULTS);

SearchUserJourney userJourney = SlangRetailAssistant.getLastSearchUserJourney();
​
userJourney.setSearchSuccess();
userJourney.notifyAppState(SearchUserJourney.AppState.SEARCH_RESULTS);

Programmatic Conversations

Sometimes the app might want to launch the Slang Voice Assistant on its own, without the user explicitly launching it via the Trigger. This could be achieved by calling the startConversation API and passing the name of theUserJourney that is to be launched. The Assistant will speak out the greeting message associated with that user journey in that case.

SlangRetailAssistant.startConversation(AssistantUserJourney.SEARCH);

SlangRetailAssistant.startConversation(AssistantUserJourney.SEARCH);

Under development

Accessing and Setting User Journey Context

When the user journey callbacks are called, the Assistant passes details of the command via the Info parameter. But when users trigger the same user journey multiple times, the Assistant preserves the context of the previous invocation and reuses it. For example:

1. Let's say the user says "onions"

2. The Assistant invokes the onSearch callback and passes the SearchInfo object with "onions" as the value for theproductType field. All other fields in the object will be empty.

3. Now let's say the user says "show me organic ones"

4. The Assistant now invokes the onSearch callback again and this time passes the SearchInfo object with two fields set: variant with "organic" as the value and also productTypewith "onions" as the value. This way, it preserves the context between multiple invocations.

Sometimes the app might want to access or set the context outside the scope of the callbacks.

The Assistant is built to be used in a multi-modal environment, where the users might use the UI to perform certain operations and voice to perform others. It's quite natural for the user to be searching for an item by typing it and then switch to voice to provide additional filters. In such cases, the app can pass data to the Assistant explicitly via the appropriate user journey context APIs, as below:

SearchUserJourney.getContext().getProductType();
SearchUserJourney.getContext().setProductType("onions");

var category = SearchUserJourney.context.getItemCategory();
SearchUserJourney.context.setItemCategory("grocery");

Under development

Sometimes, it could be important to not preserve context automatically. For example, if the user has cleared the results and started a new search, then this may need to be treated as a fresh search rather than as a continuation of the previous search.

In such cases, the app can easily clear the context as shown below

SearchUserJourney.getContext().clear();

SearchUserJourney.context.clear();

Under development

Keeping assistant's locale in sync with the app locale

If the app supports multiple locales and has the option for the user to change it, the app might want to change the assistant locale on the fly to keep it in sync with the app's locale. You can do so by using the below API

SlangRetailAssistant.changeLocale(SlangLocale.LOCALE_ENGLISH_IN);

TODO

Under development

​