iOS Documentation

Getting started

You can install the GeoSpark iOS SDK through Cocoapods or manually.

Note: GeoSpark SDK supports iOS 9.3 and higher.

Installing with Cocoapods

The easiest way to use GeoSpark in your project is with CocoaPods. Add the following to your Podfile:

  
  pod 'GeoSpark'
  
  

Then, run pod install.

Manual Installation

You can also add the SDK to your project manually, though this is not recommended. Download the current release, unzip the package, and drag GeoSpark.framework into your Xcode project. It will automatically appear in the Linked Frameworks and Libraries section of your project settings.

The SDK currently supports iOS 9.3 and higher.

Initialize SDK

To initialize the SDK, you must call the GeoSpark.initialize method when your app is started.

  
  import GeoSpark

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
      GeoSpark.sharedInstance.intialize("YOUR-SDK-KEY", apiSecret: "YOUR-SECRET");
  }
  
  
  
  #import <GeoSpark/GeoSpark.h>

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [[GeoSpark sharedInstance] intialize:@"YOUR-SDK-KEY" apiSecret:@"YOUR-SECRET"];
    return YES;
  }
  
  

Capabilities and permissions

Go to the capabilities tab in your app settings, scroll to background modes and switch it on. Select Location updates, Background fetch and Remote notifications.

To add permission strings to your Info.plist, go to the Info tab in your app settings and add permission strings for

  
  Privacy - Location Always Usage Description
  Privacy - Location Always and When In Use Usage Description
  Privacy - Location When In Use Usage Description
  
  

APNS Configurations

  1. Log into the GeoSpark dashboard, and open your Settings->Add Certs. Upload your APNS development or distribution certificates (.p12 files).
  2. In the app capabilities, ensure that remote notifications inside background modes is enabled.
  3. The following changes inside AppDelegate will register the SDK for push notifications and route GeoSpark notifications to the SDK.

Inside didFinishLaunchingWithOptions, use the SDK method to register for notifications.


  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
      GeoSpark.sharedInstance.intialize("YOUR-SDK-KEY", apiSecret: "YOUR-SECRET");
      registerForNotifications()
  }

  func getNotificationSettings() {
     UNUserNotificationCenter.current().getNotificationSettings { (settings) in
        guard settings.authorizationStatus == .authorized else { return }
        DispatchQueue.main.async {
            UIApplication.shared.registerForRemoteNotifications()
        }
     }
  }

  func registerForPushNotifications() {
     UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) {
     (granted, error) in
        guard granted else { return }
        self.getNotificationSettings()
        UNUserNotificationCenter.current().delegate = self
     }
  }



  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[GeoSpark sharedInstance] intialize:@"YOUR-SDK-KEY" apiSecret:@"YOUR-SECRET"];
    [self registerForNotifications];
    return YES;
  }

  -(void)registerForNotifications{
    if( SYSTEM_VERSION_LESS_THAN( @"10.0" ) )
    {
        [[UIApplication sharedApplication] registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeSound |    UIUserNotificationTypeAlert | UIUserNotificationTypeBadge) categories:nil]];
        [[UIApplication sharedApplication] registerForRemoteNotifications];
    }
    else
    {
        UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
        center.delegate = self;
        [center requestAuthorizationWithOptions:(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge) completionHandler:^(BOOL granted, NSError * _Nullable error)
         {
             if (granted) {
                 dispatch_async(dispatch_get_main_queue(), ^{
                     [[UIApplication sharedApplication] registerForRemoteNotifications];
                 });
             }
         }];
     }
  }

Inside and didRegisterForRemoteNotificationsWithDeviceToken and didFailToRegisterForRemoteNotificationsWithError methods, add the relevant lines so that GeoSpark can register the device token.


  func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
      let tokenParts = deviceToken.map { data -> String in
            return String(format: "%02.2hhx", data)
        }
        let deviceToken = tokenParts.joined()
      GeoSpark.didRegisterForRemoteNotificationsWithDeviceToken(deviceToken)
  }

  func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
      GeoSpark.didFailToRegisterForRemoteNotificationsWithError(error)
  }


  - (void)application:(UIApplication*)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
 {
    NSString * token = [[[[deviceToken description]
    stringByReplacingOccurrencesOfString: @"<" withString: @""]
    stringByReplacingOccurrencesOfString: @">" withString: @""]
    stringByReplacingOccurrencesOfString: @" " withString: @""];
    [[GeoSpark sharedInstance] didRegisterForRemoteNotificationsWithDeviceToken:token];
 }
  - (void)application:(UIApplication )application didFailToRegisterForRemoteNotificationsWithError:(NSError )error{
    [[GeoSpark sharedInstance] didFailToRegisterForRemoteNotificationsWithError:error];
 }

Inside the didReceiveRemoteNotification method, add the GeoSpark receiver. This method parses only the notifications that are sent from GeoSpark.

	
  func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {

      GeoSpark.didReceiveRemoteNotification(userInfo)
      // Do any additional handling for your app's notifications.
  }
	
  - (void)application:(UIApplication )application didReceiveRemoteNotification:(NSDictionary )userInfo{
    [[GeoSpark sharedInstance] didReceiveRemoteNotification:userInfo];
	    // Do any additional handling for your app's notifications.
  }

Create User

The SDK needs an User ID object to identify the device. The SDK has a convenience method createUser() to create a user which returns User ID.

  
  //Create a User for given deviceToken on GeoSpark Server. 
  GeoSpark.sharedInstance.createUser { (success, error, errorCode, userId) in
        if (error != nil) {
            // Handle createUser API error here
            ...
            return
        }
        if (userId != nil) {
            // Handle createUser API success here
            ...
        }
   }
  
  
   [[GeoSpark sharedInstance] createUser:^(BOOL success, NSError * error, NSNumber * errorCode, NSString * userID) {
        if (error != nil) {
            // Handle createUser API error here
            return;
        }
        if (userID != nil) {
   // Handle createUser API success here
        }
    }];
  

To set an optional description for the user, displayed in the dashboard, call:

  
  GeoSpark.sharedInstance.setDescription(description) 
  
  
  GeoSpark.sharedInstance.description = @"description"; 
  

Get User

If you already have an User ID object. The SDK has a convenience method getUser() to to start the session for the existing user.

Method parameters
Parameter Description
userID User ID from your API Server

  /**
  *Implement your API call for User Login and get back a GeoSpark
  *UserId from your API Server to be configured in the GeoSpark SDK
  *along with deviceToken.
  */

  GeoSpark.sharedInstance.startSessionForUser(userID) { (success, error, errorCode, userId) in
        if (error != nil) {
            // Handle getUser API error here
            ...
            return
        }  
        if (userId != nil) {
            // Handle getUser API success here
            ...
        }
   }

  
   [[GeoSpark sharedInstance] startSessionForUser:@"userID" completion:^(BOOL success, NSError * error, NSNumber * errorCOde, NSString * userID) {
        if (error != nil) {
            // Handle getUser API error here
            return;
        }
        
        if (userID != nil) {
            // Handle getUser API success here
        }

    }];
  

Start Location Tracking

To start tracking the location, use the startLocationTracking() method. You can keep SDK to track location, or turn it off if you want to stop tracking the user at any point of time using the stopLocationTracking() method.

	
  GeoSpark.sharedInstance.startLocationTracking()
	
  
  [[GeoSpark sharedInstance] startLocationTracking];
  

Location Listener

To listen for location client-side in the background, create a class that implements GeoSparkDelegate, then call setDelegate().

Set your GeoSparkDelegate in a codepath that will be initialized and executed in the background. For example, make your AppDelegate implement GeoSparkDelegate, not a ViewController. AppDelegate will be initialized in the background, whereas a ViewController may not be.

	
  class AppDelegate: UIResponder, UIApplicationDelegate, GeoSparkDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {                  
    GeoSpark.sharedInstance.setDelegate = self
     ...
   }
    func didUpdateLocation(_ location: CLLocation, user: GeoSparkUser) {
    // do something with location, user
   }
  }
	
	
  @interface AppDelegate : UIResponder <UIApplicationDelegate,GeoSparkDelegate>

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	...
    [GeoSpark sharedInstance].setDelegate = self;
    return YES;
  }

  - (void)didUpdateLocation:(CLLocation *)location user:(GeoSparkUser *)user{
        // do something with location, user
    }
	

Stop Location Tracking

You can stop tracking the user at any point of time using the stopLocationTracking() method.

	
  GeoSpark.sharedInstance.stopLocationTracking()
	
	
  [[GeoSpark sharedInstance] stopLocationTracking];
	

View Dashboard

Install your app with the GeoSpark SDK on a device and begin tracking on the Dashboard. You would see the user’s current state on the GeoSpark dashboard. If you click on the user, you should be able to view the user's location history.