02 – A basic Obj-C 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 Objective-C 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’s two ways to integrate SitumSDK in your project.

Cocoapods (recommended) #

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.

Finally, you will need to:

• 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”.

Configure Situm SDK build settings #

Once you import Situm SDK in your project, you will need to perform one basic configuration. 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).

Grant app permissions #

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.

First of all, 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;

Set up your API Keys #

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 (recommended) #

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"];

Run your application #

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