Package fi.bitwards.service

package fi.bitwards.service

Bitwards SDK for Android

Introduction

This page gives instructions how to setup your application project to use Bitwards SDK. The Bitwards SDK usage documentation can be found here: BitwardsService.

Bitwards SDK provides an easy to use APIs to interact with Bitwards resources. Bitwards SDK is intended to be used by 3rd parties who want to integrate Bitwards technologies to the application. The main functions of Bitwards SDK are as follows:

  • initialization of SDK and login/logout of end user,
  • synchronization of SDK database,
  • scanning for Bluetooth Low Energy (BLE) based resources,
  • accessing BLE and NFC based resources,
  • getting list of known resources to the end user, and user profile data, and
  • much more.

Please visit Bitwards website to learn more: https://bitwards.fi.

This page gives instructions how to setup your application project to use Bitwards SDK. The Bitwards SDK usage documentation can be found here: BitwardsService.

NOTE: All documentation assumes that the developer is familiar with Android development.

Android Bitwards SDK migration guide

This section list special considerations that a developer must address when upgrading to a newer version of the Android Bitwards SDK.

Upgrading to 3.5.0 or newer:

  • compileSdkVersion and targetSdkVersion are required to be 34 or higher.
  • If resource opening with NFC is required to be supported when application is not running or when it is in the background, the FOREGROUND_SERVICE_CONNECTED_DEVICE permission need to declared. This also means that a video demonstrating the resource opening over NFC while application is not running or it is in the background needs to be posted to Google Play's Developer console for review. This is not required.

Upgrading to 2.7.8 or newer: Starting from version 2.7.8 the following method signatures will change in order to accomodate for larger Account ID and Location ID values:

  • BitwardsAdminInfo.getAccountId() now returns long rather than int
  • BitwardsResource.getLocationId() now returns long rather than int
  • BitwardsResource.getAccountId() now returns long rather than int
  • BitwardsService.deleteUserAccount(List accountIDs, final ResultCallback callback) has changed to BitwardsService.deleteUserAccount(List accountIDs, final ResultCallback callback)

Upgrading to 2.7.0 or newer:

  • Starting from version 2.7.0 and newer versions of the Android Bitwards SDK support Android 12, i.e., Android SDK version 31 or 32. This means that the new Bluetooth permissions should be used when the application is running in Android 12 device and the targetSdkVersion is 31 or higher. Read more about using Bluetooth and permissions: [Important note about Bluetooth permissions].
  • compileSdkVersion and targetSdkVersion are required to be 31 or higher.

Bitwards SDK setup

The documentation in this section describes how to setup an Android Studio project to use Bitwards SDK for Android. You can download Android Studio from here: link.

Prerequisites

In order to use Bitwards SDK, the following need to be requested from Bitwards:

  • Developer account (username, password) for Bitwards private Maven repository.
  • Bitwards backend server URL.
  • If NFC based resources needs to be supported, then Host Card Emulation (HCE) configuration file needs to be obtained from Bitwards (BLE based resources are supported by default). Additionally, FOREGROUND_SERVICE_CONNECTED_DEVICE needs be declared if NTC based resources need to be opened while the application is not in the foreground (i.e., application is not running or is in the background). (Note that this also means that a video demonstrating the opening while application is not running beforehand needs to be uploaded to Google Play Developer Console.)
  • SDK license from Bitwards (this is not currently needed).

Setup project

This section describes the steps to setup an Android Studio project to use Bitwards SDK.

Add Bitwards private Maven repository to your project level build.gradle file: 


     buildscript {
         repositories {
             ...
             maven {
                 url 'https://developer.bitwards.io/repo'
                 credentials {
                     username bitwardsMavenUsername
                     password bitwardsMavenPassword
                 }
             }
         }
         ...
     }

     allprojects {
         repositories {
             ...
             maven {
                 url 'https://developer.bitwards.io/repo'
                 credentials {
                     username bitwardsMavenUsername
                     password bitwardsMavenPassword
                 }
             }
         }
         ...
     }

Username and password are needed to access Bitwards private Maven repository, specify them in your global gradle.properties file. Global gradle.properties files is typically in .gradle directory in your home directory. 


     bitwardsMavenUsername=<username>
     bitwardsMavenPassword=<password>

Add dependency to Bitwards SDK to build.gradle of the module that uses the Bitwards SDK, where the X.Y.Z is the version of the SDK. 


     implementation 'fi.bitwards:bitwards-sdk:X.Y.Z'

In addition, following should be considered:

  • minSdkVersion must be 21 or higher.
  • compileSdkVersion must be 34 or higher.
  • targetSdkVersion must be 34 or higher.

Set android:allowBackup to false in the application element of the AndroidManifest.xml.

Important note about Bluetooth and required permissions:

  • When using Android SDK version 30 or lower, i.e., the application is running in a device with Android 11 or older, the application must have ACCESS_FINE_LOCATION permission and the permission must be requested from the end user during runtime. To setup the application with location permissions, please refer to Request location permissions documentation for details.
  • When using Android SDK version 31 or higher, i.e., the application is running in a device with Android 12 or newer, and the application is running in a device having Android 12 or newer, the application must have BLUETOOTH_SCAN and BLUETOOTH_CONNECT permissions, and these permissions must be requested from the end user during runtime. To setup the application with Bluetooth permissions, please refer to Bluetooth permissions documentation for details.

The above cases must handled appropriately in the application in order to make sure that Bitwards SDK's Bluetooth functionality works properly. Especially, when the application is being updated from a version that was not using targetSdkVersion 31 or higher, or when the operating system in the device upgraded to Android 12. For more information about Bluetooth related permissions, please visit Bluetooth permission page at Android Developer website: [Bluetooth permissions].

Note: Bitwards SDK used to require that the device lock must be enabled. This requirement has been removed.

Configure project

Configure Bitwards SDK related parameters.

Add the following parameters to build.gradle of the module that is using Bitwards SDK:

  • bitwardsEnvironmentUrl: URL to the Bitwards backend server (mandatory)
  • bitwardsOauth2Url: URL to the OAuth2 endpoint for the Bitwards backend server (optional)

Adding a single configuration parameter is always a double operation. First, the value itself must be named and specified in the build.gradle file, and second, the value needs to be mapped to meta-data in AndroidManifest.xml.

Below is a simple example how to add the single configuration parameter in module's build.gradle file: 

     android {
         ...
         defaultConfig {
             ...
             manifestPlaceholders.bitwardsEnvironmentUrl = "<SERVER_URL>"
         }
         ...
     }
Add the following meta-data element for the configuration parameter under the application element to AndroidManifest.xml: 

     <manifest ...>
         ...
         <application ...>
             ...
             <meta-data
                 android:name="bitwards.environment.url"
                 android:value="${bitwardsEnvironmentUrl}" />
         </application>
     </manifest>
Below is another example with more flexibility: 

     android {
         ...
         buildTypes {
             debug {
                 ...
                 manifestPlaceholders.bitwardsEnvironmentUrl = "<SERVER_URL>"
                 manifestPlaceholders.bitwardsOauth2Url = "<OAUTH2_URL>"
             }
             release {
                 ...
                 manifestPlaceholders.bitwardsEnvironmentUrl = "<SERVER_URL>"
                 manifestPlaceholders.bitwardsOauth2Url = "<OAUTH2_URL>"
             }
         }
         ...
     }
Add the following meta-data elements for each configuration parameter under the application element to AndroidManifest.xml: 

     <manifest ...>
         ...
         <application ...>
             ...
             <meta-data
                 android:name="bitwards.environment.url"
                 android:value="${bitwardsEnvironmentUrl}" />
             <meta-data
                 android:name="bitwards.oauth2.url"
                 android:value="${bitwardsOauth2Url}" />
         </application>
     </manifest>

After all the above steps have been completed, the project is ready to use Bitwards SDK. Please continue with the BitwardsService class documentation to see how to use Bitwards SDK.

© Bitwards 2022