Installation and Permissions

Create an App

A Hover “app” represents your Android application on Hover’s server. Each app has a unique API token, and a page where you can view information about users’ USSD sessions.

From your account dashboard click “New app”. The app name is for your reference only, it won't be visible to end users. Enter the exact package name of your app, and an optional https webhook URL where Hover will post a JSON representation of USSD session details. The package name must match your applicationId in AndroidManifest.xml.

Save your new app and note the API token for use in the next step.


As of April 17, 2019 the current version of the Hover SDK is 0.17.0

To include the SDK in your app, add Hover to your app-level build.gradle dependencies:

repositories {
	maven { url '' }

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

There can be various build errors and conflicts depending on which Android Studio and Gradle Build Tools version you are using and which Android SDK you target. We recommend Android Studio 2.3+. The Hover SDK also depends on some of the Android Support libraries. If there is a conflict when you build, you can try to not use the transitive dependencies (transitive = false or the exclude keyword in your build file) and include the support libraries version you wish to use. We cannot guarantee that doing this will not cause issues. In case you encounter an issue, please feel free to get in touch for help. You can list our dependencies by running ./gradlew app:dependencies.

Then include your API token as application level meta-data in your AndroidManifest.xml:


To find or create an API token visit your Hover dashboard and click on your app, or make a new one. The package name in our dashboard must match that of your actual app for the token to work.


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) {



This call downloads your configuration information from the Hover server. If the READ_PHONE_STATE permission has been granted it also reads the SIM cards the user has present and listens for changes to them.


  1. The Hover SDK requires the following permissions which you do not need to add as they are automatically merged by including the SDK in the dependencies:
<uses-permission android:name="android.permission.CALL_PHONE"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.RECEIVE_SMS"/>
<uses-permission android:name="android.permission.READ_SMS"/>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<uses-permission android:name="android.permission.BIND_ACCESSIBILITY_SERVICE"/>
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
<uses-permission android:name="android.permission.WAKE_LOCK"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

<uses-feature android:name="android.hardware.telephony"/>

As of Android Oreo the runtime permissions that must be granted by the user are READ_PHONE_STATE/CALL_PHONE and RECEIVE_SMS/READ_SMS. BIND_ACCESSIBILITY_SERVICE is a special permission which users must enable through a permission management screen in Android settings. Users can be can be sent to the screen from your app, but must toggle the setting themselves. SYSTEM_ALERT_WINDOW is also a special permission, but so long as your app is downloaded from the Play Store it will be granted without the user having to do anything. During development and if your app is sideloaded then the user will also have to grant this in the settings.

Hover includes an optional helper activity to get the permissions from the user. This helper is automatically used if you start a session without first getting the required permissions:

import com.hover.sdk.permissions.PermissionActivity;
startActivityForResult(new Intent(this, PermissionActivity.class), 0);

The result is RESULT_OKif ALL the permissions were granted. You may also use it to only get certain permissions by adding an extra to the intent, for example:

intent.putExtra(PermissionActivity.CMD, PermissionActivity.PHONE);

The table below shows the avaialble extras and the corresponding screens provided by PermissionActivity, including screens shown when a user denies the permission request. Most strings can be translated, see customization


Extra Permissions requested What users see
PermissionActivity.BASIC PermissionActivity.PHONE
PermissionActivity.ALL PermissionActivity.BASIC

In all versions of android except 6.0.1-6.0.4, the SYSTEM_ALERT_WINDOW permission is automatically granted to apps that request it, as long as the app is downloaded from the Play Store. The "Allow display over other apps" screen is only shown to users when the permission is not granted automatically.

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.