Skip to content

Sample Application

A sample application is included in the package demonstrating how to integrate and use the DeviceAssure library in an Android application.

The sample application is written in Kotlin. The library's callback API is usable from Java too — see the integration guides for the same examples in both languages.

Prerequisites

  • JDK version 11 or 17
  • Android SDK with API level 21 or higher
  • Gradle (or use the included Gradle wrapper)
  • A valid DeviceAssure licence key
  • An Android device or emulator for testing

Setup Steps

1. Extract the Sample Application

Extract the contents of the DeviceAssure SDK zip archive to your desired location.

2. Configure Your Licence Key

The sample application requires your DeviceAssure licence key to function. This must be configured before building.

Locate the application.properties file in app/src/main/assets/application.properties and add your licence key:

licence-key=<LICENCE_KEY>

3. Configure Build Gradle with Licence Key

In order to download the DeviceAssure library from the DeviceAtlas Maven repository, you will also need to add your licence key to the build.gradle at the project level.

Edit the build.gradle file located in the root of the project and find the placeholder text:

licence = "Please enter your DeviceAssure licence key here"

Replace it with your actual licence key.

4. Build the Application

From the project root directory, build the application using Gradle:

# Using Gradle wrapper (recommended)
./gradlew assembleDebug

# Or for Windows
gradlew.bat assembleDebug

The APK will be generated in app/build/outputs/apk/debug/

5. Install on Device or Emulator

Option 1: Using Gradle

./gradlew installDebug

Option 2: Using ADB

# Install APK directly
adb install app/build/outputs/apk/debug/app-debug.apk

# Launch the app
adb shell am start -n com.deviceassure.android.example/.activity.MainActivity

Option 3: Using your IDE

Open the project in Android Studio and build and run the application using the IDE's build tools.

Granting Permissions

The sample app uses the Phone State permission (READ_PHONE_STATE) to collect the TAC for device validation on Android 9 (API 28) and below. It declares the permission in its own manifest and requests it at runtime, which is exactly what your application must do:

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

Important: READ_PHONE_STATE is not merged into your application by the library. Your application must declare it itself, and — because it is a dangerous permission on Android 6.0 (API 23) and higher — request it at runtime as well. Declaring it alone is not enough; requesting it without declaring it cannot succeed. See Add the Library for the full permission list and the upgrade impact.

Important: The DeviceAssure library checks permission status but does not request permissions itself. Host applications should request any required permissions before calling DeviceAssure.check() or DeviceAssure.getData(). Without the permission, validation still proceeds but the TAC is omitted, which may result in an incomplete validation.

Verifying the Setup

Once the app is running:

  • The app should successfully initialise the DeviceAssure library
  • Device data collection will begin automatically
  • Results will be displayed in the app's UI
  • Monitor logcat for detailed logs:
adb logcat | grep -i deviceassure

Troubleshooting

If you encounter errors, verify that:

  • Your licence key is correctly configured in both the build.gradle and application.properties files
  • READ_PHONE_STATE is declared in your application's manifest as well as granted on the device — a missing declaration looks the same as a denied permission
  • Your device/emulator meets the minimum API level requirement (API 21)
  • You have a stable internet connection for the application to communicate with the DeviceAssure service

See Also