IOS Integration

iOS Integration:

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.

Mist iOS Integration Prerequisite:

  • 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>

Integrate MistSDK:

Add the following pod dependency in your podfile
   Using CocoaPods
      $ pod 'MistSDK'
      Or
   Mist SDK Without DR
   Manually Adding .framework
      -Download 'MistSDK.framework' from SDK Releases
      -Add MistSDK.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
   Manually Adding '.framework'
      -Download 'MistSDK.framework' from SDK Releases folder with '-dr' in the name.
      -Add 'MistSDK.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.

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:

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

  2)  Use the response to initialize the MSTCentralManager

         NSLog(@"name %@", [response objectForKey:@"name"]);
         NSLog(@"org_id %@", [response objectForKey:@"org_id"]);
         NSLog(@"secret %@", [response objectForKey:@"secret"]);

  3)  Initialize MSTCentralManager:

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

  4)  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. Following callback returns updated location of the device as a point (X,Y) measured in meters from the map origin:

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

You can get the map detail of your current map from the MSTMap[0].

MSTPoint

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

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

Zones and 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 wherever you want to place them in your floorplan and never have to worry about any battery or relocation problems.

There are 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 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’ For more detail, 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 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

    }];

  }

Background Mode:

Mist SDK do have power optimized 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