Hover helps developers automate USSD sessions in the background of Android applications. Our Android SDK can run virtually any USSD interaction on any mobile operator anywhere in the world. This includes payments, airtime topup, bill pay and more. Hover is most useful for integrating with services that do not offer an API but do have a USSD channel. Hover enables developers to make USSD-based services more accessible to users with visual impairments or impairments related to literacy or numeracy.
- Target Android API level 18 or higher
- Have a SIM card that runs the USSD service you wish to integrate
- A Hover account
If you are new to Android or starting your app from scratch, we have an app on Github that can help you get going faster. Just follow the instructions in the README.
1. Create an Action
Actions are how you configure the Hover SDK to run USSD sessions on your users' devices. Go to Create an Action and choose a name and the mobile network (SIM card) that the action works with. Then enter the root code and ordered steps that are normally completed by a user from their device. Under "parsers" you can add regular expressions to detect and use USSD session responses, but if this is your first action we suggest you leave this blank for now.
2. Install the SDK
As of November 28, 2018 the current version of the Hover SDK is 0.17.0-rc5
Add Hover to your app-level build.gradle dependencies:
Then include your API token as application level metadata in your AndroidManifest.xml:
Finally, have your app initialize the Hover SDK by calling
Hover.initialize(). This needs to be done once, ideally in your main launch activity. Please do not do this in your Application class.
3. Start a USSD Session
Before running a USSD session you must get the
SYSTEM_ALERT_WINDOW permissions. Hover provides a helper Activity to help you get these permissions, but you can also do it yourself. If you start an action without these permissions Hover will automatically use its helper to get them from the user. Learn more at permissions.
Run an Action
Create a request and launch the intent, specifying an
action_id. The names and values for any variable action steps should be added as extras:
In production, you'll often want to check whether the user has the correct SIM card before calling an action. The Hover SDK provides helper methods for this, see using actions for details.
Get information about the session
onActivityResult() to get the content of the session. If the
RESULT_OK then as far as the SDK can tell the request was accepted and is being processed by the USSD operator. If the result code is
RESULT_CANCELED then something went wrong and you should not expect the request to succeed. In this case the data intent returned will have a String Extra called
error which will contain the error message.
4. (Optional) Parse the Result
Hover provides a number of helpers for parsing the content and result of a USSD session, or you can do it yourself. See parsing for more.