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, you have to 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>

As the HiveMQ MQTT Client uses Java 8 language features, you also have to specify the following in the app’s build.gradle file that is typically located at $PROJECT_DIR/app/build.gradle:

...
android {
    ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    packagingOptions {
        exclude 'META-INF/INDEX.LIST'
        exclude 'META-INF/io.netty.versions.properties'
    }
}
...

Additionally you have to set some proguard rules in the 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 the app’s build.gradle file:

...
android {
    ...
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
        ...
    }
    ...
}
...

Android API levels below 24

The above configuration is enough if your minimum supported Android API level is at least 24 (7.0 Nougat). Targeting lower Android versions requires additional configuration as Android still lacks support for Java 8 APIs like java.util.Optional, java.util.function.* and 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 in the app’s build.gradle file. You have to add the plugin and the two backport dependencies android-retrostreams and android-retrofuture:

buildscript {
    repositories {
        google()
        gradlePluginPortal()
    }
    dependencies {
        classpath 'gradle.plugin.com.github.sgtsilvio.gradle:android-retrofix:0.4.1'
    }
}

apply plugin: 'com.android.application'
apply plugin: 'com.github.sgtsilvio.gradle.android-retrofix'

...

dependencies {
    implementation 'com.hivemq:hivemq-mqtt-client:1.3.0'
    
    implementation 'net.sourceforge.streamsupport:android-retrostreams:1.7.4'
    implementation '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.