-
Notifications
You must be signed in to change notification settings - Fork 5
Home
- Introduction
- System requirements
- Installation
- Concepts
- Integration steps (For SDK 3.x.x onwards)
- Integration steps (For Older SDK)
- Methods Available in IndoorLocationManager (For SDK 3.x.x onwards)
- Methods Available in IndoorLocationManager (For older SDK)
- FAQs
The Indoor Location Service and Outdoor Location Service differ significantly. This is because most Outdoor Location Services rely on GPS and other Global Navigation Satellite Systems (GNSS), which are obstructed by buildings' roofs and walls. Consequently, GPS is not a suitable solution for our case study in terms of accuracy. To attain indoor location services, we utilize MistSDK, which employs BLE technology for indoor positioning, wayfinding systems, proximity notification, and other features.
MistSDKDR - Mist Software Development Kit Dead Reckoning.
By leveraging Mist's 16 vBLE antenna array Access point, Mist SDK facilitates an indoor blue dot experience. With this SDK, you will have the ability to determine the user's location and deliver proximity-based notifications utilizing Mist's patented vBeacon technology.
Why the word Dead Reckoning?
MistSDK employs a dead reckoning technique to compute the user's current location. It does so by using their previous location and extrapolating it based on known and estimated speeds over elapsed time. This implies that DR is devised to make use of all available location data that a user had when connected and continues to function as though the client is connected, even when facing disconnections or interruptions in the connection.
Important features offered by our Mist SDK:
- Indoor Location,
- Providing the coordinates in the map for your app to draw the blue dot location of the device.
- Virtual Beacon Notification.
- A beacon, which is not physically present, but a virtual one. A virtual beacon that is added on the web portal and known by your app through the SDK. It provides notifications when the device is near the location of the virtual beacon.
- Virtual Zone notification.
- Zones are defined on the Mist portal as areas within a map. The SDK provides notifications on going into a zone.
- Wayfinding Path Information
- Wayfinding paths are defined on the Mist portal. The SDK provides the coordinate information from the current blue dot to the nearest point in the paths, through the shortest path to a given coordinate in the same map. This information can be used by the app to draw the shortest route a user can take to a destination.
-
Hardware Requirements:
- Mist Access Point with vBLE support (AP) - very important - Mist uses an AP with 16 vBLE Antennas to get the position of device in the floor.
- iOS Mobile Device: Since the iOS Simulator doesn’t have Bluetooth support, it will not work properly. We need a physical device with BLE support for application testing and development with the SDK.
-
Software Requirements:
- Xcode: 12 or later.
- iOS deployment Target: 14.0 or later.
- Access to Mist Account
- Mobile SDK secret
Follow the steps to integrate Cocoa-Pod in the Xcode project or [Refer CocoaPods Getting Started guide]:
-
Open the terminal and change directory to your project folder, and create and initialize Podfile using the commands below.
$ cd ./project_folder_path
- If pod not installed, run the below command
$ sudo gem install cocoapods
- If pod not installed, run the below command
-
Initilize project
$pod init
- this will create a folder and required files in the project directory
-
Open the Podfile created and add the package to the target section in the pod file.
source 'https://github.com/CocoaPods/Specs.git' source 'https://github.com/mistsys/mist-vble-ios-sdk.git' platform :ios, '14.0' target 'MyApp' do #Pods for MyApp pod 'MistSDK', '3.0.0' end
-
Go back to the terminal and Run the command in your project directory to complete the SDK installation with Cocoapods.
$pod install
-
Open <<projectname>>.xcworkspace and build. This way, you can get the benefit of the pod and its installed packages.
-
Add import MistSDK in swift OR #import <MistSDK/MistSDK.h> in Objective c to get started.
Note: Incase Mist SDK DR version is not compliant with bitcode. You need to set BitCode -> Enable = No in the build setting of your XCode Project.
Once you have your Swift package set up, adding MistSDK as a dependency is as easy as adding it to the dependencies value of your Package.swift.
dependencies: [ .package(url: "https://github.com/mistsys/mist-vble-ios-sdk.git", from: "3.0.0") ]
- For the latest SDK version, download the MistSDK.framework
- Drag and drop the MistSDK.framework in the project file.
- In your Xcode project file add MistSDK.framework to Targets > General > Framework, Libraries and Embedded contents > select Embed and Sign.
- Add `import MistSDK in swift OR #import <MistSDK/MistSDK.h> in Objective c .
There are some of the important steps to be configured initially to get started with an SDK
- App Permissions.
- Mobile SDK token.
- Floor Plan - (MistMap)
- Position Access Points (APs) in the floor plan
And the following are necessary on the need basis,
- Way-finding Paths
- Virtual Beacons
- Zones
- App Wakeup
To proceed, our SDK gathers certain sensitive information, which is deemed necessary. For instance, the SDK leverages Bluetooth to scan for BLE devices and use motion sensor data. Therefore, it is crucial to provide sufficient permissions to begin. These permissions include:
- Bluetooth Permission:
- Privacy - Bluetooth Always Usage Description.
- Bluetooth access required to scan Mist AP Beacon.
- Privacy - Bluetooth Always Usage Description.
- Motion Sensor Permission:
- Privacy - Motion Usage Description
- Motion sensor data is used to provide a more accurate indoor location estimate.
- Privacy - Motion Usage Description
To provide those permissions open info.plist in a source code mode and add the following snippet.
<key>NSBluetoothAlwaysUsageDescription</key>
<string> Bluetooth access required to scan Mist AP Beacon. </string>
<key>NSMotionUsageDescription</key>
<string> Motion sensor data is used to provide a more accurate indoor location estimate. </string>
- Location Permission:
- Privacy - Location When in Use Usage Authorization.
- To listen for iBeacon and other location services in foreground.
- Privacy - Location Always Usage Authorization.
- To listen for iBeacon and other location services even in background.
- Privacy - Location When in Use Usage Authorization.
- Bluetooth Permission:
- Privacy - Bluetooth Peripheral Usage Description.
- Bluetooth access required to scan Mist AP Beacon.
- Privacy - Bluetooth Peripheral Usage Description.
- Motion Sensor Permission:
- Privacy - Motion Usage Description.
- Motion sensor data is used to provide a more accurate indoor location estimate.
- Privacy - Motion Usage Description.
To provide those permissions open info.plist in a source code mode and add the following snippet.
<key>NSLocationWhenInUseUsageDescription</key>
<string> Mist wants to access the Location services </string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string> Mist wants to access the Location services in background </string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string> Bluetooth access required to scan Mist AP Beacon. </string>
<key> NSMotionUsageDescription </key>
<string> Motion sensor data is used to provide a more accurate indoor location estimate. </string>
Now we are done with adding permissions. The next step is to create a Mobile SDK token to enroll the device in the Mist Cloud.
In-order to run the MistSDK in background, you have to enable below capabilities in the project under 'Signing & Capabilities'
-
Background Modes
- Uses Bluetooth LE accessory
- Background processing
![Screenshot 2024-06-04 at 5 24 30 PM](https://private-user-images.githubusercontent.com/117802355/336437438-9db025a9-0273-42ee-a985-4e6832394540.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjM2ODQyOTgsIm5iZiI6MTcyMzY4Mzk5OCwicGF0aCI6Ii8xMTc4MDIzNTUvMzM2NDM3NDM4LTlkYjAyNWE5LTAyNzMtNDJlZS1hOTg1LTRlNjgzMjM5NDU0MC5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjQwODE1JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI0MDgxNVQwMTA2MzhaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT03OTIwMTFjZTQyMzA1MWJjNjE4ZmY4NDQ2ZGQ2Mzc1MGU0ODRiNTdjYmNmZTM3MGU5ODk4YzYxYzY1M2VjZTBiJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZhY3Rvcl9pZD0wJmtleV9pZD0wJnJlcG9faWQ9MCJ9.sz5Aqshil6YOY0Jd_7ewq3Iy0bLmSGxo1tzAZfykZjo)
Mobile SDK token is the secret key which can be created from the Mist portal. This key authenticates an SDK instance and identifies that it belongs to a specific organization in the Mist cloud.
Why is this Mobile SDK token for?:
Mist provides the solution for indoor location services. With the Mobile SDK token we ensure that SDK instances are only used for specific organizations in the Mist cloud.
Token Creation Steps:
- To create a Mobile SDK token, you should have registered with the Mist portal
- Go to Organization --> Mobile SDK as,
![Screenshot 2023-04-15 at 8 26 15 PM](https://user-images.githubusercontent.com/122332297/232232499-aaa34657-c2e0-4a86-ba3c-75faa2b15c40.png)
- Create a new invitation. It will ask for the organization name and once you give the name and hit save, you will get your token, Refer the image for better understanding.
![Screenshot 2023-04-15 at 8 26 15 PM](https://user-images.githubusercontent.com/122332297/232232538-4dcb2445-b54c-47ec-b8b1-8f2bbaddf16a.png)
- Our goal is to provide indoor location services. This requires a map, specifically a floor plan.
- In the Mist portal, we can upload the floor plans. We call these the MistMaps.
Maps Supported
- Mist Map: Map Type (jpeg, png, gif)
- Micello
- Jibestream
Conversion from Mist Coordinates to other maps Jibestream:
jibestreamX = (mistX1000)/mmpp
jibestreamY = (mistY1000)/mmpp
Where mmpp is MilliMeterPerPixel which is specific to map and will be provided by jibestream itself
How to add the Floor Plan in Mist Portal:
- Go to Location--> Live View – here it will show all of the existing floorplans, if there are none then it will tell you to add the floorplan with a button.
![Screenshot 2023-04-15 at 8 26 32 PM](https://user-images.githubusercontent.com/122332297/232232555-c68cd442-fd37-4d93-8a4f-0399a120972d.png)
- To add a floor plan, click on the "Add FloorPlan" or "Import FloorPlan" button based on your requirements. You will be prompted to provide a name for the floor. Once you have entered the name, press "Enter", and you will be asked to upload the floor plan image. Simply drag and drop the image into the designated area and click on the "Upload" button.
![Screenshot 2023-04-15 at 8 26 39 PM](https://user-images.githubusercontent.com/122332297/232232572-84a5fe71-919d-437b-8881-5ec656be39fa.png)
- The final step in configuring the floor plan is to add the PPM (Pixels per meter) value. This indicates the distance in meters that each pixel on the floor plan represents.
Positioning the AP in the Mist Portal exactly as it is in the real world is crucial. Failing to do so will result in an inaccurate Mist Point.
How to position APs in the floor plan in the Mist Portal
Go to Location -> Live View -> Setup Floorplan, from here you can see the list of APs that are claimed to that site and move them around to whereever you want.
This is one of the examples of floor plan with AP installed.
![Screenshot 2023-04-15 at 8 26 46 PM](https://user-images.githubusercontent.com/122332297/232232592-96ab55a3-d677-4585-8a27-bdc85eb06344.png)
Wayfinding paths can be created to help the location estimate gravitate towards the paths drawn out. The wayfinding paths can also be used by your app to draw the shortest route for wayfinding. To generate the path, we can use the Mist portal and define the route directly on the map. For that
- Go to Location -> Live View -> Choose the floor plan
- Click the Wayfinding paths button
![Screenshot 2023-04-15 at 8 26 50 PM](https://user-images.githubusercontent.com/122332297/232232602-4307212f-6ede-48dc-b529-7e3fddd932db.png)
- You will see the Following options
![Screenshot 2023-04-15 at 8 26 54 PM](https://user-images.githubusercontent.com/122332297/232232612-16ebbbc8-3fb5-49ee-9fa3-e43119b56c0c.png)
- Draw paths in areas where there will be people walking and moving through; be sure to draw paths in every area where you intend to utilize the SDK clients. Make sure that all path segments are connected to each other.
![Screenshot 2023-04-15 at 8 26 59 PM](https://user-images.githubusercontent.com/122332297/232232619-f0b3a1b5-9b9a-45bd-8b50-2547c6395116.png)
for more [https://www.mist.com/documentation/adding-wayfinding-paths/]
vBeacons are a Mist-patented technology that enables the provision of proximity-related information. The advantage of vBeacons is that they can be placed anywhere on the floor plan without concerns about battery life or relocation issues. Similar to real beacons, ranging APIs can be used for vBeacons. It’s important to note that these do not act as stand-ins for real beacons and are only for proximity-related notification information. Meaning that placing these vBeacons on your floorplan will not help increase accuracy.
To add the vBeacons,
- Go to Location->Live View-> select the floor plan->click the Beacons and Zones
![Screenshot 2023-04-15 at 8 30 28 PM](https://user-images.githubusercontent.com/122332297/232232669-7b02012f-0cbc-4774-9fa5-08f1109508cc.png)
- Now the user can create and move the vBeacon wherever he wants. All the Green circles are vBeacons
![Screenshot 2023-04-15 at 8 27 05 PM](https://user-images.githubusercontent.com/122332297/232232694-1e353cfa-7e93-4bea-b953-15e40cad7a46.png)
- Furthermore, we have the flexibility to customize the beacon according to your requirements. If you wish to remove a beacon, you can choose the "Remove" option, or if you want to make any modifications to the beacon, you can select the "Edit" option.
![Screenshot 2023-04-15 at 8 27 09 PM](https://user-images.githubusercontent.com/122332297/232232706-fa801797-5392-4e7d-bd4c-6ee8c0058bf4.png)
- If you intend to edit a beacon, you should fill the necessary details in the edit popup and save the changes. On the other hand, if you wish to delete a beacon, simply click the "Delete" button.
![Screenshot 2023-04-15 at 8 27 13 PM](https://user-images.githubusercontent.com/122332297/232232711-5f4103b5-d0e6-4829-a782-0f80942be72d.png)
- A zone is a customized area defined on the Mist map that enables notifications to be sent to provide location-specific information to customers. We can send notifications when a user enters the specified zone in the Mist portal.
- To add zones, Go to Location->Live View-> select the floor plan->click the Beacons and Zones.
- And click add location Zone and drag the area on the floor plan to create the zone.
- Refer the highlighted area in the image for the zone.
![Screenshot 2023-04-15 at 8 27 18 PM](https://user-images.githubusercontent.com/122332297/232232716-94a229c9-3229-4747-ac6e-afe83d879977.png)
As same as virtual beacons, we have options to edit and delete the zones.
App wakeup refers to the act of bringing the app back to an active state when it enters the range of a registered beacon. This feature is primarily related to the app itself and not the Mist SDK. However, you can initiate the SDK in the background when you receive the callback in the killed state and utilize it for analytics purposes instead of navigation or location.
For wakeup we are using the Apple CLBeaconRegion API using iBeacon in iOS. Apple had a method didEnterRegion and didExitRegion delegate methods in Core Location package to handle such a scenario better. For Android we are using ALTBeacon to achieve AppWakeup.
-
Import MistSDK
Swift:
import MistSDK
-
Create and initialize the SDK with the Mobile SDK token that you get through the token creation process.
Swift:
let sdkConfig = Mist.Configuration(sdkToken: <Mobile SDK Token>, logLevel: .debug, enableLog: true) let mistManager = IndoorLocationManager.shared
To disable debug log:
let sdkConfig = Mist.Configuration.default(sdkToken: <Mobile SDK Token>)
-
Start the location SDK.
-
Assign an IndoorLocationDelegate.
Swift:
mistManager.start(with: sdkConfig, delegate: self)
-
Once we have done all the steps, we will be able to get all the required parameters in the respective delegate methods.
didReceive()
method needs to be overridden to handle all MistSDK callbacks using events withcase
func didReceive(event: Mist.Event) { switch event { case .callbackName(): // handle callbacks here
The following are the callbacks in detail:
-
To get client information when enrolment sucessfull or client name has been updated.
case onReceivedClientInfo(MistSDK.Mist.Client)
Mist.Client
Property Datatype Description name String? The name of the client. orgId String? The organization ID associated with the client. orgName String? The organization name associated with the client. deviceId String? The device ID of the client. -
To receive all sites maps
case onReceivedAllMaps([MistSDK.Mist.Map])
Mist.Map
Property Datatype Description id String? The ID of the map. name String? The name of the map. siteId String? The site ID associated with the map. orgId String? The organization ID associated with the map. type String? The type of the map. locked Bool? Indicates whether the map is locked. originX Double? The x-coordinate origin of the map. originY Double? The y-coordinate origin of the map. width Double? The width of the map. height Double? The height of the map. ppm Double? The pixels per meter ratio of the map. widthM Double? The width of the map in meters. heightM Double? The height of the map in meters. createdTime Int64? The timestamp of when the map was created. modifiedTime Int64? The timestamp of when the map was last modified. url String? The URL of the map. thumbnailUrl String? The URL of the map thumbnail. wayFindingPath MistSDK.Mist.Path? The path data for wayfinding on the map. wallPath MistSDK.Mist.Path? The path data for walls on the map. siteSurveyPath [MistSDK.Mist.Path]? The path data for site survey on the map. wayfinding MistSDK.Mist.Wayfinding? Information about wayfinding on the map. latlngBr MistSDK.Mist.LatlngBr? The bottom-right latitude and longitude coordinates of the map. latlngTl MistSDK.Mist.LatlngTl? The top-left latitude and longitude coordinates of the map. drInternal MistSDK.Mist.DRInternal? Internal data related to DR geoRefParamsv2 MistSDK.Mist.GeoRefParamsV2? Georeferencing parameters for the map. orientation Int? The orientation of the map. occupancyLimit Int64? The occupancy limit of the map. intendedCoverageAreas String : String? The intended coverage areas of the map. -
To get current map data
case onMapUpdate(MistSDK.Mist.Map)
-
To get all Virtual Beacons for the current map
case onUpdateVirtualBeaconList([MistSDK.Mist.VirtualBeacon])
Mist.VirtualBeacon
Property Datatype Description orgId String? The organization ID associated with the virtual beacon. siteId String? The site ID associated with the virtual beacon. mapId String? The map ID associated with the virtual beacon. vbId String? The ID of the virtual beacon. vbUUID String? The UUID of the virtual beacon. vbMajor Int? The major value of the virtual beacon. vbMinor Int? The minor value of the virtual beacon. power Int? The power of the virtual beacon. powerMode String? The power mode of the virtual beacon. message String? A message associated with the virtual beacon. createdTime Int64? The timestamp of when the virtual beacon was created. modifiedTime Int64? The timestamp of when the virtual beacon was last modified. tagId String? The tag ID associated with the virtual beacon. name String? The name of the virtual beacon. url String? The URL associated with the virtual beacon. position MistSDK.VBeaconPosition? The position information of the virtual beacon. additionalInfo MistSDK.Mist.AdditionalInfo? Additional information about the virtual beacon. -
To get current mist point
case onRelativeLocationUpdate(MistSDK.Mist.Point)
Mist.Point
Property Datatype Description map MistSDK.Mist.Map The map associated with the point. x Double The x-coordinate of the point. y Double The y-coordinate of the point. lat Double The latitude of the point. lon Double The longitude of the point. latency Int64 The latency associated with the point. heading Double The heading (direction) of the point. speed Double The speed associated with the point. hasMotion Bool Indicates whether the point has motion. -
To receive zone notification onEnter
case onEnterZone(MistSDK.Mist.Zone)
-
To receive zone notification onExit
case onExitZone(MistSDK.Mist.Zone)
Mist.Zone
Property Datatype Description name String? The name of the zone. timestamp String? The timestamp associated with the zone. origin String? The origin of the zone. level Int? The level of the zone. recipient String? The recipient of the zone. recipientId String? The ID of the recipient of the zone. userId String? The ID of the user associated with the zone. zoneId String? The ID of the zone. mapId String? The ID of the map associated with the zone. siteId String? The site ID associated with the zone. orgId String? The organization ID associated with the zone. clientType String? The type of client associated with the zone. isRandom Bool? Indicates if the zone is random. zonePosition MistSDK.ZonePosition? The position information of the zone. trigger MistSDK.Mist.ZoneTrigger? The trigger associated with the zone. time String? The time associated with the zone. sinceTime String? The since time associated with the zone. timeEpoch Int64? The epoch time associated with the zone. sinceTimeEpoch Int64? The epoch time since associated with the zone. sessionId String? The session ID associated with the zone. duration Int64? The duration associated with the zone. -
To know when the client is in the range of a VirtualBeacon
case onRangeVirtualBeacon(MistSDK.Mist.VirtualBeacon)
-
-
And finally we call the stop method to stop the sdk:
Swift:
mistManager.stop()
- start(with:delegate:)
- stop()
- getWayfindingPath(to:)
- saveClient(name:)
- getClientInformation()
- clientUUID
- This method will start the MistSDK.
- Usage:
- Swift:
mistManager.start(with: sdkConfig, delegate: self)
- This method will stop MistSDK.
- It doesn’t take any arguments and won’t return anything.
- Usage:
- Swift:
mistManager.stop()
- This method will return a list of nodes to be traversed when we want to draw the path towards the destination.
- This is also the instance method, so invocation should be via instance of class only.
- We should pass the destination - (an object of type MistSDK.MistPosition) as an argument.
- It will return a sequence of nodes to be traversed in an array format of type [MistSDK.Mist.Node].
- Usage:
- Swift:
let nodes = mistManager.getWayfindingPath(to: MistPosition.init(x: 10, y: 10))
- This method saves the client information to the mist server - (client is the current user in the session).
- The user can send his name to server via this method, SDK will invoke the API update the username to server. After this process we can easily find the user in the map via this name.
- It takes the username as a parameter
- Usage:
- Swift:
mistManager.saveClient(name: "<username>")
- It fetches the client information from the server.
- To Get the Client Information subscribe to didReceive(event: Mist.event) callback and use - case onReceivedClientInfo(let client)
- Usage:
- Swift:
mistManager.getClientInformation()
- This variable will give us the current Mist User UUID from the server.
- Swift:
let mistUUID = mistManager.clientUUID
-
Import MistSDK
Swift:
import MistSDK
Obj-c:
#import <MistSDK/MistSDK.h>
-
Create and initialize the SDK with the Mobile SDK token that you get through the token creation process.
Swift:
let indoorLocationManager = IndoorLocationManager.sharedInstance(MistConstants.mistAccessToken)
Obj-c:
self.indoorLocationManager = [IndoorLocationManager sharedInstance: @"<AccessToken>"];
-
Start the location SDK.
-
Assign an IndoorLocationDelegate.
Swift:
indoorLocationManager?.start (with: self)
Obj-c:
[_indoorLocationManager startWithIndoorLocationDelegate:self];
-
Once we have done all the steps, we will be able to get all the required parameters in the respective delegate methods.
-
There are roughly around five delegates available, and they are
- IndoorLocationDelegate.
- ZonesDelegate.
- MapsListDelegate.
- VirtualBeaconsDelegate.
- ClientInformationDelegate.
Required methods to be overridden.
-
func didUpdateRelativeLocation(_ relativeLocation: MistPoint!) -> Void
-
func didReceivedOrgInfo(withTokenName tokenName: String!, andOrgID orgID: String!) -> Void
didUpdateRelativeLocation
This delegate method is a part of IndoorLocationDelegate which is very important to be overridden. So, the class whichever is trying to confirm IndoorLocationDelegate should override this method.
The main purpose of this method is to provide relativeLocation of type MistPoint, which gives us detailed information about the current location of the device.
MistPoint
Property | Datatype | What it infers |
---|---|---|
x | double | It is a spatial coordinate x |
y | double | It is a spatial coordinate y. |
lat | NSNumber | It mentions the current latitude of the device. |
lon | NSNumber | It mentions the current longitude of the device. |
hasMotion | bool | It tells us whether the device has a motion or not. |
latency | double | It provides the delay in getting the data. |
heading | NSNumber | It provides direction towards AP in degrees. |
map | MistMap | It provides all the information related to MistMap. |
Example:
Swift:
func didUpdateRelativeLocation(_ relativeLocation: MistPoint!){
self.mistPoint = relativeLocation
}
Obj-c:
(void)didUpdateRelativeLocation:(MistPoint *)relativeLocation {
_mistPoint = relativeLocation;
}
didUpdate(_ map: MistMap).
It will be called once the map gets updated – which means that, if the device moves from one floor to another floor, there will be a change in the floor map. In such a scenario this callback will be triggered with an updated floor map. It is also the required delegate method and should be overridden without fail.
MistMap
Property | Datatype | What it infers |
---|---|---|
name | String | It is the name of the map (Floor plan). |
Width, height | long | Width and height of the map. |
mapID | String | Unique identifier for the map. |
siteID | String | Site is a venue where our MistSDK is running – and this id refers to the unique identifier for the site. |
orgID | String | Organization ID. |
url | String | This is the url which contains the actual map. |
wayfindingPath | MistPath | It provides the path towards our goal destination. |
MistPath
Property | Datatype | What it infers |
---|---|---|
coordinate | String | It is spatial coordinate. |
name | String | Name of the route which is visible on the map |
mapID | String | Unique identifier for the map. |
nodes | list : PathNode | List of nodes to be traversed. |
pathID | String | Unique id for the path. |
Example:
Swift:
func didUpdate(_ map: MistMap!) {
self.mistMap = map
}
Obj-c:
(void)didUpdateMap:(MistMap *)map {
_mistMap = map;
}
didErrorOccur(_ withError:,withErrorMessgage).
This method will get called if the SDK faces any error rather than getting any positive response. And it will help us by giving two values
- errorMessage of type NSString,
- errorType of type ErrorType Enum.
ErrorType
Property | What it infers |
---|---|
.noResponse | This will be thrown when Mist cloud cannot send a response to the device. |
.responseParseError | This will be thrown, if we could not be able to parse the response from Mist server. |
.noBeaconsDetected | It will be thrown when there is no beacon available to scan. |
.noConnectionToCloud | It will be thrown when we cannot be able to establish a connection to our Mist cloud. |
.noDataConnection | It will be thrown when our device has no internet connection. |
.authFailure | If SDK could not authorize, we will get this issue. |
.serverOverloaded | This error will be thrown if our server is already overloaded, and it cannot process our request. |
.sdkNotStarted | This will be thrown when the SDK itself is not running. |
Example:
Swift:
func didErrorOccur(with errorType: Error, andMessage errorMessage: String!) {
switch errorType{
case .noResponse:
// Handle noResponse Error
case .responseParseError:
// Handle responseParseError Error
case .noBeaconsDetected:
// Handle noBeaconsDetected Error
case .noConnectionToCloud:
// Handle noConnectionToCloud Error
case .noDataConnection:
// Handle noDataConnection Error
case .authFailure:
// Handle authFailure Error
case .serverOverloaded:
// Handle serverOverloaded Error
case .sdkNotStarted:
// Handle sdkNotStarted Error
}
}
Obj-c:
(void)didErrorOccurWithType:(NSError*)errorType andMessage:(NSString *)errorMessage{
switch (errorType) {
case ErrorTypeNoResponse:
// handle ErrorTypeNoResponse break;
case ErrorTypeResponseParseError:
// handle ErrorTypeResponseParseError break;
case ErrorTypeNoBeaconsDetected:
// handle ErrorTypeNoBeaconsDetected break;
case ErrorTypeNoConnectionToCloud:
// handle ErrorTypeNoConnectionToCloud break;
case ErrorTypeNoDataConnection:
// handle ErrorTypeNoDataConnection break;
case ErrorTypeAuthFailure:
// handle ErrorTypeAuthFailure break;
case ErrorTypeServerOverloaded:
// handle ErrorTypeServerOverloaded break;
case ErrorTypeSDKNotStarted:
// handle ErrorTypeSDKNotStarted break;
}
}
didReceivedOrgInfo
This method will get called if the SDK can successfully authenticate our organization with an access token. It will give is the following values
- TokenName of type String.
- OrgID of type String.
Example:
Swift:
func didReceivedOrgInfo(withTokenName tokenName: String!, andOrgID orgID: String!) {
self.tokenName = tokenName
self.orgID = orgID
}
Obj-c:
(void)didReceivedOrgInfoWithTokenName:(NSString *)tokenName andOrgID:(NSString *)orgID{
_orgID = orgID;
_tokenName = tokenName;
}
As we already gone through, a zone is a custom area defined on the Mist map to get the notification to provide vicinity related information to your customer. And this delegate will get called when a device enters the defined zone area in the Mist portal.
-
func didEnter(_ mistZone: MistZone!) -> Void
-
func didExitZone(_ mistZone: MistZone!) -> Void
didEnter(_ mistZone: MistZone)
This delegate method will get called when the app enters our monitoring region - (the area where we implemented our Mist System).
Example:
Swift:
func didEnter(_ mistZone: MistZone!) {
print("Entered into MistZone \(mistZone)")
}
Obj-c:
(void)didEnterZone:(MistZone *)mistZone{
printf("Entered into the zone %s", mistZone.debugDescription);
}
didExitZone(_ mistZone: MistZone)
This delegate method will get called when the app exits from our monitoring region - (the area where we implemented our Mist System). Both above methods give us a mistZone object of type MistZone.
Example:
Swift:
func didExitZone(_ mistZone: MistZone!) {
print("Exit from MistZone \(mistZone)")
}
Obj-c:
(void)didExitZone:(MistZone *)mistZone{
printf("Exit from the zone %s", mistZone.debugDescription);
}
Note: Both methods are optional in this protocol- means that no need to override if any class conforming to ZonesDelegate but if we want to have a better experience, use this delegate as much effective as possible.
MistZone
Property | Datatype | What it infers |
---|---|---|
name | String | Name of the Zone. |
userID | String | Name of the Zone. |
orgID, siteID | String | They are just an identifier of the organization and a site where mist is implemented. |
zoneID | String | Unique Identifier for the zone. |
sinceTime | String | It tells from what time user is inside the zone. |
sinceTimeEpoch | long | It tells and gives the timer, and it says how long the device is active in a zone. |
sessionID | String | SDK Maintains a session in backend. And this id indicates the session of the current device inside the zone. |
zonePosition | ZonePosition | It gives the spatial coordinates of Three-dimensional plane |
ZonePosition
Property | Datatype | What it infers |
---|---|---|
x | double | Spatial coordinate X |
y | double | Spatial coordinate Y |
z | double | Spatial coordinate Z |
MapsListDelegate.
func didReceiveAllMaps(_ maps: [MistMap]!) -> Void.
- This delegate will give us maps for all sites in the entire organization. It gives us the array of maps which is supposed to be of MistMap type (properties were explained in detail – didUpdate(_map) delegate explanation.).
- And it is a mandatory method to be overridden, if the class wants to conform this MapsListDelegate protocol.
Example:
Swift:
func didReceiveAllMaps(_ maps: [MistMap]!) {
self.mapList = maps
}
Obj-c:
(void)didReceiveAllMaps:(NSArray<MistMap *> *)maps{
_mapList = maps;
}
VirtualBeaconsDelegate. As we already know, vBeacon can provide proximity related information and the good thing is you can move these vBeacon wherever we want to place them in your floorplan and never have to worry about any battery or relocation problems. And it will work as exactly same as physical beacon.
Required methods to be overridden.
- didRangeVirtualBeacon
Using this delegate method, we can get the current ranging beacon, which is near to us.
func didRangeVirtualBeacon(_ mistVirtualBeacon: MistVirtualBeacon!) -> Void
Example:
Swift:
func didRangeVirtualBeacon(_ mistVirtualBeacon: MistVirtualBeacon!) {
self. rangingvBeacon = mistVirtualBeacon
}
Obj-c:
(void)didRangeVirtualBeacon:(MistVirtualBeacon *)mistVirtualBeacon { _rangingvBeacon = mistVirtualBeacon;
}
Optional methods can be overridden on the need basis.
-
didUpdateVirtualBeaconList
It will return all the available virtual beacons placed on the floorplan whenever its position and other details are changed from the Mist portal.
func didUpdateVirtualBeaconList(_ mistVirtualBeacons: [MistVirtualBeacon]!) -> Void
Example:
Swift:
func didUpdateVirtualBeaconList(_ mistVirtualBeacons: [MistVirtualBeacon]!) {
self.vBeaconList = mistVirtualBeacons
}
Obj-c:
(void)didUpdateVirtualBeaconList:(NSArray<MistVirtualBeacon *> *)mistVirtualBeacons{
_vBeaconList = mistVirtualBeacons;
}
It returns the object/ array of Objects of the type MistVirtualBeacon.
Properties of MistVirtualBeacon
MistVirtualBeacon
Property | Datatype | What it infers |
---|---|---|
name | String | Name of the Virtual beacon |
orgID | String | Organization Identifier |
siteID | String | Site/ Venue id |
mapID | String | Floorplan id |
vbID | String | Unique Identifier of the Virtual beacon on Mist portal |
vbUUID | long | vBeacon UUID |
vbMajor | String | Major value of vBeaconsession of the current device inside the zone. |
vbMinor | long | Minor value of vBeacon |
position | BeaconPosition | It Mentions where exactly the vBeacon is positioned in floor plan. |
additionalInf | AdditionalInfo | Additional information on the vBeacons |
message | String | Any custom messages entered on mist portal.it will be Used for Notification purpose. |
power | long | It’s the power of the vBeacon, to increase the sensing strength. So that the device can sense the vBeacon in a specified distance. |
BeaconPosition
Property | Datatype | What it infers |
---|---|---|
x | double | Spatial coordinate X of vBeacon. |
y | double | Spatial coordinate Y of vBeacon. |
z | double | Spatial coordinate Z of vBeacon. |
AdditionalInfo
Property | Datatype | What it infers |
---|---|---|
proximity | String | Proximity of the device with vBeacon, like: 1. immediate 2. near 3. far 4. unknown |
distance | double | It tells how much distance a device from the vBeacon. |
rssi | double | Signal strength |
orientation | long | Orientation of device towards the vBeacon |
direction | String | Direction towards the vBeacon |
- And finally, we simply call the stop function in the indoor Location manager to stop the SDK. a. Swift: IndoorLocationManager?.stop () b. Obj-c:[_indoorLocationManager stop];
- -(void) startWithIndoorLocationDelegate: (id ) delegate;
- -(void) stop;
- -(NSArray*) getWayfindingPathTo:(Position*) destination;
- +(NSUUID *)getMistUUID;
- +(void)clearMistUUID;
- -(void)saveClientInformation:(NSString *)clientName withDelegate: (id)clientInformationDelegate;
- -(void)getClientInformationwithDelegate:(id)clientInformationDelegate;
- This method will start the MistSDK.
- This is the instance method, means that it should only be invoked via object of the class
- It will take an indoorLocationDelegate as a parameter. So that we can be able to override the callbacks defined in indoorLocationDelegate protocol.
- And it returns void.
- Usage:
- Swift:
let indoorLocationManager = IndoorLocationManager.sharedInstance(MistConstants.mistAccessToken) indoorLocationManager?.start (with: self)
- Obj-C:
self.indoorLocationManager = [IndoorLocationManager sharedInstance: @"<AccessToken>"]; [_indoorLocationManager startWithIndoorLocationDelegate:self];
- This method will stop MistSDK.
- This is also the instance method, so invocation should be via instance of class only.
- It doesn’t take any arguments and won’t return anything.
- Usage:
- Swift:
indoorLocationManager?.stop()
- Obj-C:
[_indoorLocationManager stop];
- This method will return a list of nodes to be traversed when we want to draw the path towards the destination.
- This is also the instance method, so invocation should be via instance of class only.
- We should pass the destination - (an object of type Position) as an argument.
- It will return a sequence of nodes to be traversed in an array format of type [Node].
- Usage:
- Swift:
let nodes = indoorLocationManager?.getWayfindingPath(to: Position.init(makeX: 10, y: 10))
- Obj-C:
NSArray *nodes = [_indoorLocationManager getWayfindingPathTo:[Position positionMakeX:10 Y: 10]];
- MistUUIDis the unique user id provided to the user who is in the session actively.
- This method will give us the current Mist User UUID from the server.
- This is a class method, so invocation should be via Name of the class. It's like invoking a static method with a reference of a class Name.
- It doesn’t take any arguments. [Node].
- It returns the unique identifier of type NSUUID to the caller function.
- Usage:
- Swift:
let userUniqueID = IndoorLocationManager.getMistUUID()
- Obj-C:
NSUUID *userUniqueID = [IndoorLocationManager getMistUUID];
- If the user wants to remove the user reference id for some reason, they can use clearMistUUI() method.
- It will clear the current session of the user from backend. And the user can call getMistUUID()again if he wishes to create and get a new id for the current user.
- It doesn’t take any arguments.
- Usage:
- Swift:
IndoorLocationManager.clearMistUUID()
- Obj-C:
[IndoorLocationManager clearMistUUID];
- This method saves the client information to the mist server - (client is the current user in the session).
- The user can send his name to server via this method, SDK will invoke the API update the username to server. After this process we can easily find the user in the map via this name.
- It takes the username and the ClientInformationDelegate as a parameter. And it doesn’t return anything. Since this is an asynchronous function, we deal with delegate pattern to get a response from this method.
- Usage:
- Swift:
indoorLocationManager?.saveClientInformation(" <username> ", with: self)
- Obj-C:
[_indoorLocationManager saveClientInformation:"<username>" withDelegate:self]
- And the result will be returned in the call backs of ClientInformationDelegate.
- It fetches the client information from the server and returns to the application in the form of ClientInformationDelegate
- Usage:
- Swift:
indoorLocationManager?.getClientInformationwithDelegate(self)
- Obj-C:
[self.indoorLocationManager getClientInformationwithDelegate:self];
Using Old SDK <= 2.0.8
- Swift:
func onSuccess(_ clientName: String) func onError(_ errorType: ErrorType, andMessage errorMessage: String)
- Obj-C:
-(void) onSuccess:(NSString*) clientName; -(void) onError:(ErrorType )errorType andMessage:(NSString*) errorMessage;
Using New SDK <= 3.0.0
- Swift:
func onSuccess(_ clientName: String) func onError(_ errorType: Error, andMessage errorMessage: String)
- Obj-C:
-(void) onSuccess:(NSString*) clientName; -(void) onError:(NSError*)errorType andMessage:(NSString*) errorMessage;
OnSuccess
- It will be triggered upon the success of the Updating process.
- It will give us the updated clientName.
- Swift:
func onSuccess(_ clientName: String!) { print(clientName ?? "") }
- Obj-C:
-(void)onSuccess:(NSString *)clientName { NSLog(@"client name %@", clientName); }
OnError
- This will be triggered if there is a failure in the updating process.
- and it will help us by giving two values
- errorMessage of type NSString,
- errorType of type ErrorType Enum in old sdk <= 2.0.8 and Error in new sdk 3.x.x onwards
- (For error type, please go through the list of errors mentioned in the table at the didErrorOccur section in IndoorLocationDelegate.)
if using Old SDK <= 2.0.8
- Swift:
func onError(_ errorType: ErrorType, andMessage errorMessage: String!) { //handleErrorCases, for more go through didErrorOccur section in IndoorLocationDelegate }
- Obj-C:
-(void)onError:(ErrorType)errorType andMessage:(NSString *)errorMessage { //handleErrorCases, for more go through didErrorOccur section in IndoorLocationDelegate }
if Using New SDK <= 3.0.0
- Swift:
func onError(_ errorType: Error, andMessage errorMessage: String!) { //handleErrorCases, for more go through didErrorOccur section in IndoorLocationDelegate }
- Obj-C:
-(void)onError:(NSError*)errorType andMessage:(NSString *)errorMessage { //handleErrorCases, for more go through didErrorOccur section in IndoorLocationDelegate }
For further questions please reach out to support@mist.com