image

iOS Quick Start

Veery iOS API is written in Swift 3.0 and supports iOS 9.0 and newer versions. Veery works with both Swift and Objective-C projects.

Integration

You can obtain the Veery API for iOS with Cocoapods, Carthage or as a direct download from GitHub.

Each method has its pros and cons, but we recommend Cocoapods as a good place to start.

Cocoapods

Cocoapods is the most popular dependency management tool for Cocoa.

As Cocoapods is built using Ruby, you can use the Ruby default available on macOS to install Cocoapods.

sudo gem install cocoapods

Inside the root directory of your Xcode project, create the pod file with the following command.

pod init

Open the generated .Podfile with your preferred text editor. Please add the following pod source and save it.

source 'https://github.com/roofstreet/cocoa.repo.git'

Inside your “target” clause, add the pod and its version x.x.x (please check our releases). Please do not forget to tell Cocoapods that you are using Swift and its dynamic frameworks with the keyword use_frameworks!.

target 'YourProjectName' do
      use_frameworks!
      pod 'Veery', 'x.x.x'
end

Install the API with the following command:

pod install

Finally, close your YourProjectName.xcodeproj and open the new workspace YourProjectName.xcworkspace generated by Cocoapods.

open –a Xcode YourProjectName.xcworkspace

The command

pod outdated

allows you to know if Veery is outdated. If that is the case, then we can update Veery with the following command:

pod update

Carthage

do not execute this if you have already chosen to integrate using Cocoapods

Carthage is a decentralized dependency manager which tends to be the simplest tool for integrating dependencies in Xcode projects.

To install Carthage, you can download and run the Carthage.pkg file for the latest release then follow the instructions. If you use homebrew, you can also install Carthage by simply running the following commands.

brew update
brew install carthage

Navigate to the root directory of your project and create an empty Cartfile.

touch Cartfile

Open the Cartfile with your favorite text editor, then add the following line and save it:

x.x.x corresponds to the latest version (please check our release list).

github “roofstreet/Veery.ios.release” == x.x.x

Install the library by running the following command:

carthage update –-platform iOS

Carthage will generate a Carthage directory containing the framework. Simply drag the Veery.framework inside the Carthage/Checkouts directory to your xcode project’s target settings inside the General tab and drop it in Linked Frameworks and Libraries.

This tells Xcode to link your app to the Veery framework, allowing you to use it within your own code.

GitHub

do not execute this if you have already chosen to integrate using Cocoapods or Carthage

You can clone or download the framework directly from GitHub. Use git to clone the framework as follows:

git clone https://github.com/roofstreet/Veery.ios.release.git

Include The Library

Enabling Background Location Service

First of all, as Veery exploits iOS’s background location to provide a seamless advanced service, you need to enable this feature in your Xcode project.

Open the project navigator by choosing View → Navigators → Show Project Navigator.

Choose your target from the Project/Targets pop-up menu or in the Targets section of the second sidebar if it appears.

Click Capabilities then set Background Modes to ON and select Location updates, as shown:

veery-ios-enable-background-location

As indicated by Xcode, add the NSLocationAlwaysUsageDescription in your plist file.

The permanent usage allows Veery to provide a better user experience.

Here is an example of the plist key:

veery-ios-enable-background-location-2

If you work on Objective-C projects, as Veery is built using Swift, you need to embed the Swift standard libraries as well. You can do this by simply going to the project editor as explained above, click on Build Settings, choose Build Options and set Always Embed Swift Standard Libraries to YES.

Declare your API_KEY

You should have received the following information in the registration confirmation email.

  • CLIENT_ID : The UUID identifying your company in our systems
  • Developer API KEY : The API key your mobile app will use to register a new mobile user
  • API Secret : The password that authenticate your API_KEY

In your info.plist (or application_name.plist) file you shoud add the following :

VeeryApiKey
VeeryClientID

Import And Create Veery Objects (+ set the Key Secret)

For your project, import the Veery library and subclass the Veery delegate, then create a Veery object on every class where location services are needed, i.e. in your view controllers. Please follow the below patterns according to the programming language of your project.

Swift

import Veery
      class YourClass: ..., VeeryDelegate {
      let veery = Veery()
      veery.delegate = self
      veery.SetApiKeySecret("kjqSLJhbljhbLhblkjkjb")
}

Objective-C

@import Veery;
@implementation ViewController
      Veery *veery = [[Veery alloc] init];
      veery.delegate = self;
      veery.SetApiKeySecret("kjqSLJhbljhbLhblkjkjb");
}

Veery is designed with a singleton pattern, therefore you can create as many Veery instances and delegates as you need. They still refer to the same Veery service instance. Below you will find 2 typical usage examples of Veery in a Swift and Objective-C project.

Veery is designed with a singleton pattern, therefore you can create as many Veery instances and delegates as you need. They still refer to the same Veery service instance. Below you will find 2 typical usage examples of Veery in a Swift and Objective-C project.

Swift

import UIKit
import MapKit
import Veery
class ViewController: UIViewController, MKMapViewDelegate, VeeryDelegate
{
     let veery = Veery()
     @IBOutlet weak var mapView: MKMapView!
     @IBOutlet weak var switchButton: UISwitch!
     fileprivate let radiusZoom = 500.0

     override func viewDidLoad() {
          super.viewDidLoad()
          veery.delegate = self
          self.mapView.delegate = self
     }

     @IBAction func startLocationService(_ sender: UISwitch) {
          if sender.isOn {
               veery.requestLocationUpdate()
          } else {
               veery.stopLocationUpdate()
          }
     }

     fileprivate func zoom(_ loc: CLLocation, radius: CLLocationDistance) {
          let coords = CLLocationCoordinate2D(latitude: loc.coordinate.latitude, longitude:loc.coordinate.longitude)
          let region = MKCoordinateRegionMakeWithDistance(coords, radius, radius)
          mapView.setRegion(region, animated: true)
     }

     func veeryDidReceiveNewLocations(_ veery: Veery, newLocations: [CLLocation]) {
          draw(location: newLocations[0])
     }

     func mapView(_ mapView: MKMapView, rendererFor overlay: MKOverlay) -> MKOverlayRenderer {
          if overlay is MKCircle {
               let circleRenderer = MKCircleRenderer(overlay: overlay)
               circleRenderer.fillColor = UIColor.blue.withAlphaComponent(0.01)
               circleRenderer.strokeColor = UIColor.blue
               circleRenderer.lineWidth = 1
               return circleRenderer
          }
          return MKOverlayRenderer(overlay: overlay)
     }

     @IBAction func getCurrentLocation(_ sender: UIBarButtonItem) {
          if let loc = veery.getCurrentLocation() {
               zoom(loc, radius: radiusZoom)
               draw(location: loc)
          }
     }

     private func draw(location loc: CLLocation) {
          let point = MKPointAnnotation()
          point.coordinate = loc.coordinate
          point.title = loc.timestamp.description
          mapView.addAnnotation(point)
          let circle = MKCircle.init(center: loc.coordinate, radius: loc.horizontalAccuracy)
          mapView.add(circle)
     }
}

Objective-C

#import "ViewController.h"
@import Veery;
@interface ViewController () <VeeryDelegate>
@property Veery *veery;
@end
@implementation ViewController
- (void)viewDidLoad {
      [super viewDidLoad];
      self.veery = [[Veery alloc] init];
      self.veery.delegate = self;
      [self.veery serviceConnect];
      [self.veery requestLocationUpdate];
}

- (void)veeryDidReceiveNewLocations:(Veery *)veery newLocations:(NSArray<CLLocation *> *)newLocations {
      // location data processing...
}
- (IBAction)getCurrentLocation {
      CLLocation * _Nullable loc = [self.veery getCurrentLocation];
      if (loc != nil) {
            // location data processing...
      }
}
@end

Enabling Background Networking Sessions

Veery works quietly in the background to deliver the most accurate locations to your application while minimizing battery consumption. To provide advanced services such as mobility prediction, Veery needs to communicate with our backend to handle some networking events. In your AppDelegate, please add a Veery instance, implement the delegate function handleEventsForBackgroundURLSession, then call the Veery’s handler as follows.

Swift

import Veery
class AppDelegate: UIResponder, UIApplicationDelegate {
     let veery = Veery()
     func application(_ application: UIApplication, 
               handleEventsForBackgroundURLSession identifier: String,
               completionHandler: @escaping () -> Void) {
          if identifier == Veery.backgroundSessionID {
               veery.handleEventsForBackgroundURLSession(
                    identifier:identifier, completionHandler: completionHandler)
          } else {
               // if you have your own networking background sessions, 
               //  you can process them here
          }
     }

Objective-C

@import Veery;
@implementation AppDelegate
- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)())completionHandler {
     if (identifier == Veery.backgroundSessionID) {
          Veery *veery = [[Veery alloc] init];
          [veery handleEventsForBackgroundURLSessionWithIdentifier:identifier completionHandler:completionHandler];
     } else {
          // if you have your proper networking background sessions, 
          // you can process them here
     }
}

The background session identifier will be helpful for identifying Veery if you have multiple background sessions to process. Veery sessions are identified with Veery.backgroundSessionID.

Connect To The Veery Service

You can connect to Veery’s service by simply implementing its serviceConnect() function.

Swift

veery.serviceConnect()

Objective-C

[veery serviceConnect]

A good place to connect to the service is where you initialize your application.

Get The Current Location

Veery iOS API has the following function which retrieves the last geo-localization data:

func getCurrentLocation() -> CLLocation?

Note that retrieving a CLLocation is optional. In order to obtain the data, you need to use the following code:

Swift

if let location = veery.getCurrentLocation() {
     // do whatever you need with the location object
}

Objective-C

CLLocation * _Nullable location = [self.veery getCurrentLocation];
if (location != nil) {
     // do whatever you need with the location object
}

For spontaneous location requests, this function is the right choice. If you need more frequent updates, for example, for tracking applications, please follow the instructions below.

Activate the required functionality level

You should activate the necessary functionality level for every mobile user (see the full documentation to check which level is required for the functionalities you want to use).

FOREGROUND : geolocalize the user only when the application is in foreground. The connection with the Veery backend remains inactive

BACKGROUND : geolocalize the user also when the application is in background (this includes FOREGROUND). The connection with the Veery backend remains disabled.

BACKEND : geolocalize the user when the app is in background and in foreground, and communicate the positions with the Veery Backend. This is required for SDK fonctions implying notifications and data completion.

GEOPROFILE : The levels above + the users profiling functions (Predictions, Point of interests, …).

You can do that operation whenever you want to activate the user but you should notice that iOS will request for required the user rights when called.

//
// iOS interactively request for the authorization for Background Location 
//
veery.activate(service: Veery.BACKGROUND)

This call can be made when the application starts but also after you have explained to the user why you require the Background Location right.

BACKEND and GEOPROFILE implies backend charges for every mobile where it is executed. Contact us for details.

Register For Location Updates

Once you’ve registered as a Veery delegate, you can implement the following functions to receive real time location updates:

Swift

func veeryDidReceiveNewLocations(newLocations: CLLocation[]) {
     // do whatever you need with the location object
}

Objective-C

- (void)veeryDidReceiveNewLocations: (Veery *)veery
newLocations:(NSArray<CLLocation *> *)newLocations {
     // do whatever you need with the location object
}

The frequency of location updates depends on the mobility and the activity of the app users, as well as network conditions. Veery iOS is equipped with an advanced adaptive tracking algorithm which captures the best of a user’s trajectory, while preserving battery life.

In contrast to the basic iOS location service, Veery does not require any configurations. The algorithm adapts itself to user activity.

Start & Stop Receiving Location Updates

To start receiving location updates, simply implement the requestLocationUpdate() function.

To stop receiving location updates, just initiate the stopLocationUpdate().

Swift

veery.requestLocationUpdate()
//
// ...
//
veery.stopLocationUpdate()

Objective-C

[self.veery requestLocationUpdate]
//
// ...
//
[self.veery stopLocationUpdate]

Please place these functions anywhere you need to control the flow of location updates.