README
SlangPharmacyAssistant.
Slang Pharmacy Voice Assistant for react native apps for android.
Prerequisites
Before starting with adding slang pharmacy voice assistant to your app, you must've received 'BUDDY_ID' and 'API_KEY' from us. If you don't have it, please contact 42@slanglabs.in with relavant details of your app.
Step 1 - Installation
Add below 2 packages to your project.
react-native-slang
:npm install react-native-slang --save
oryarn add react-native-slang
slang-pharmacy-assistant
:npm install slang-pharmacy-assistant --save
oryarn add slang-pharmacy-assistant
Step 2 - Setting up the android project
- In your android project level build.gradle, add
allprojects {
repositories {
...
maven {
url "http://maven.slanglabs.in:8080/artifactory/gradle-release"
}
...
}
}
- For automatic linking of the slang library with native code, run
react-native link react-native-slang
Step 3 - Usage
To initialize SlangPharmacyAssistant
Import SlangPharmacyAssistant where you want to initialize it
import SlangPharmacyAssistant from 'slang-pharmacy-assistant';
Once you have SlangPharmacyAssistant in scope, by following either of the above two methods, you have to initialize SlangPharmacyAssistant.
SlangPharmacyAssistant.initialize({
requestedLocales: ['en-IN'], //List of locales to be supported.
buddyID: 'BUDDY_ID', //Required
apiKey: 'API_KEY', //Required
pharmacyAssistantListener, //Required //Listener object that will be notified by SlangPharmacyAssistant for defined voice actions. Refer below for details on the listener object.
}
);
SlangPharmacyAssistant.show(); //Required to be called whenever you are ready to show the voice assistant trigger on the screen.
pharmacyAssistantListener
SlangPharmacyAssistant will listen to user's voice, processes the spoken utterance and extracts certain information and notifies the app. The way this is done is through pharmacyAssistantListener.
pharmacyAssistantListener object is expected to have the methods onItemSearched(pharmacyItem) and onError(errorCode) implemented.
onItemSearched(pharmacyItem): On detecting the user intention to search medicine, SlangPharmacyAssistant will extract, create and pass the pharmacyItem object with details such as: name, type, strength, unitStrength, packSize.
name holds the name of the medicine.
type holds the type of the medicine (Ex: tablets/capsule/syrup/cream/drops/etc..)
strength holds the amount of active ingredient in the medicine (Ex: 650, 500, etc.)
unitStrength holds the unit if the active ingredient (Ex: 'mg', 'ml', etc.)
packSize holds the number packas of the medicine.
onError(errorCode): This is a very important method through which the Slang assistant communicates with the app whenever it detects an error. Apps must ensure that they implement this method and handle the various types of errors.
The most important types of errors, and how to handle them are described below. SlangPharmacyAssistant.ERROR_CODE.FATAL_ERROR: This error type indicates that the Slang assistant encountered a fatal error and cannot continue. Upon receiving this error, the app must ensure that the app UI indicates that the Slang assistant is not available. SlangPharmacyAssistant.ERROR_CODE.ASSISTANT_DISABLED: This error type indicates that the Slang assistant is disabled for the current device. Upon receiving this error, the app must ensure that the app UI indicates that the Slang assistant is not available. SlangPharmacyAssistant.ERROR_CODE.MISSING_CREDENTIALS: This error type indicates that the either or both of the required credentials (buddy id, API key) were not supplied during initialization. SlangPharmacyAssistant.ERROR_CODE.INVALID_CREDENTIALS: This error type indicates that invalid credentials (buddy id, API key) were supplied during initialization. SlangPharmacyAssistant.ERROR_CODE.SYSTEM_ERROR: This error type usually indicates that a non-fatal system error occurred. The error is informational and the app should be able to continue execution despite receiving this error.
Example of pharmacyAssistantListener:
const pharmacyAssistantListener = {
onPharmacyItemSearched: searchItem => {
if (searchItem.name) console.log("Name:" + searchItem.name);
if (searchItem.type) console.log("Type:" + searchItem.type);
if (searchItem.strength) console.log("Strength:" + searchItem.strength);
if (searchItem.unitStrength) console.log("Unit:" + searchItem.unitStrength);
if (searchItem.packSize) console.log("Pack Size:" + searchItem.packSize);
},
onError: errorCode => {
switch (errorCode) {
case SlangPharmacyAssistant.ERROR_CODE.FATAL_ERROR:
console.error('Slang Fatal Error!');
break;
case SlangPharmacyAssistant.ERROR_CODE.SYSTEM_ERROR:
console.error('Slang System Error!');
break;
case SlangPharmacyAssistant.ERROR_CODE.ASSISTANT_DISABLED:
console.error('Slang Assistant Disabled!');
break;
case SlangPharmacyAssistant.ERROR_CODE.MISSING_CREDENTIALS:
console.error('Slang Missing Credentials!');
break;
case SlangPharmacyAssistant.ERROR_CODE.INVALID_CREDENTIALS:
console.error('Slang Invalid Credentials!');
break;
}
};
Additional APIs supported
To get things started and working, just initialising with appropriate listener and calling show() API whenever you want to start showing the voice assistant is good enough.
However, for more deeper integrations, refer the below APIs.
Hide the SlangPharmacyAssistant
SlangPharmacyAssistant.hide(); //Self explanatory.
Show the SlangPharmacyAssistant
SlangPharmacyAssistant.show(); //Self explanatory.
To start the search conversation pro-actively (without having user to click the trigger)
SlangPharmacyAssistant.startSearchConversation();
To report the non voice search actions to SlangPharmacyAssistant for deeper analysis of user behavior
SlangPharmacyAssistant.notifyNonVoiceSearch(pharmacyItem);
pharmacyItem here is nothing but a object that is similar to what you received in onItemSearched call back in pharmacyAssistantListener. It is expected to have name, strength, unit, type and pack size. All fields are optional but it is recommended to send the 'name' of the medicine at the least. By reporting the non voice (typed) search to SlangPharmacyAssistant, we can provide you with deeper user behavior analytics to understand the user better and improve the product/app.
In addition, there are few voice assistant's Trigger specific APIs which you can use to customise its behavior.
SlangPharmacyAssistant.setTriggerSize(width, height); //Self explanatory.
SlangPharmacyAssistant.setTriggerDraggable(isDraggable) //You can use this to enable/disable draggable property of trigger. If enabled, user can drag the trigger around and place where they want.
SlangPharmacyAssistant.setTriggerPosition(definedPosition, offsetX, offsetY, forceStartingPosition); //Refer below for the predefined base position of trigger on the screen. offsetX and offsetY are the offset of the trigger from the definedPosition. If you have not disabled the ability to drag the trigger, you could use the parameter forceStartingPosition to tell the assisiatnt to ALWAYS start from the fixed position on every launch. If you set this to false, trigger position will start from the location where user has left in previous launch of the app. _definedPosition can be one of the below values. By default the trigger is placed at "CENTER_BOTTOM".
SlangPharmacyAssistant.TRIGGER_BASE_POSITION.LEFT_TOP SlangPharmacyAssistant.TRIGGER_BASE_POSITION.CENTER_TOP SlangPharmacyAssistant.TRIGGER_BASE_POSITION.RIGHT_TOP SlangPharmacyAssistant.TRIGGER_BASE_POSITION.LEFT_CENTER SlangPharmacyAssistant.TRIGGER_BASE_POSITION.CENTER SlangPharmacyAssistant.TRIGGER_BASE_POSITION.RIGHT_CENTER SlangPharmacyAssistant.TRIGGER_BASE_POSITION.LEFT_BOTTOM SlangPharmacyAssistant.TRIGGER_BASE_POSITION.CENTER_BOTTOM SlangPharmacyAssistant.TRIGGER_BASE_POSITION.RIGHT_BOTTOM
Contact
For any queries contact us at 42@slanglabs.in