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

  • Link the following libraries:

    • CoreLocation
    • CoreMotion
    • libc++.tbd
    • libz.tbd
  • If you chose the manual installation of the SDK, in the configuration of your project, under Linking/Other Linker Flags add the flag “-ObjC”

  • Disable Bitcode. Go to the Build settings tab of your app, search for the option Enable Bitcode and select NO as the value for the setting.

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

let locationManager: CLLocationManager = CLLocationManager()
if CLLocationManager.locationServicesEnabled() {
    let status: CLAuthorizationStatus = CLLocationManager.authorizationStatus()
    if status == CLAuthorizationStatus.notDetermined {
        locationManager.requestAlwaysAuthorization()
        //or
        locationManager.requestWhenInUseAuthorization()
    }
}
  • Create a header file (.h) and add the line:
#import <SitumSDK/SitumSDK.h>
  • In the configuration of your project, under Swift compiler - General/Objective-C Bridging Header add the route from the project root to the header file created previously.

IMPORTANT: If you are using a SitumSDK version equal or greater than 2.31.1, you can skip the two last steps refering to the bridging header and just use import SitumSDK

You can now compile and check everything is working.

And that’s all. From now on, you should be able to use Situm SDK in your app.

Step 2: Set API Key

Now that you have correctly configured your Swift project, you can start writting your application’s code. All you need to do is introduce your credentials. You can do that in your AppDelegate.swiftfile. 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 APIKEY 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")

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