Android Integration

Android Integration

Mist Android SDK provides a simple way to integrate Mist into your application. This document is a step by step guide to enable indoor location feature for developers. Follow the steps below to get started on Android integration. We also provide sample app which includes Mist SDK integration.

Mist Android SDK prerequisite:

  • Minimum SDK requirement is API 21 and above.
  • We recommend targeting SDK to API 27 and above. If you are targeting API 28 or above, you must include declaration following declaration within AndroidManifest in application tag:

<uses-library android:name=“org.apache.http.legacy” android:required=“false” />

  • Mobile SDK Key from Mist portal

To install Mist Android SDK in your application, add following dependency in build.gradle of your project:

implementation ‘com.mist:core-sdk:2.0.0’

Make sure you have jcenter() included in allprojects in build.gradle

allprojects {
      repositories {
            jcenter()
      }
 }

Provide required permissions in AndroidManifest.xml

<uses-permission android:name=“android.permission.INTERNET” />

<uses-permission android:name=android.permission.ACCESS_FINE_LOCATION” />

<uses-permission android:name=“android.permission.ACCESS_COARSE_LOCATION” />

<uses-permission android:name=“android.permission.ACCESS_GPS” />

<uses-permission android:name=“android.permission.BLUETOOTH” />

Initialize Mist Android SDK:

To initialize Mist SDK you need organization secret and organization id.

Obtain the invitation token from the Mist portal at the following path: Organization -> Mobile SDK. Use the token to obtain the org_id and secret via onReceivedSecret callback:

MSTOrgCredentialsManager mstOrgCredentialsManager = new 
MSTOrgCredentialsManager(getApplication(), new
MSTOrgCredentialsCallback(){
/**
 * @param orgName   Organization Name for the QR code
 * @param orgID     Organization ID for the QR code
 * @param sdkSecret SDK Secret token to be used to connect to Mist Cloud
 * @param error     Error, if the information was not obtainable
 */@Override
 public void onReceivedSecret(String orgName, String orgID, String sdkSecret, String error, String envType) {
     // Store orgID and sdkSecret to be used next to initialize MSTCentralManager.
 }
});

 

mstOrgCredentialsManager.enrollDeviceWithToken(invitation_secret);

Use the org_id and secret for starting the SDK and implements the CentralManagerIndoorOnlyListener callbacks:

MSTCentralManager mstCentralManager = new MSTCentralManager (application, orgID, orgSecret, mstCentralManagerIndoorOnlyListener);

Call start API of MSTCentralManager to start the SDK:
mstCentralManager.start();

Call stop on MSTCentralManager to stop receiving callbacks from Mist SDK:
mstCentralManager.stop();

Getting Location Info:

Location response is used to know the position of the user in that particular floorplan. To get location information from Mist SDK implement MSTCentralManagerIndoorOnlyListener callbacks in your application. Following callback returns updated location of the device as a point (X,Y) measured in meters from the map origin:

Relative coordinates based on top-left origin in meters (x, y)

onRelativeLocationUpdated(MSTPoint relativeLocation, MSTMap[] maps, Date dateUpdated)

The current map can be retrieved by maps[0].

relativeLocation object contains the following user information:

  • x, y: user location
  • hasMotion: is the user in motion ,
  • mstPointType: type Cloud,
  • latency: latency in the network,
  • heading: compass heading,
  • headingFlag: availability of compass heading

Lat/Long coordinate

onDRRelativeLocationUpdated(JSONObject drInfo, MSTMap mstMap, Date date)

The latitude and longitude coordinates can be found inside the JSONObject.

    {
       "Raw": {
          "Lat": 36.562600,
          "Lon": -118.957490,
       },
       "Snapped": {
          "Lat": 36.562600,
          "Lon": -118.957490,
       }
    }

For more details, you can see the implementation in the sample app here

Zone and VBLE Notification:

Mist SDK provides you proximity related and area related notification. Using this you can provide contextual information to your user based on the proximity and area they are in. vBeacon: vBeacon are Mist patented technology using which you can provide proximity-related information and the good thing is you can move this vBeacon where ever you want to place them in your floorplan and never have to worry about any battery or relocation problems.

There’re two types of notifications:

  • zones
  • virtual beacon (vbeacon)

You can use ranging API for vBeacon similar to what you can do for real beacons.

You will get the vBeacon notification in the following callback

onNotificationReceived(Date dateReceived, String message)

The type of message let you know whether that is for vBeacon or zone, for vBeacon its ‘zone-event-vb

For more details, you can see the implementation in the sample app Notification Use-case App

Zone: Zone is a custom area defined on the Mist portal to get the notification to provide vicinity related information to your customer.

You will get the zone notification in the following callback

onNotificationReceived(Date dateReceived, String message)

The type of message let you know whether that is for vBeacon or zone, for zone its ‘zones-events’

For more details, you can see the implementation in the sample app Notification Use-case App

Background Mode:

Mist SDK do have power optimised way of working in the background for the use case of analytics. You can specify Send-Time and Rest-Time for SDK to work in the background.

Send-Time: SDK will work for the mentioned minutes and then will rest for the specified minutes. Rest-Time: SDK will stop collecting data and sending it to cloud for the specified number of minutes.

You also have the option to set the Beacon scanning mode as well.

We can set state and paraters with something like below:

Background :

mstCentralManager.setAppMode(new AppModeParams(AppMode.BACKGROUND,BatteryUsage.LOW_BATTERY_USAGE_LOW_ACCURACY,mShouldWorkInBackground,mSendDuration,mRestDuration))

Foreground:

mstCentralManager.setAppMode(new AppModeParams(AppMode.FOREGROUND,BatteryUsage.HIGH_BATTERY_USAGE_HIGH_ACCURACY,mShouldWorkInBackground,mSendDuration,mRestDuration))

For more detail, you can see the implementation in the sample app here

App Wake Up:

App wakeup is like waking up the app from the killed state when its get in range of register beacon. This is more of app side feature and nothing to do with SDK. You can, however, start the SDK in the background when you receive the callback in killed state and use it for analytics purpose rather the navigation/location.

For wakeup, we are using the Google Nearby API

We have a sample for the wake up which can be found here