iOS Monitor App Quick Start

The ARRIVE SDK provides a way to integrate with your monitor applications and to notify you when users are arriving, view ETAs, and perform other actions. The monitor app does not generate location data like your mobile app does.

The following information will help you integrate the ARRIVE SDK with your monitor app using Xcode and Objective-C or Swift.

Before continuing, follow the instructions to integrate ARRIVE SDK with your mobile app.

Requirements

Build an App

  1. Set up your app
  2. Integrate the SDK
  3. Add site-arrival tracking
  4. Get tracking errors

Step 1: Set up your app

Install ARRIVE SDK with CocoaPods

The recommended way to install the SDK is to use CocoaPods:

  1. Add pod 'Curbside' to your podfile.
  2. Run pod install from the command line for the initial installation.
  3. Close any current Xcode sessions and use YOUR_APPS.xcworkspace for this project from now on.

Enable Background Modes

  1. From the Project Navigator, select your project.
  2. Select your target.
  3. Select Capabilities.
  4. Scroll down to Background Modes.
  5. Check Location updates and Background fetch.

Image of background modes

Step 2: Integrate the SDK

Import Header File

Import the Curbside SDK header file into your app’s delegate .m file and any other place that you plan to use it.

@import Curbside;
import Curbside

Get an API Key and Secret

When you are ready to move your app into production, check Production to create a separate usage key for production.

Your mobile and monitor apps must use the same environment.

Initialize the SDK

Initialize CSMonitoringSession with an API key and secret:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Monitoring Client
    CSMonitoringSession *sdksession = [CSMonitoringSession createSessionWithAPIKey:@"YOUR_API_KEY" secret:@"YOUR_SECRET_KEY" delegate:nil];
    
    // Call sessions method application:didFinishLaunchingWithOptions:
    [sdksession application:[UIApplication sharedApplication] didFinishLaunchingWithOptions:launchOptions];

    return YES;
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool
{
    // Monitoring Client
    let sdksession = CSMonitoringSession.createSession(withAPIKey: "YOUR_API_KEY", secret: "YOUR_SECRET_KEY", delegate: nil)
    
    // Call sessions method application:didFinishLaunchingWithOptions:
    sdksession.application(UIApplication.shared, didFinishLaunchingWithOptions: launchOptions)

    return true
}

Step 3: Add site-arrival tracking

Setting the Logged-in Associate

CSMonitoringSession requires a unique tracking identifier for each logged-in site associate or employee. This identifier enables Curbside to track and attribute actions on a trip to the associate. Set the trackingIdentifier of the CSMonitoringSession to the associate’s or the employee’s identifier:

[CSMonitoringSession currentSession].trackingIdentifier = @"MONITOR_USER_UNIQUE_TRACKING_ID";
CSMonitoringSession.current().trackingIdentifier = "USER_UNIQUE_TRACKING_ID"

The parameters above can be set when the associate logs into your monitor application and should be set to nil when the associate logs out.

Subscribing to arrival events

To start tracking arrivals at the site and to receive location updates for users of your mobile app, set the current site and a status update handler on CSMonitoringSession. To receive errors when using CSMonitoringSession, see the section on Get Tracking Errors.

[CSMonitoringSession currentSession].statusesUpdatedHandler = ^(NSArray<CSUserStatusUpdate *> *userStatusUpdates) {
    // Process User location updates in the app.
};
[[CSMonitoringSession currentSession] startMonitoringArrivalsToSiteWithIdentifier:@"SITE_ID"];
CSMonitoringSession.current().statusesUpdatedHandler = { userStatusUpdates in
    // Process User location updates in the app.
}
CSMonitoringSession.current().startMonitoringArrivalsToSite(withIdentifier: "SITE_ID")

When there are user status updates, the statusesUpdatedHandler will be called with updated information. Each object in the array is an instance of CSUserStatusUpdate that represents information about your mobile app users.

for (CSUserStatusUpdate *statusUpdate in userStatusUpdates) {
    NSString *userID = statusUpdate.trackingIdentifier;
    CLLocation *userLocation = statusUpdate.location;
    int userDistanceInMeters = statusUpdate.distanceFromSite;
    int estimatedArrivalInSeconds = statusUpdate.estimatedTimeOfArrival;
    
    CSUserStatus userStatus = statusUpdate.userStatus;
}
for statusUpdate in userStatusUpdates {
    let userID = statusUpdate.trackingIdentifier
    let userLocation = statusUpdate.location
    let userDistanceInMeters = statusUpdate.distanceFromSite
    let estimatedArrivalInSeconds = statusUpdate.estimatedTimeOfArrival
    
    let userStatus = statusUpdate.userStatus
}

The code snippet above lists some properties available on CSUserStatusUpdate.

The update provides information about each user’s current location, how far the user is from the site, and the user’s estimated time of arrival. In addition, you can query the user status to determine if the user is in transit, approaching, or has arrived at the site.

There is a special user status called CSUserStatusUserInitiatedArrived which indicates that users have confirmed that they are at the site. The monitor app can receive this status if your mobile app implements the CSUserSessionDelegate -session:canNotifyMonitoringSessionUserAtSite: method.

Stop Tracking Arrivals

When a user has arrived on-site, and you no longer need to track them for a given track token, you can stop your mobile app from sending location data by calling the following method to complete the user trip. The track token(s) identifies the trip(s) being stopped. If the “trackTokens” array is empty or nil, then all trips for the user to the site will be stopped:

[[CSMonitoringSession currentSession] completeTripForTrackingIdentifier:@"CUSTOMER_TRACKING_ID" trackTokens:@[trackToken]];
CSMonitoringSession.current().completeTrip(forTrackingIdentifier: "CUSTOMER_TRACKING_ID", trackTokens: ["token"])

To calculate wait time, see Measure Wait Time.

Cancel Tracking Arrivals

Use cancel tracking when the user will not continue to the site and is not completing the trip. Like the complete tracking method, once you call this method, your mobile app will stop sending location data for the given track token(s). The track token(s) identify the trip(s) being cancelled. If the “trackTokens” array is empty or nil, then all trips for the user to the site will be cancelled.

[[CSMonitoringSession currentSession] cancelTripForTrackingIdentifier:@"USER_UNIQUE_TRACKING_ID" trackTokens:@[trackToken]];
CSMonitoringSession.current().cancelTrip(forTrackingIdentifier: "USER_UNIQUE_TRACKING_ID", trackTokens: ["token"])

Step 4: Get tracking errors

If there was an error on the session, the delegate will receive a callback with the error cause. For a complete list of errors, see the CSErrorCode documentation.

To receive notifications when errors occur, set the delegate on CSMonitoringSession, conform to CSMonitoringSessionDelegate, and implement the error callback method. The following code snippets assume that you will be using ViewController as the CSMonitoringSession’s delegate.

Set the delegate on CSMonitoringSession in viewDidLoad.

[CSMonitoringSession currentSession].delegate = self;
CSMonitoringSession.current().delegate = self

Conform to CSMonitoringSessionDelegate.

// In ViewController.m
@interface ViewController () <CSMonitoringSessionDelegate>

@end
// Place this at the end of ViewController.swift outside of your ViewController class scope.
extension ViewController: CSMonitoringSessionDelegate {

}

Implement the error callback method.

- (void)session:(CSMonitoringSession *)session encounteredError:(NSError *)error
{
    NSLog(@"Error: %@", error.localizedDescription);
}
func session(_ session: CSMonitoringSession, encounteredError error: Error) {
    print("Error: \(error.localizedDescription)")
}