02 – A basic Swift iOS app

Situm SDK can be used to build Wayfinding and Tracking applications, and dozens of use cases within those realms. However, there is a common pattern or skeleton that most Situm based applications will follow. In this Section, we provide an Swift iOS step-by-step guide to build your first Situm app based on this pattern.

Import Situm SDK in your project dependencies #

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

Cocoapods (recommended) #

Create a Podfile in the root folder of your project and 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', 'X.Y.Z'

Change the version number “X.Y.Z” with the latest available version of the SitumSDK (which you can find here).

After creating this file, open a console, go to your project’s folder and run pod install. This will download & link Situm SDK to your project, and create a file named project.xcworkspace: make sure you always use/open this one (not the project.xcodeproj file).

*If you need more information about Cocoapods, you can read it here.

Manual installation #

If you prefer to install Situm SDK manually, you will need to:

• Link the following system libraries.
  • CoreLocation
  • CoreMotion
  • libc++.tbd
  • libz.tbd
• Apply the -ObjC flag. In “Configuration”, under “Linking/Other Linker Flags”, add the flag “-ObjC”.
• Disable Bitcode. Go to the “Build Settings” tab, search for the option “Enable Bitcode” and select “NO” as the value for that setting.

Then:

• Download a version of SitumSDK from our repository (preferably, the latest stable version as per our changelog).
• 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 (you can check this on the “Build phase” tab, “Link Binary with Libraries” section). Otherwise, add a link to the framework.

A word on Protobuf #

If your app (or any library you use) uses Protobuf, we strongly recommend you that you use Cocoapods (as explained in the previous section).

If you want to go ahead anyway, then you should use a version of our SDK that doesn’t use Protobuf included (available from version 2.31.3 or higher) and provide that dependency separately. You’ll recognize these versions in our repository because they are named such as “SitumSDK.noprotobuf.sdk”.

Grant app permissions #

An application running Situm will need certain permissions in order to work. First, in XCode you should go to the “Settings/Info” tab and create the following keys:

• NSLocationAlwaysAndWhenInUseUsageDescription. In XCode: “Privacy – Location Always and When In Use Usage Description”.
• NSLocationWhenInUseUsageDescription. In XCode: “Privacy – Location When In Use Usage Description”.
• NSBluetoothPeripheralUsageDescription. In XCode: “Privacy – Bluetooth Peripheral Usage Description”.
• NSBluetoothAlwaysUsageDescription (only if you are targeting iOS 13.0 or superior). In XCode: “Privacy – Bluetooth Always Usage Description”.

You will also need to add a description to each key, which will be shown to the user at the time the app request each specific permission. For example, to ask for Bluetooth usage you can add the key “NSBluetoothAlwaysUsageDescription” with the description “Location and Bluetooth is required to find out where you are”.

Lastly, you need to include the following snippet in your app’s code so the system requests location permissions to the user. If your don’t do this or the user doesn’t grant the permissions, your app won’t receive Situm location information. You will have an example on how to use this function in the Start Positioning Section.

var coreLocationManager:CLLocationManager = CLLocationManager()
...

func requestLocationAuth(){
   if CLLocationManager.locationServicesEnabled() {
      let status: CLAuthorizationStatus = CLLocationManager.authorizationStatus()
      if status == CLAuthorizationStatus.notDetermined {
          coreLocationManager.requestAlwaysAuthorization()
          //or
          coreLocationManager.requestWhenInUseAuthorization()
      }
   }
}

Import the headers #

Import the Situm SDK headers as follows:

@import SitumSDK;

Set up the API Keys #

Great! At this point, you have correctly configured your Swift project. You can start writting your application’s code!

All you need to do now is introducing your Situm credentials (you can obtain them here) in your AppDelegate.swift file. There are two ways of doing this.

Option 1: using your email address and APIKEY (recommended) #

Write the following sentence on the -application:didFinishLaunchingWithOptions: method of your AppDelegate.swift file.

SITServices.provideAPIKey("SET YOUR APIKEY HERE", forEmail: "SET YOUR EMAIL HERE")

Option 2: using your user and password
#

You can also use your username & password directly. To do that, write the following code on the -application:didFinishLaunchingWithOptions: method of your AppDelegate.swift file.

SITServices.provideUser("SET YOUR USER EMAIL HERE", password: "SET YOUR PASSWORD HERE")

Configure the positioning parameters #

Next, you will need to configure the positioning parameters. You may do this by building a LocationRequest object, as shown in the following example.

//You may insert this code in the ViewController where you want to start location updates

 let request: SITLocationRequest = SITLocationRequest()

The previous code will configure a SITLocationRequest with the default parameters. You may also set each parameter individually. To do this, you have two options:

1. (Recommended) By using the Remote Configuration feature, that allows you to change the LocationRequest over-the-air using Situm Dashboard.
2. (Not recommended) By manually setting the parameters in the LocationRequest builder.

Start Positioning #

To receive location updates you need to:

1. Define the class that will implement the SITLocationDelegate protocol.
2. Implement in that class the three mehtods where you will receive location updates:
   1. locationManager(locationManager:didUpdate location:): It will receive every new location produced. 
   2. locationManager(locationManager:didFailWithError error): It will receive every error produced in the SDK.
   3. locationManager(locationManager:didUpdate state): It will receive every status change produced in the SDK.
3. Set that class as the delegate of SITLocationManager.
4. Start the positioning by calling the SITLocationManager with the SITLocationRequest, which will contain the positioning configuration parameters (see previous Section).

The following code snippet assumes that you have created a simple 2 button interface. A similar & more complete example can be found here.

class ViewController: UIViewController, SITLocationDelegate {

    var sitLocManager: SITLocationManager = SITLocationManager.sharedInstance()

...

    //This method is called when the user clicks the "Initialization Button"
    @IBAction func initializeButton(_ sender: UIButton) {

        //This function has been defined in the "Grant app permissions" Section
        requestLocationAuth()

        //Set the delegate so the update functions receive the messages
        sitLocManager.delegate = self
    }

    //This method is called when the user clicks the "StartButton"
    @IBAction func startRequestButton(_ sender: UIButton) {    

        //Create the request to activate positioning
        let request: SITLocationRequest = SITLocationRequest()

        //Start positioning by requesting location updates
        sharedLocManager.requestLocationUpdates(request)
    }

...

//    Delegate functions to receive notifications
    func locationManager(_ locationManager: SITLocationInterface, didUpdate location: SITLocation) {
        print("*POSITION UPDATED*\nPosition was updated to:\n Latitude: \(location.position.coordinate().latitude)\n Longitude:  (location.position.coordinate().longitude).")
    }
    
    func locationManager(_ locationManager: SITLocationInterface, didFailWithError error: Error?) {
        print("*POSITIO UPDATED*\nThere was an error with the request: \(error?.localizedDescription ?? "")")
    }
    
    func locationManager(_ locationManager: SITLocationInterface, didUpdate state: SITLocationState) {
        print("*POSITION UPDATED*\nState was updated to \(state.rawValue)")
    }

At this point, Situm SDK will start computing your location. Your application log should show a serie of messages similar to this one:

*POSITION UPDATED*
Position was updated to:
 Latitude: 42.359897881877846
 Longitude: -8.7809602226224

Stop Positioning #

At any point you may choose to stop the positioning system. You may do so by calling the method removeUpdates method.

...

sitLocManager.removeUpdates()

Next steps: take a look at all the code samples #

We have compiled a list of code samples which will teach you how to interact with Situm SDK to retrieve locations, handle cartography, compute routes and more.

• Swift code examples

• ObjC code examples