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.

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

Install the SDK

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

If you have issues with your app building and you are using Android X dependencies then we have an SDK variant for that: `0.17.0-androidx`

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 app. 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 should ideally happen 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.