iOS App Quick Start

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

Requirements

  • iOS 8.0 and above
  • Location Services permissions set to Always (more details below)
  • Background App Refresh

Create an account

You’ll need to create an account to complete the steps below. Already have an account? Sign in

Build an app

  1. Set up your app
  2. Integrate the SDK
  3. Ask for Location Services permissions
  4. Add a Site
  5. Start and cancel trips
  6. Test your app

Step 1: Set up your app

Install the SDK with CocoaPods

The recommended way to install the SDK is using 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 ARRIVE SDK header file into your app’s delegate file and in any other place that you plan to use it:

@import Curbside;
import Curbside

Initialize the SDK

Initialize CSUserSession with a usage token.

Get a Usage Token

If your app will be used in production, check Production token when you get your usage token. You can manage and get more usage tokens in your account at Account > Access > Usage Tokens. Your mobile and monitor apps must use the same environment.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // User Session Clients
    CSUserSession *sdksession = [CSUserSession createSessionWithUsageToken:@"YOUR_USAGE_TOKEN" delegate:nil];

    // Call sessions method application:didFinishLaunchingWithOptions:
    [sdksession application:[UIApplication sharedApplication] didFinishLaunchingWithOptions:launchOptions];

    return YES;
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool
{
    // User Session Clients
    let sdkSession = CSUserSession.createSession(withUsageToken: "YOUR_USAGE_TOKEN", delegate: nil)

    // Call sessions method application:didFinishLaunchingWithOptions:
    sdkSession.application(UIApplication.shared, didFinishLaunchingWithOptions: launchOptions)

    return true
}

Step 3: Ask for Location Services permissions

The ARRIVE SDK makes use of Location Services. The SDK needs Always authorization for ARRIVE to work. If your app did not ask the user for the required permission, you need to add a usage description to your app’s Info.plist before requesting permission. The usage description explains why the application requires Always authorization.

Xcode 9

Location Services permissions changed in iOS 11: you now have two opportunities to ask for permission. if you first ask for While in use location access, you can then decide later to ask the user to grant Always location access.

Apple recommends that apps start with While in use location access as their base experience. Apps should only prompt users to grant Always location access after they have had a chance to explore the app and encounter a feature where Always location access is beneficial.

Here are the steps to add usage descriptions to your app’s Info.plist

  1. Open your app’s Info.plist file.
  2. Add an entry named Privacy - Location Always and When In Use Usage Description. The equivalent raw key name is NSLocationAlwaysAndWhenInUseUsageDescription. Use To get accurate GPS locations as the description.
  3. Add an entry named Privacy - Location When In Use Usage Description. The equivalent raw key name is NSLocationWhenInUseUsageDescription. Use To get accurate GPS locations as the description.

Image of background modes

Xcode 8

Here are the steps to add usage description to your app’s Info.plist

  1. Open your app’s Info.plist file.
  2. Add an entry named Privacy - Location Always Usage Description.
  3. The equivalent raw key name is NSLocationAlwaysUsageDescription. Use To get accurate GPS locations as the description.

Image of background modes

Step 4: Add a Site

A site is a physical location near a road network and is the destination for a trip. It is usually (but not necessarily) a store, a restaurant, or a place of business. To track trips to a site, you must add that site to your account. When you add a site, you create a site ID, which you will use in your app when you add trip tracking.

Step 5: Start and cancel trips

Start Trips

Curbside requires that a unique tracking identifier be issued for each user. This unique value is used by ARRIVE to identify the user. It should be the same across all logins from the same user, and across multiple devices. Once the user is logged in, you should use the following property to identify the user:

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

When the user logs out, use the same property, and set its the value to nil as in:

[CSUserSession currentSession].trackingIdentifier = nil;
CSUserSession.current().trackingIdentifier = nil

After setting the tracking identifier, the app is ready to start tracking the user. Use the following method on CSUserSession with a SITE_ID and trackToken:

[[CSUserSession currentSession] startTripToSiteWithIdentifier:@"SITE_ID" trackToken:@"UNIQUE_TRACK_TOKEN"]
CSUserSession.current().startTripToSite(withIdentifier: "SITE_ID", trackToken: "UNIQUE_TRACK_TOKEN")

SITE_ID is the unique identifier for a site where users will arrive. You create the Site ID when you add a site to your account.

UNIQUE_TRACK_TOKEN is the unique identifier for a trip. A track token is needed to start tracking each user. The track token has a maximum of 60 characters.

  • If your site accepts orders, you can use your order ID as a track token. Appointment or confirmation numbers can also be used in situations where no orders are placed.
  • Track tokens are passed to the monitor app.

Note: This call checks to make sure the app has all the permissions needed for the ARRIVE SDK to report locations. If CSUserSession fails to start tracking for the site, the SDK will report errors in CSUserSessionDelegate. See the reference docs for more information on what caused the failure. For ARRIVE to work correctly, the app must use the following settings:

  1. Location Access Settings: Always
  2. Background App Refresh: Enabled

Cancel Trips

If the trip completes all the way through the system (that is, the monitor app is also integrated with ARRIVE), then tracking for the site will stop automatically when the pickup is completed.

If the user is cancelling the trip in your app and there is no active trip at the given site, call the following method to cancel the trip:

[[CSUserSession currentSession] cancelTripToSiteWithIdentifier:@"SITE_ID" trackToken:nil];
CSUserSession.current().cancelTripToSite(withIdentifier: "SITE_ID", trackToken: nil)

CSUserSessionDelegate

The CSUserSessionDelegate has various methods to inform you of key events. We recommend the following two methods: encounteredError 'Curbside' in the Understanding Tracking Errors section to receive notifications if errors occur. canNotifyMonitoringSessionUserAtSite 'Curbside' in the User confirming they arrived section to confirm that a user has arrived at a site.

To receive CSUserSessionDelegate Callbacks

Adopt CSUserSessionDelegate protocol. If your class already adopts other protocols, you can add commas (,) between the protocols.

Understanding Tracking Errors

If there was an error completing an action on the tracker, the CSUserSessionDelegate will get a callback with the error cause. For a complete list of errors, see to the CSErrorCode documentation.

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

User confirming they arrived

The CSUserSessionDelegate provides a callback method when a user is near a site being tracked. This method is executed when the app is launched or resumed. We suggest using it to enable a button that the user can click to confirm they are on-site.

- (void)session:(CSUserSession *)session canNotifyMonitoringSessionUserAtSite:(CSSite *)site
{
    // Show/enable notify button
}
func session(_ session: CSUserSession, canNotifyMonitoringSessionUserAt site: CSSite) {
    // Show/enable notify button
}

The following method can be called to inform the user of the monitor app at the site that the user confirms they are on-site. It is up to individual developers to decide how they want to use this functionality.

[[CSUserSession currentSession] notifyMonitoringSessionUserOfArrivalAtSite:site];
CSUserSession.current().notifyMonitoringSessionUserOfArrival(at: site)

Step 6: Test your app

The ARRIVE SDK should now be fully integrated in your app. Run the app and view your dashboard to start seeing trips as they are being tracked. You’re done!

If you are receiving errors, see the error code documentation to help you troubleshoot.

Next Steps