Link Search Menu Expand Document Edit GitHub

Installation on Android

The HiveMQ MQTT Client library is supported on Android 4.4 (API level 19) and higher versions. This covers almost 100% of all Android devices.

To be able to use the HiveMQ MQTT Client on Android, configure your Android project with the following 5 steps:

  1. Use Android Gradle plugin 7.0 or newer.

  2. Grant your app the permission to use internet communication. You configure this permission in the AndroidManifest.xml that is typically located at $PROJECT_DIR/app/src/main/AndroidManifest.xml:

    <manifest>
        <uses-permission android:name="android.permission.INTERNET"/>
    </manifest>
    
  3. Configure your app’s build.gradle(.kts) file that is typically located at $PROJECT_DIR/app/build.gradle(.kts):

    • android {
          compileOptions {
              sourceCompatibility = JavaVersion.VERSION_1_8
              targetCompatibility = JavaVersion.VERSION_1_8
          }
          packagingOptions {
              resources {
                  excludes += ['META-INF/INDEX.LIST', 'META-INF/io.netty.versions.properties']
              }
          }
      }
      
    • android {
          compileOptions {
              sourceCompatibility = JavaVersion.VERSION_1_8
              targetCompatibility = JavaVersion.VERSION_1_8
          }
          packagingOptions {
              resources {
                  excludes += listOf("META-INF/INDEX.LIST", "META-INF/io.netty.versions.properties")
              }
          }
      }
      
  4. Add the following lines to your app’s proguard rules file that is typically located at $PROJECT_DIR/app/proguard-rules.pro:

    -keepclassmembernames class io.netty.** { *; }
    -keepclassmembers class org.jctools.** { *; }
    

    Please make sure that the proguard-rules.pro file is referenced in your app’s build.gradle(.kts) file:

    • android {
          buildTypes {
              release {
                  minifyEnabled = true
                  proguardFiles(getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro')
              }
          }
      }
      
    • android {
          buildTypes {
              release {
                  isMinifyEnabled = true
                  proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
              }
          }
      }
      
  5. You are done if your minimum supported Android API level is at least 24 (7.0 Nougat). If you want to support older Android versions, continue with the next step.

Android API Levels below 24

The above configuration is enough if your minimum supported Android API level is at least 24 (7.0 Nougat). Supporting older Android versions requires additional configuration as Android still lacks support for Java 8 APIs like java.util.concurrent.CompletableFuture on versions below 24.

You can use the Android RetroFix Gradle plugin to backport these APIs automatically. This plugin enables you to use the Java 8 APIs even if you have to support lower Android versions.

The following shows how to configure the Android RetroFix plugin.

  • Ensure that the google and gradlePluginPortal plugin repositories are configured in the settings.gradle file:

    pluginManagement {
        repositories {
            google()
            gradlePluginPortal()
        }
    }
    

    In your app’s build.gradle file, apply the Android RetroFix plugin and add the backport dependencies android-retrostreams and android-retrofuture:

    plugins {
        id('com.android.application')
        id('com.github.sgtsilvio.gradle.android-retrofix') version '0.5.0'
    }
    
    dependencies {
        implementation('com.hivemq:hivemq-mqtt-client:1.3.0')
    
        retrofix('net.sourceforge.streamsupport:android-retrostreams:1.7.4')
        retrofix('net.sourceforge.streamsupport:android-retrofuture:1.7.4')
    }
    
  • Ensure that the google and gradlePluginPortal plugin repositories are configured in the settings.gradle.kts file:

    pluginManagement {
        repositories {
            google()
            gradlePluginPortal()
        }
    }
    

    In your app’s build.gradle.kts file, apply the Android RetroFix plugin and add the backport dependencies android-retrostreams and android-retrofuture:

    plugins {
        id("com.android.application")
        id("com.github.sgtsilvio.gradle.android-retrofix") version "0.5.0"
    }
    
    dependencies {
        implementation("com.hivemq:hivemq-mqtt-client:1.3.0")
    
        retrofix("net.sourceforge.streamsupport:android-retrostreams:1.7.4")
        retrofix("net.sourceforge.streamsupport:android-retrofuture:1.7.4")
    }
    

When you increase the Android API level to 24+ in the future, you will only need to remove the plugin and the backport dependencies. You do not have to change your code.

Note

Android Studio will still display an error “Call requires API level 24 (current min is 21)”. This error is actually just a warning. Android Studio does not know that we backport the API, so it still thinks that the API can not be used with the minSdkVersion. You can build and run your app without any problems. If you want to get rid of the warning, just add @SuppressLint("NewApi") to the method or class where you use the API.