Installation¶

To use the SDK, you have to integrate the library files in your app, then call the respective API.

Requirements¶

Android SDK¶

You need Android SDK 24 or later to compile the SDK.

However, note that some tests are not working on Android 24, due to the lack of support for the built-in WebView by modern websites. Android SDK 26 improves this a bit, but still does not support all metrics because it's from 2017. Android SDK 29 fixes this completely. Here's a compatibility matrix:

Test	SDK 24	SDK 26+	SDK 29+
`WebQualityTest`	❌	⚠️ Only TTFB, Document Ready Time and Page Load Time	✅ With First Contentful Paint and Largest Contentful Paint
`VideoQualityTest`	❌	❌	✅
`ExoPlayerQualityTest`	✅	✅	✅

Permissions¶

For conducting the actual tests, the SDK may need additional Android permissions. The default permissions are as follows; these are "normal" permissions that any app can request.

ACCESS_NETWORK_STATE: Required for retrieving network information.
ACCESS_WIFI_STATE: Required for retrieving WiFi information.
INTERNET: Required for measuring and sending data to the server.

The following are "dangerous" runtime permissions which will need to be queried from the user. Please check out the demo activity to see how to request the permissions.

ACCESS_COARSE_LOCATION: Optional, required for coarse geolocation tracing
ACCESS_FINE_LOCATION: Optional, required for detailed geolocation tracing
READ_PHONE_STATE: Optional, required for mobile network connection detail tracing

Details about what these permissions enable are shown in the measurement data section.

Download¶

Download the SDK from the links you have been sent, and extract them locally. The extracted folder should look like this:

.
├── LICENSE.md
├── README_SDK.md
├── docs/
├── qualitytestlib
│   └── quality-sdk/…
└── qualitytestlib_demo-$version-$customer.zip

The docs contain the JavaDoc API docs, which you may find useful. The qualitytestlib folder contains the actual SDK library files. In the qualitytestlib_demo-$version-$customer.zip file, you will find the demo app source code.

Integration into your Android project¶

The actual SDK is contained in the qualitytestlib/quality-sdk folder as a Maven package.

First, copy the quality-sdk folder to your app folder. For instance, your existing Android project may look like this:

.
├── app
│   ├── build.gradle
│   ├── proguard-rules.pro
│   └── src (your Android app source code)
├── build.gradle
├── gradle
│   └── wrapper
├── gradle.properties
├── gradlew
├── gradlew.bat
├── local.properties
└── settings.gradle

Place the quality-sdk folder into the app folder, so that it looks like this:

.
├── app
│   ├── build.gradle
│   ├── proguard-rules.pro
│   ├── src (your Android app source code)
│   └── quality-sdk (our SDK library)
...

Updating Gradle settings¶

Then modify settings.gradle in your root folder as follows, to add the SDK as a local Maven repository:

dependencyResolutionManagement {
    repositories {
        // quality-sdk local repo
        maven {
            url = "file://" + file('app/quality-sdk')
        }
        google()
        mavenCentral()
    }
}

Note

If you use Gradle < 6.8, you may need to add the following to your settings.gradle instead of the dependencyResolutionManagement block:

repositories{
    maven {
        url uri("${rootProject.projectDir}/app/quality-sdk")
    }
}

In your app's build.gradle, add the following to the dependencies block:

implementation 'com.aveq:qualitytestlib:$version'

Replace $version with the version number of the SDK that you were provided with, e.g. 1.8.1.

Required dependencies¶

The SDK requires androidx.media3:media3-exoplayer as a runtime dependency. Add it to your app's build.gradle:

implementation 'androidx.media3:media3-exoplayer:1.9.2'

This is needed because the SDK's ExoPlayerQualityTest class implements media3 interfaces. Without this dependency, release builds will fail with R8 "Missing classes" errors, or the app will crash with a VerifyError at runtime.

Note

Even if your app only uses VideoQualityTest or WebQualityTest, the media3 dependency is still required because the ExoPlayerQualityTest class is bundled in the SDK and must be resolvable by the Android runtime.

The com.aveq.qualitytestlib package should now be available to your application for importing.

Note

If you are getting an error about NoClassDefFoundError: Failed resolution of: Landroidx/security/crypto/MasterKey$Builder, please add this to your build.gradle's dependencies block:

implementation 'androidx.security:security-crypto:1.1.0-alpha06'

Once you have added the SDK to your project, you can start using it.

Backup and Restore Behavior¶

The SDK stores the device's registration credentials (UUID, among others) in an encrypted shared-preferences file named RegistrationPrefs.xml. The file is encrypted with a master key that lives in the Android Keystore. That master key is device-bound and is not included in Android Auto Backup or device-to-device transfer.

The SDK ships two backup-rules resources and references them from its library manifest:

surfmeter_backup_rules.xml for android:fullBackupContent (Android < 12)
surfmeter_data_extraction_rules.xml for android:dataExtractionRules (Android 12+)

Both files exclude RegistrationPrefs.xml from cloud backup and device-to-device transfer. When you build your app, the Android manifest merger picks these up automatically and you do not need to do anything.

Conflict if you already declare backup rules

If your AndroidManifest.xml already sets android:fullBackupContent or android:dataExtractionRules on its <application> element, the manifest merger will report a conflict with the SDK's values. You then have two options:

Reference the SDK rules from your own rules file (recommended). Copy the <exclude domain="sharedpref" path="RegistrationPrefs.xml" /> lines into your own backup-rules XML, so your file excludes both your data and the SDK's prefs. Keep your android:fullBackupContent / android:dataExtractionRules attributes pointing to your file.
Override the SDK attributes. In your application's <application> element, add tools:replace="android:fullBackupContent,android:dataExtractionRules" and ensure your own rules file excludes RegistrationPrefs.xml. Forgetting the exclude will reintroduce the duplicate-UUID problem on restore.

Updating the SDK¶

To update the SDK at a later stage, you can download the latest version from the AVEQ portal, and repeat the steps above. In particular, you need to:

Update the quality-sdk folder to the new SDK version
Update the version in the build.gradle file