How to integrate the Hover SDK with Flutter 🇹🇿 💸 💻
A guest post by Francis Mwakatumbula, Dar es Salaam, Tanzania
This article will show you step by step how to automate USSD sessions using Hover SDK on your Flutter.
My name is Francis Mwakitumbula, a software engineer from Lockwood Technology based in Dar es Salaam, Tanzania. I’m going to show you how to accept payments from any mobile money wallet in Africa using the Hover SDK in your Flutter app. We used the SDK at Lockwood to create Kikoba, a mobile wallet that allows VIKOBA (Village Community Banks) in Tanzania to transact using a simple and intuitive UI, making USSD only a transport layer. For more details on the Hover SDK, check out their documentation.
Integrating the SDK requires four main steps
- Create an Action
- Install the SDK in your Android app
- Run your Action
- Parse the response (optional)
Note: if you already have a Flutter app just follow the steps to integrate the Hover SDK to start running USSD sessions on your app. If not, you can start a new Flutter app or clone a demo app here.
1. Sign in to your Hover account and create a new action
To begin, sign up for a Hover account or sign in to your existing one. From the dashboard, click “New action” and give your action a name. For this example, we’ll call it “Send money”. Select the country and mobile operator, then enter the root code, i.e. the string a user would dial to initiate the USSD session: *150*01#. For more details view Hover Documentation.
2. Configure your action
Actions instruct the Hover SDK on how to integrate with a USSD service.
Actions consist of
- Name of your choice, for example, “Send_Money”.
- Mobile networks/SIM cards that can run the USSD service.
- Root code, the shortcode used to dial the USSD service.
- The USSD menu steps. See below.
Your configuration should look something like this:
3. Install the SDK in your Flutter app
On your Hover dashboard, click “New app”. Give your app a name for your reference, and enter the package name exactly as it appears in AndroidManifest.xml. This can be found in android[APP_NAME]->app->src->main->. Follow the path to install the Hover SDK with Maven. Make sure to include your Hover API Token in AndroidManifest.xml.
Include your API token in your AndroidManifest.xml:
<application>
...
<meta-data
android:name="com.hover.ApiKey"
android:value="<YOUR_API_TOKEN>"/>
</application>
Add the latest Hover release to your app-level build.gradle dependencies:
repositories {
mavenCentral()
maven { url 'http://maven.usehover.com/releases' }
}dependencies {
implementation('com.hover:android-sdk:1.4.3') { transitive = true; }
}
4. Create the Flutter platform channel
The client and host sides (Flutter and Java) of the channel are connected through the channel name passed in the channel constructor. All channel names used in a single app must be unique. In our example, we are creating the channel name kikoba.co.tz/hover. For more information on a platform channel, check out the official Flutter docs.
class _sendMoneyState extends State<sendMoney> {
static const _hover = const MethodChannel('kikoba.co.tz/hover');5. Invoke method on platform channel
Invoke a method on the method channel, specifying the concrete method to call via the String identifier. In the code below, it is a function that sends action values to java code using a map that stores the values like in an array.
// Send Money call to Hover SDK java codeFuture<dynamic> sendMoney(
String phoneNumber, amount) async {
var sendMap = <String, dynamic>{
'phoneNumber': "phoneNumber",
'amount': amount,
};
// response waits for result from java codeString response = "";
try {
final String result = await _hover.invokeMethod('sendMoney',sendMap);
response = result;
} on PlatformException catch (e) {
response = "Failed to Invoke: '${e.message}'.";
}
return response;
}
Use the returned response to update the user interface state inside setState so you know if the action was successful or not.
setState(() {
_responseFromNativeCode = response;
});6. Create method implementation in Android using Java
In Android Studio open your Flutter app and select the Android folder. Open the file MainActivity.java.
Now we have to create a MethodChannel with the same name that we have created in your Flutter app.
public class MainActivity extends FlutterActivity {
private static final String CHANNEL = "kikoba.co.tz/hover";We have to create a MethodCallHandler in onCreate method to run actions. We can now get the Map (array) arguments from our Flutter sendMoney function.
7. Run your action
Your actions are downloaded and the SDK is initialized 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. To see an example of how to run an action click here.
import com.hover.sdk.api.Hover;
import com.hover.sdk.api.HoverParameters;
....
public class MainActivity extends FlutterActivity {@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
Hover.initialize(this); GeneratedPluginRegistrant.registerWith(this);
}
}
8. Make the request
Build your Hover request and launch the intent, specifying an action_id. The names and values for any variable action steps must be added as extras:
// Hover Action function
private void SendMoney(String PhoneNumber,String amount){
Intent i = new HoverParameters.Builder(this)
.request("action_id")
.extra("PhoneNumber", PhoneNumber)
.extra("Amount", amount)
.buildIntent();
startActivityForResult(i,0);
}@override
protected void onActivityResult (int requestCode, int resultCode, Intent data) {
if (requestCode == 0 && resultCode == Activity.RESULT_OK) {
String[] sessionTextArr = data.getStringArrayExtra("ussd_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();
}
}
new MethodChannel(getFlutterView(), CHANNEL).setMethodCallHandler(
new MethodChannel.MethodCallHandler() {
@Override
public void onMethodCall(MethodCall call, MethodChannel.Result result) {// Get arguments from flutter codefinal Map<String,Object> arguments = call.arguments();
String PhoneNumber = (String) arguments.get("phoneNumber");
String amount = (String) arguments.get("amount");
if (call.method.equals("sendMoney")) {SendMoney(PhoneNumber,amount)
String response = 'sent';
result.success(response);
}
}});
Complete Code Comparison
Android Native code
Flutter code
Result
Run the code on your Android device. Click on the button “Send Money” to send money as the action shows.
Here is the GitHub link to the Source Code.
Thanks for reading. If you enjoyed this article, feel free to hit 👏 that 👏 clap 👏 button 👏 and help others find it by sharing.
This article is based on our experience building with the Hover SDK on Flutter. If you are looking for a mobile app development team to build your solution, please contact us at devteam@lockwood.co.tz.
