Note: This section applies only to Android and ReactNative platforms
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.
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;},
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);
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
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:
Let's say the user says "onions"
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.
Now let's say the user says "show me organic ones"
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 productType
with "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
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
​