Parsing

Hover's SDK includes an easy way to help you parse out messages from USSD sessions and SMS responses. While the text of USSD sessions is always returned when you use Hover's SDK, and you can use Android APIs to get SMS responses, we want to make it as easy as possible for you to get what you need. When you create an Action in your Hover dashboard you have the option of adding parsers. Each parser is a regular expression and and optional SMS sender. If a sender is not specified then the parser will be used to match against the last USSD session message. (This will soon change to any USSD session message)

See our blog post for more on writing parsers.

Writing the Regex

Your regex should be as specific as possible to prevent matching unrelated messages. However, you should also account for variation that can occur, such as ads at the end of the message. We recommend ending your regex with .* and replacing whitespace with [\s]*. The SDK uses named-groups in the regex to parse out variables and return them to you. So if you want to run a balance check and get the balance parsed out of the message, the balance in the regex might look like (?<balance>[0-9\,\.]+). Any named groups parsed out of the confirmation will show in the transaction details for that transaction in the Hover Dashboard. See below for how to get this information in-app.

Matching SMS

If the SMS sender is specified in your parser, then the SDK will watch for any SMS message from that sender and attempt to use the regular expression to match the message. If it matches, then the SMS will be assumed to be related to the most recent pending session for the parser's action. You can use this to match a mobile money confirmation from the operator, or you could use it to match a related SMS, for example an electricity token from the electricity provider after taking a Pay Bill action.

Implement the Parsed Message Receiver In-App

Add a BroadcastReceiver which receives intents with the action YOUR.PACKAGE.NAME.CONFIRMED_TRANSACTION to your Android Manifest. Make sure exported is false otherwise another app could spoof successful transactions:

<receiver
		android:name=".TransactionReceiver"
		android:enabled="true"
		android:exported="false">
		<intent-filter>
				<action android:name="app.package.name.CONFIRMED_TRANSACTION"/>
		</intent-filter>
</receiver>

Create the Receiver itself and use the intent as you need:

public class TransactionReceiver extends BroadcastReceiver {
	public TransactionReceiver() { }

	@Override
	public void onReceive(Context context, Intent intent) {
		String uuid = intent.getStringExtra("uuid");
		if (intent.hasExtra("transaction_extras")) {
		HashMap t_extras = (HashMap) intent.getSerializableExtra("transaction_extras");
		if (t_extras.containsKey("confirmCode"))
			String confirmationCode = t_extras.get("confirmCode");
		if (t_extras.containsKey("balance"))
			String balance = t_extras.get("balance");
	}

	}
}

The intent received will contain the meta data about the transaction, such as the action, transaction uuid, and original message. The named-groups that have been parsed out are in a serialized HashMap extra called transaction_extras. It is recomended that you check that an extra is present first with extras.containsKey()

Extra Description
uuid Unique Identifier for the transaction
action_id The action id from our supported operators page
response_message Full message used for parsing
request_timestamp Time user initiated transaction (Unix time)
response_timestamp Time at which the message arrived (SMS arrival or USSD session time)
transaction_extras A HashMap object of all named groups parsed out of the response message based on your regex