Master Lock Android Bluetooth SDK¶

Requirements¶

Minimum Android API 21 or higher

For devices running android 6 (API 23) and above, you must request and acquire Bluetooth Scanning permissions at runtime before calling MLBluetoothSDK.startScanning().

Prior to android 12, this permission is grouped together with ACCESS_FINE_LOCATION (or before API 29 ACCESS_COARSE_LOCATION is also acceptable).

ACCESS_FINE_LOCATION (Required for devices with API 29+)
ACCESS_COURSE_LOCATION (Required for devices < API 29)

If using targetSDKVersion 31, you must request the following permissions at runtime for devices running android 12 (API 31) or higher:

BLUETOOTH_SCAN (Required for devices with API 31+)
BLUETOOTH_CONNECT (Required for devices with API 31+)

Note Android 12 allows connecting to locks without ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION permission, however, if you do not also request these permissions no location data will be recorded for lock interactions.

-Add the following uses-permission elements to AndroidManifest.xml:

<uses-permission android:name="android.permission.BLUETOOTH_SCAN"
        android:usesPermissionFlags="neverForLocation"/> <!--if You don't have this additional flag, scan won't work on API 31 unless you also receive location permission -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> <!-- Only required to record location from encounters on API 31+, Required if device API below 31-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> <!-- Only required to record location from encounters on API 31+, Required if device API below 31-->
<uses-permission android:name="android.permission.BLUETOOTH"
                 android:maxSdkVersion="30" /> 
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"
                 android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.INTERNET" /> 
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

-Add the MLBluetoothsSDK Scanner Service to your AndroidManifest.xml in a service element

<service
    android:name="com.masterlock.mlbluetoothsdk.bluetoothscanner.Scanner"
    android:enabled="true"
    android:exported="false" />

Kotlin¶

The SDK contains kotlin code, and requires a minimum Kotlin version of 1.9.20 or higher.

Supporting Android below API 26¶

The SDK uses Java 8 code. If your app targets a minimum API below 26 (Pre Android 8) you will need to use Androidx Java 8 desugaring ** Note: with recent updates to Android Gradle Plugin, this requirement is enforced for all apps regardless of minimum SDK Version **

To enable desugaring, add the following to your app/build.gradle (must be in application module)

// add coreLibraryDesugaring attribute to your app/build.gradle file compileOptionsBlock
compileOptions {
        coreLibraryDesugaringEnabled true // Add this line

        sourceCompatibility JavaVersion.VERSION_1_8 // Or higher
        targetCompatibility JavaVersion.VERSION_1_8 // Or higher
}
// Add coreLibraryDesugaring dependency to app/build.gradle dependencies block
dependencies {

  coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.5' // or higher
  // other dependencies
}

This requirement will be removed in a future release of the SDK, when the minimum Android SDK is raised to 26 (Android 8.0) or higher.

Installation¶

Option 1: Gradle Maven GithubPackages Import¶

Once you have setup your project to use the MLBluetoothSDK Github Packages repository, add the following dependency to your app/build.gradle:

implementation 'com.masterlock:mlbluetoothsdk:4.5.0'

The demo project in this repository’s SampleApp folder uses this method

Adding the MLBluetoothSDK Github Packages Repository¶

For the github import to work, you will need to create a file called github.properties in project root with the following two lines (with your actual values substituted):

// save in your app's project root
user=YOUR_GITHUB_USERNAME 
key=YOUR_GITHUB_ACCESS_TOKEN // see below for how to generate a token

Generating an access token¶

Once logged into Github, click your avatar and select Settings
Select Developer Settings
Select Personal Access Tokens
Click Generate new token
Under Select Scopes Select the scope for read:packages
Click Generate

Adding the repository dependency to project root’s `build.gradle`¶

(see SampleApp for full example)

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            name = "GitHubPackages"

            url = uri("https://maven.pkg.github.com/TMLC-Connected-Products/MLBluetoothSDKAndroid")

            credentials {
                username = github_user() // see utility methods below
                password = github_key()
            }
        }
    }
}

Utility methods for github_user and github_key:¶

Add the following methods to read from github.properties

buildscript {

    def readGithubProperties = {

        def githubPropertiesFile = new File(project.rootDir, 'github.properties')
        def properties = new Properties()
        def stream
        try {
            stream = new FileInputStream(githubPropertiesFile)
            properties.load(stream)
        } catch (FileNotFoundException ignore) {
            println "github.properties not found in project root! This is
             required to import MLBluetoothSDK from Github package. See README.md"
        } finally {
            if (stream != null) stream.close()
        }
        return properties
    }

    ext.github_user = {
        def props = readGithubProperties()
        def user = props['user']
        return user
    }
    ext.github_key = {
        def props = readGithubProperties()
        def key = props['key']
        return key
    } 
    // (buildscript continues)

Option 2: Manual aar download¶

Instead of using GithubPackages, you can manually import the mlbluetoothsdk.aar provided in the aar folder of this repository, and add it as a project dependency.

Before doing a manual import in the Sample App, remove references to the Master Lock github packages import by removing line from SampleApp/build.gradle before you follow the steps for manual import:
```
implementation "com.masterlock:mlbluetoothsdk:$masterlock_version"
```

Also remove these references to the Master Lock Github Packages Maven the your root build.gradle

```groovy maven { name = “GitHubPackages”

      url = uri("https://maven.pkg.github.com/TMLC-Connected-Products/MLBluetoothSDKAndroid")

      credentials {
          username = github_user()
          password = github_key()
      }
  }

```

Copy the aar file to a subfolder of the app folder in the project, and add the file as a dependency.

For help with adding an aar file as a dependency, see Android Developer instructions for adding an AAR file as a dependency.

You will not automatically import Javadoc for the SDK if you use this method, and you will need to manually add the following dependencies to your app/build.gradle:

// begin include for sdk app
implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.1.0'
implementation 'com.google.code.gson:gson:2.11.0'

// retrofit
implementation 'com.squareup.retrofit2:retrofit:2.11.0'
implementation 'com.squareup.retrofit2:converter-gson:2.11.0'
implementation 'com.squareup.okhttp3:okhttp:4.9.3'

// Room
implementation 'androidx.room:room-runtime:2.4.3'
annotationProcessor 'androidx.room:room-compiler:2.4.3'

ProGuard or R8¶

Add the following keep rule to your proguard (or R8) configuration:

-keep class com.masterlock.mlbluetoothsdk.** { *; }

DexGuard¶

If using DexGuard, an additional ProGuard configuration file is available for each release after 1.8.3 in the format proguard-rules-vX.Y.Z.txt