Quick start guide

Introduction

In this tutorial, we will guide you step by step to set up your first application using Situm Wayfinding Module. Before starting to write code, we recommend you to set up an account in our Dashboard, retrieve your API KEY and configure your first building.

  1. Go to the sign in form and enter your username and password to sign in.
  2. Go to the account section and on the bottom, click on "generate one" to generate your API KEY.
  3. Go to the buildings section and create your first building.
  4. Download Situm Mapping Tool Android application. With this application you will be able to configure and test Situm's indoor positioning system in your buildings.

Perfect! Now you are ready to develop your first indoor positioning application.

Step 1: Configure our SDK in your Objective C project

First of all, you must configure Situm SDK in your iOS project. There’s two ways to integrate SitumSDK in your project:

Cocapods (recommended for production)

  • Create a Podfile in the root folder of your project. Add a dependency with SitumSDK like this:
target '<your_target_name>' do
  use_frameworks!
  source 'https://github.com/CocoaPods/Specs.git'
  platform :ios, '9.0'
  pod 'SitumSDK', '2.25.1'

Check and add the latest avaliable version of the SitumSDK pod, which you can find here. After creating the file, you just have to run pod install from the route folder of your project, close the project.xcodeproj file and open project.xcworkspace instead. SitumSDK will be downloaded and correctly linked, so you can keep working from here. More information about Cocoapods here.

Manual installation

For this, you will have to choose which version of our SDK you need. If anything in your app uses Protobuf, you should use our SDK without Protobuf included (available from version 2.31.3 or higher) and provide that dependency separately. If that’s not the case, you can use the version with Protobuf included for simplicity’s sake. Both are available in our repository.

  • Drag the file SitumSDK.framework to your project (normally this should be included in a SitumSDK folder, inside your Vendor folder). Make sure to check the option “Copy items if needed”. In recent versions of Xcode this automatically links your app with the framework as you can check on the Build phase tab, Link Binary with Libraries section. Otherwise, add a link to the framework. You can download the latest version of our SDK from our repository.

Other dependencies configuration

If you are not using Cocoapods, you need to configure this extra settings:

  • Go to the Build Phases settings tab. Add libz.tbd and libc++.tbd on Link Binary With Libraries.

  • On Link Binary With Libraries add the following system frameworks: CoreLocation and CoreMotion.

  • Go to the Build Settings tab. Search the “Other linker flags” section and add “-ObjC”.

For both the Cocoapods and the manual installation, we need you to configure some more settings:

  • Open your project settings and go to the Build Settings tab. Search for the setting Enable Bitcode and chage its value to NO (if not already done).

Finally, there is a last step needed if we want to work with the indoor location system: requesting permissions to access location of the user.

  • Go to the Info tab of the Settings of your app. We need to add descriptors for the system permissions, accompanied with a label of your liking. The description value of these keys can be anything you want, for example just type “Location and bluetooth is required to find out where you are”. The required keys to use our SDK are the following:

    • NSLocationAlwaysUsageDescription (in XCode, “Privacy - Location Always Usage Description”).
    • NSLocationWhenInUseUsageDescription (in XCode, “Privacy - Location When In Use Usage Description”).
    • NSBluetoothPeripheralUsageDescription (in XCode, “Privacy - Bluetooth Peripheral Usage Description”).
    • Only if you are targeting iOS13.0 or superior: NSBluetoothAlwaysUsageDescription (in XCode, “Privacy - Bluetooth Always Usage Description”)
  • Then, you also need to request the Location permission from the user, as follows:

CLLocationManager *locationManager = [CLLocationManager new];

if ([CLLocationManager locationServicesEnabled]) {
    if ([CLLocationManager authorizationStatus] == kCLAuthorizationStatusNotDetermined) {
        [locationManager requestAlwaysAuthorization];
        //or
        [locationManager requestWhenInUseAuthorization];
    }
}

And that’s all. From now on, you should be able to use Situm SDK in your app by importing its components with the line:

#import <SitumSDK/SitumSDK.h>

Other possible way to use SitumSDK (ONLY if you are using a version greater or equal to 2.31.1) it’s by importing with:

@import SitumSDK;

Step 2: Set API Key

Now that you have correctly configured your iOS project, you can start writting your application’s code. All you need to do is introduce your credentials. You can do that your appDelegate.m file. There are two ways of doing this:

Using your email address and APIKEY.

This is the recommended option and the one we have implemented in this project. Write the following sentence on the -application:didFinishLaunchingWithOptions: method.

[SITServices provideAPIKey:@"SET YOUR API KEY HERE" forEmail:@"SET YOUR EMAIL HERE"];
Using your user and password

This is the other available option to provide your credentials, with your username and password. As in the previous case, write the following sentence on the -application:didFinishLaunchingWithOptions: method.

[SITServices provideUser:@"SET YOUR USER HERE" password:@"SET YOUR PASSWORD HERE"];

In both cases, remember to add the following dependency in the same file:

#import <SitumSDK/SitumSDK.h>

or its equivalent (if you are using a version greater or equal to 2.31.1)

@import SitumSDK;

Congratulations! Now you can start to code using Situm SDK. For more information and code samples, please check our Objective-C Getting Started in Github.