Running a USSD Session

Once you have verified that a user has the correct SIM to run an action, use HoverActivity to start and manage a USSD session for you.

Button button= (Button) findViewById(R.id.action_button);
button.setOnClickListener(new View.OnClickListener() {
	@Override
	public void onClick(View v) {
		Intent i = new HoverParameters.Builder(this)
			.request("action_id")
			.extra("step_variable_name", variable_value_as_string) // Only if your action has variables
			.buildIntent();
		startActivityForResult(i, 0);
	}
});

onActivityResult() Callback

By using startActivityForResult() you will get the content of the session once it completes.

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

If the resultCode is RESULT_OK then the USSD session was successfully initiated. You can find out the details of the session and whether it successfully completed by inspecting the intent extras provided and parsing the text (see below). If the result code is RESULT_CANCELED then something went wrong before starting the session. In this case the data intent returned will have a String Extra called error which will contain the error message.

In some cases a transaction confirmation based on a parser can come before onActivityResult is called. If you need to know about the pending transaction first then you can listen for the local broadcast intent fired when the pending transaction is first created. This should come before any confirmation and has all the same details about the transaction as onActivityResult.

private void callHover() {
		LocalBroadcastManager.getInstance(context).registerReceiver(pendingTransactionReceiver, new IntentFilter("PENDING_TRANSACTION_CREATED"));
        startActivityForResult(createHoverIntent(), 0);
	}
	private final BroadcastReceiver pendingTransactionReceiver = new BroadcastReceiver() {
		@Override
		public void onReceive(final Context context, final Intent i) {
			Log.i(TAG, "Recieved pending transaction created broadcast");
            Log.i(TAG, "uuid: " + i.getStringExtra("uuid");
		}
	};

Don’t forget to unregister your reciever when your activity is destroyed.

Getting a Session Result

The data intent returned in onActivityResult() contains the following information if the result is RESULT_OK

You can parse the text from the USSD session in your own code, or create parsers through Hover. Hover parsers make it easy to extract and access information such as confirmation details and USSD session status within your application code.

Dual SIM support

Hover supports dual SIM out of the box, with helpers to help you find out what SIMs the user has. When you run an Action the correct SIM is used automatically. If the user has two of the same SIM, or more than one SIM that will work with the given action, they will be presented with a dialog to choose the SIM they wish to use. See dual SIM.

Test Environment

If you do not have access to the SIM card or network you wish your users to use you can activate the SDK test environment by calling .setEnvironment(HoverParameters.TEST_ENV) on your HoverParameters.Builder(). If you have the correct SIM then using the default is preferable since it returns real information from your real account. TEST_ENV is still a work in progress and does not provide all the necessary information. However, the default will inccur standard charges from the mobile money service and count against your Hover credits (which is part of why we provide free credits), whereas TEST_ENV does not.

Debug Environment

If your USSD session does not seem to be running correctly and you want more visibility into what is happening you can activate the SDK debug environment by calling .setEnvironment(HoverParameters.DEBUG_ENV) on your HoverParameters.Builder(). This will prevent the Screen Blocker from displaying, allowing you to see the USSD session as it happens, and adding more logging information to the logcat. Do not interact with the session when you see it in this mode; if nothing happens you should recheck your action configuration. If it still doesn’t work it is most likely a device specific issue, try with a different device and contact us so we can check the device and help you out. Please do not run debug mode in production: when users see the USSD messages flash across the screen it scares them, the blocking processing screen should always be in place.

Advanced Usage

In some cases you may need information from the USSD session before you can complete a transaction. For example you may want to get a recipients name so that the user can confirm that it is the correct recipient. To do this you currently need to create 2 separate actions. The first you will configure to run through the USSD steps until the menu that has the information you need. Make that the final step, then create a parser which pulls the details you need out of the message. Use the TRANSACTION_UPDATE broadcast to recieve this information and trigger showing it to the user. Once they have confirmed or otherwise acted based on the information you can then start a second action which you have configured to run the transaction through to completion. Please remember that in some cases your users are charged per USSD session and will not appreciate being charged twice.

Next: Parse responses