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, including 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 further 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
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.
Install the SDK
As of September 17, 2018 the current version of the Hover SDK is 0.17.0-rc1
Add Hover to your app-level build.gradle dependencies:
Then include your API token as application level metadata in your AndroidManifest.xml:
First have your app initialize the Hover SDK by calling
Hover.initialize(). This needs to be done once, ideally at app launch.
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 installation and 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.
Use the Result
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.
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.