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 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.

Prerequisites

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:

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

dependencies {
	implementation('com.hover:android-sdk:0.17.0-rc5') { 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>

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.

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

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

		Hover.initialize(this);
	}
		...

}

3. 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 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.

Get information about the session

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();
	}
}

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.