Integration Guide

Overview

Mist SDK will provide you the indoor bluedot experience using Mist’s 16 vBLE antenna array Access point. Using this SDK you will know where the user is and can provide the proximity-related notification using Mist patented vBeacon technology.

System requirements

• Deployment Target : 8.1
• Xcode : 8.1+

Permissions

• Location
• Internet
• Bluetooth

Include the following keys and values in your Info.plist.

 <key>NSAppTransportSecurity</key>
      <dict>
      <key>NSAllowsArbitraryLoads</key>
           <true/>
      </dict>
 <key>NSBluetoothPeripheralUsageDescription</key>
 <string>(Insert description)</string>
 <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
 <string>(Insert description)</string>

Getting Started

For integrating Mist core SDK you need to add the following pod dependency in your pod file

Mist core SDK without DR:

Method 1. Using CocoaPods

pod 'MistSDK'

Method 2. Manual

Simply manually include the .framework into the project and build & run for device only.

For more details please refer to one of the Sample Apps.

Mist core SDK with DR

For getting DR capability you have to use the SDKs from here with having ‘-dr’ name.

Method 1. Manual

Simply manually include the .framework into the project and build & run for device only.

Note: DR is not compliant with bitcode

Initializing Mist SDK

To initialize Mist SDK you need Organization Secret and Organization ID. To get these details you have to enroll the Device with the Invitation Secret.

Invitation Secret: you can create one from Mist portal at the following path: Organization -> Mobile SDK

[MSTOrgCredentialsManager enrollDeviceWithToken:@"(Mist Portal Org Token)" onComplete:^(NSDictionary *response, NSError *error) {
        NSLog(@"org_id %@", [response objectForKey:@"org_id"]);
        NSLog(@"secret %@", [response objectForKey:@"secret"]);
    }];

You will get the required detail in response dictionary. Store these strings in your local file in order to initialize MSTCentralManager.

name: response!["name”],
orgID: response!["org_id"],
orgSecret: response!["secret”]]

Use above required info for starting the SDK like following

self.mstCentralManager = [[MSTCentralManager alloc] initWithOrgID:orgID AndOrgSecret:orgSecret];
self.mstCentralManager.delegate = self;
[self.mstCentralManager setAppState:[[UIApplication sharedApplication] applicationState]];
[self.mstCentralManager startLocationUpdates]; // Start Location Updates

To stop receiving callbacks from Mist SDK use:

[self.mstCentralManager stopLocationUpdates];

Listening to Mist SDK callbacks

To get location information from Mist SDK you need to implement MSTCentralManagerDelegate callbacks in your application.

Getting Location Info

Location response is used to know the position of the user in that particular floorplan. For getting the coordinates of the user’s location we can use the following callback

-(void)mistManager: (MSTCentralManager *) manager didUpdateRelativeLocation: (MSTPoint *) relativeLocation inMaps: (NSArray *) maps at: (NSDate *) dateUpdated;

Returns updated location of the mobile client (as a point (X, Y) measured in meters from the map origin. You can get the map detail of your current map from maps[0].

MSTPoint x : relative x y : relative y hasMotion : is user in motion mstPointType : type MSTPointTypeLE, MSTPointTypeLast latency : latency in network heading : compass heading headingFlag : availability of compass heading

Getting Zone/vBLE Notifications

Mist SDK provide you proximity related and area related notification. Using this you can provide contextual information to you 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 these vBeacon where ever you want to place them in your floorplan and never have to worry about any battery or relocation problems.

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

You will get the vBeacon notification in following callback

-(void)mistManager:(MSTCentralManager *)manager didReceiveNotificationMessage:(NSDictionary *)payload;

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

Zone: Zone is like a big area or room for which you might want to get the notification to provide vicinity related information to your customer.

You will get the zone notification in following callback

-(void)mistManager:(MSTCentralManager *)manager didReceiveNotificationMessage:(NSDictionary *)payload;

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

DR Callbacks and Usage

Raw and Snapped DR Locations

-(void)mistManager:(MSTCentralManager *)manager didUpdateDRRelativeLocation:(NSDictionary *)drInfo inMaps:(NSArray *)maps at:(NSDate *)dateUpdated {

[Default performBlockOnMainThread:^{
    double sX = [[[drInfo objectForKey:@"Snapped"] objectForKey:@"X"] doubleValue];
    double sY = [[[drInfo objectForKey:@"Snapped"] objectForKey:@"Y"] doubleValue];
    double rX = [[[drInfo objectForKey:@"Raw"] objectForKey:@"X"] doubleValue];
    double rY = [[[drInfo objectForKey:@"Raw"] objectForKey:@"Y"] doubleValue];
    
    MSTPoint *rPoint = [[MSTPoint alloc] initWithX:rX andY:rY];
    MSTPoint *sPoint = [[MSTPoint alloc] initWithX:sX andY:sY];
    
    // using the dot
}];

}

DR heading in degrees

-(void)mistManager:(MSTCentralManager *)manager didUpdateDRHeading:(NSDictionary *)drInfo {

if (!self.isNavigating) {
    return;
}

[Default performBlockOnMainThread:^{
    NSNumber *mapCorrection = 0;
    double snappedHeading = [[[drInfo objectForKey:@"Snapped"] objectForKey:@"Heading"] doubleValue];
    double angle = -[mapCorrection floatValue]; // start off with a mapCorrect (fuzz factor);
    angle = angle + snappedHeading;
    
    // using the heading
}];

}

Other Callbacks

- (void) mistManager: (MSTCentralManager *) manager didUpdateMap: (MSTMap *) map at: (NSDate *) dateUpdated;

This method returns the updated map for the organization.

-(void)mistManager:(MSTCentralManager *)manager beaconsSent:(NSMutableArray *)beacons;

This method returns the NSMutableArray of beacons that were found in the region of the registered organization.

`- (void) mistManager:(MSTCentralManager *)manager didUpdatePressure: (double) pressure at: (NSDate *)dateUpdated;

This method returns the updated pressure when available to the app. The pressure will be a double measured in millibars.

-(void)mistManager:(MSTCentralManager *)manager didReceivedVirtualBeacons:(NSArray *)virtualBeacons;

This method returns an NSArray of virtual beacons associated with the current map of the Organization.

-(void)mistManager:(MSTCentralManager *)manager didReceivedClientInformation:(NSDictionary *)clientInformation;

This method returns clientName information

- (void) manager:(MSTCentralManager *)manager didErrorOccurWithType: (ErrorType) errorType andDetails: (NSString *) errorDetails;

This method notifies the host application about any errors encountered.

-(void)manager:(MSTCentralManager *) manager receivedLogMessage: (NSString *)message forCode:(MSTCentralManagerStatusCode)code;

This method notifies the host application about the status of the MSTCentralManager.

-(void)manager:(MSTCentralManager *) manager receivedVerboseLogMessage: (NSString *)message;

This method notifies the host application about the verbose state of the MSTCentralManager status.

Background Mode

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

Send-Time : sdk will work for the mentioned minutes and than 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 option to set the the Beacon scanning mode as well.

We can set state and paraters with something like below:

Background : with wakeup time and sleep time

[self.mstCentralManager wakeUpAppSetting:YES]; [self.mstCentralManager backgroundAppSetting:YES]; [self.mstCentralManager setSentTimeInBackgroundInMins:0.5 restTimeInBackgroundInMins:5];

without any rest time for SDK to be running long time

[self.mstCentralManager wakeUpAppSetting:YES]; [self.mstCentralManager backgroundAppSetting:YES]; [self.mstCentralManager sendWithoutRest];

App Wake Up

App wakeup is like waking up the app from 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 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 Apple CLBeaconRegion API using iBeacon

Maps Supported

• Mist map
• Jibestream
• Micello

Conversion from Mist coordinates to other maps Jibestream :

jibestreamX = (mistX *1000)/mmpp jibestreamY = (mistY *1000)/mmpp

Where mmpp is MilliMeterPerPixel which is specific to map and will be provided by jibestream itself