Basic functionality of Situm SDK Document
Basic functionality of Situm SDK
At this point you have successfully follow the Setup guide and you have a iOS project prepared to work with the Situm SDK. Congratulations! Now let’s talk about how to make funny things.
Contents of this guide:
- Loading cartography information
- Finding the user’s location
- Getting directions to a point
- Retrieveing Turn-by-turn navigation
Loading cartography information
In API v2.x.x you can load cartographic information (Buildings, Floors, Points of interest, Events) with the following methods:
// 1. Retrieve your buildings
[[SITCommunicationManager sharedManager] fetchBuildingsWithOptions:nil
success:^(NSDictionary *mapping) {
NSLog(@"results: %@", [mapping valueForKey:@"results"]);
} failure:^(NSError *error) {
NSLog(@"error: %@", error);
}];
// 2. Retrieve information about a building
[[SITCommunicationManager sharedManager] fetchBuildingInfo:@""
withOptions:nil
success:^(NSDictionary *mapping) {
SITBuildingInfo *info = [mapping valueForKey:@"results"];
} failure:^(NSError *error) {
NSLog(@"error: %@", error);
}];
Finding the user’s location
In API v2.x.x there is a central component to work with the user’s location. You can determine where a user as in the following example:
// 1. Declare that your class conforms to the SITLocationDelegate protocol
@interface YourClassShouldGoHere : NSObject SITLocationDelegate
// 2: Build a SITLocationRequest
SITLocationRequest *request = [[SITLocationRequest alloc]initWithPriority:kSITHighAccuracy
provider:kSITHybridProvider
updateInterval:1
buildingID:@"Unique identifier of building" // Identifier of the building where you want to find the user
operationQueue:nil
options:nil];
// 2.5: Use beacons with custom proximityUUIDs (Optionally).
SITBeaconFilter *customBeaconFilter = [[SITBeaconFilter alloc]initWithUUID:@"00000000-0000-0000-0000-000000000001"
identifier:@"com.myCompany.beacons"];
NSArraySITBeaconFilter *> *beaconFilters = @[customBeaconFilter];
request.beaconFilters = beaconFilters;
// 3. Conform to the SITLocationManagerDelegate protocol to receive updates
[SITLocationManager].delegate = self;
// 4. Start the SITLocationManager with the LocationRequest
[[SITLocationManager sharedManager] requesrLocationUpdates:request];
// 5. Listen for updates
- (void)locationManager:(idSITLocationInterface)locationManager
didUpdateLocation:(SITLocation *)location
{
NSLog(@"new location has arrived: %@", location);
}
Getting directions to a point
In API 2.x.x there is a central component that provides routes and indications between two points.
// 1. Declare that your class conforms to the SITDirectionsDelegate protocol
@interface YourClassShouldGoHere : NSObject SITDirectionsDelegate
// 2. Build a SITDirectionsRequest with the options you want
SITLocation *location = ...; // This should be updates received from the SITLocationManager as previously described in section #location
SITPoint *destination = ...; // This should be a point in a building (usually a point of interest - SITPOI object)
SITDirectionsRequest *request = [[SITDirectionsRequest alloc] initWithRequestID:0 // There is no need to initialize this field (it will be automatically set for you)
origin:origin
destination:destination
options:nil];
// 3. Perform the request
[[SITDirectionsManager sharedManager] requestDirections:request];
// 4. Receive the result of the request through the delegate interface
// 4.1. The request has been successfully processed
- (void)directionsManager:(idSITDirectionsInterface)manager
didProcessRequest:(SITDirectionsRequest *)request
withResponse:(SITRoute *)route
{
NSLog(@"successfully processed response: %@ for request: %@", route, request );
}
// 4.2. The processing of the request has failed
- (void)directionsManager:(idSITDirectionsInterface)manager
didFailProcessingRequest:(SITDirectionsRequest *)request
withError:(NSError *)error
{
// Check the error and maybe retry it later. Your logic goes here.
}
This replaces the way of requesting routes in version 1.x.x where there was an specific component SITGraph for every building.
Retrieveing Turn-by-turn navigation
In API 2.x.x you can provide turn by turn navigation in two steps:
// 1. Declare that your class conforms to the SITNavigationDelegate protocol
@interface YourClassShouldGoHere : NSObject SITNavigationDelegate
// 2. Create a SITNavigationRequest and load into the module
SITNavigationRequest *navigationRequest = [[SITNavigationRequest alloc]initWithRoute:route]; // Additional parameters can be configured in the request
[self.navigationManager requestNavigationUpdates:navigationRequest];
// 3. Conform to the SITNavigationDelegate protocol to receive updates
[[SITNavigationManager sharedManager].delegate = self;
// 4. Continuosly send location updates (SITLocation objects) to the SITNavigationManager
[[SITNavigationManager sharedManager] uploadWithLocation:location]; // These should be updates received from the SITLocationManager as previously described in section #location
// 5. Receive Updates through its delegate interface.
// 5.1. Maybe the user is following the loaded SITRoute. In that case you'll receive SITNavigationProgress objects with the progress of the route.
- (void)navigationManager:(idSITNavigationInterface)navigationManager
didUpdateProgress:(SITNavigationProgress *)progress
onRoute:(SITRoute *)route
{
NSLog(@"User is following the loaded route. I can update the remaining distance, time, ... with the SITNavigationProgress object: %@", progress);
}
// 5.2. Maybe the user is not following the loaded route. In that case, when the distance will be higher than a configurable threshold (outsideRouteThreshold as declared in SITNavigationRequest) a notification will be send on the method:
- (void)navigationManager:(idSITNavigationInterface)navigationManager
userOutsideRoute:(SITRoute *)route
{
NSLog(@"User is following the loaded route. Maybe I should recalculate directions from the actual location of the user");
}
// 5.3. At some point the user can reach the destination and you'll be notified on the appropiate method:
- (void)navigationManager:(idSITNavigationInterface)navigationManager
destinationReachedOnRoute:(SITRoute *)route
{
// At this point all the resources should be released by calling the reset method on the SITNavigationManager
}
How to Migrate your code from previous versions (1.x.x) of Situm SDK to 2.x.x versions
For those of you that has previously worked with 1.x.x versions of the SDK you will notice some changes on the interface. For now, most of the new functionality is compatible with the previous versions but you should change to the new APIs in order to receive support, as versions 1.x.x will be discontinued in later releases.
In particular, the following classes has been deprecated:
SITIndoorBuilding, SITIndoorLevel, SITPOIExterior, SITIndoorLocation, SITIndoorPoint, SITIndoorRoute, SITIndoorRouteStep, SITIndoorLocationManager
Instead you should now use the equivalent ones: SITBuilding, SITFloor, SITPOI, SITLocation, SITPoint, SITRoute, SITRouteStep, SITLocationManager.
SITPOIBase will be integrated in the new and unique SITPOI class.
New modules has been introduced to better support and simplify funcionality:
Now you can find the route between two points with the SITDirectionsManager component instead of using SITGraph objects.
Additionally, you can navigate through a route with the SITNavigationManager component.