Quick Start

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.

Prerequisites

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:

repositories {
	mavenCentral()
	maven { url 'http://maven.usehover.com/releases' }
}

dependencies {
	implementation('com.hover:android-sdk:0.17.0-rc1') { transitive = true; }
}

Then include your API token as application level metadata in your AndroidManifest.xml:

<application>
	...
	<meta-data
		android:name="com.hover.ApiKey"  
		android:value="<YOUR_API_TOKEN>"/>
</application>

Initialize Hover

First have your app initialize the Hover SDK by calling Hover.initialize(). This needs to be done once, ideally at app launch.

import com.hover.sdk.api.Hover;
...

public class MainActivity extends AppCompatActivity {
...
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		...

		Hover.initialize(this);
	}
    ...

}

Start a USSD Session

Get Permission

Before running a USSD session you must get the READ_PHONE_STATE, BIND_ACCESSIBILITY_SERVICE, and 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:

Intent i = new HoverParameters.Builder(this)
	.request("action_id").
	.extra(“action_step_variable_name”, variable_value)
	.buildIntent();
startActivityForResult(i, 0);

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

Implement onActivityResult() to get the content of the session. If the resultCode is 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.

@Override
protected void onActivityResult (int requestCode, int resultCode, Intent data) {
	if (requestCode == HOVER_REQUEST && resultCode == Activity.RESULT_OK) {
		String sessionTextArr = data.getStringArrayExtra("ussd_messages");
		String uuid = data.getStringExtra("uuid");
	} else if (requestCode == HOVER_REQUEST && resultCode == Activity.RESULT_CANCELED) {
		Toast.makeText(this, "Error: " + data.getStringExtra("error"), Toast.LENGTH_LONG).show();
	}
}

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.