Requirements

  • iOS 8.0+
  • Xcode 8.0+

Getting your Foursquare API keys

If you do not have a Foursquare API key whitelisted for Pilgrim access, read our guide on Foursquare API Access.


Installation

1. Download and unzip the latest release

While the Pilgrim SDK is in a beta, you must request access from Foursquare.

Request Access

2. Embed the framework

Drag Pilgrim.framework into your project’s Embedded Binaries section in the project editor. In the sheet that appears, make sure “Copy items if needed” is checked, then click Finish.

If you’re using Swift, be sure to import the SDK in your bridging header.

#import "Pilgrim/Pilgrim.h"

3. Install dependencies

The Pilgrim SDK also requires the FSQLocationBroker framework. This can be installed through CocoaPods, Carthage, or manually.


Configure and start Pilgrim

1. Configure Pilgrim in your AppDelegate

Configure Pilgrim by pasting the following code in the didFinishLaunchingWithOptions method of your AppDelegate. Be sure to replace MY_API_KEY and MY_API_SECRET with your real API credentials.

FSQPPilgrimManager.shared().configure(withConsumerKey: "MY_API_KEY", secret: "MY_API_SECRET", delegate: self, completion: nil)

2. Conform to Pilgrim delegate

Have your AppDelegate conform FSQPPilgrimManagerDelegate by pasting the following code just below your AppDelegate class.

extension AppDelegate : FSQPPilgrimManagerDelegate {
    func fsqpPilgrimManager(_ locationManager: FSQPPilgrimManager, didVisit visit: FSQPVisit) {
        // Process the visit however you like here
    }
}

3. Start Pilgrim

Once Pilgrim is configured, you can start running it by calling startMonitoringVisits after the configuration method in your AppDelegate.

FSQPPilgrimManager.shared().startMonitoringVisits()

Note: You must make sure the user has accepted background location permissions before starting the SDK. We provide a convenience method for requesting the ‘Always On’ location permission. However, you are not required to use this method.

FSQPPilgrimManager.shared().requestAlwaysAuthorization { (authorized) in
            if authorized {
                FSQPPilgrimManager.shared().startMonitoringVisits()
            } else {
                // user rejected location permissions
            }
        }

4. Handle a visit

With Pilgrim properly configured, the delegate method should be hit whenever you arrive or depart one of our 105+M places around the world. In order to test your visit callback without physically walking around, we provide a test method fireTestVisitWithConfidence.

This method can be used to test different confidence levels and location types. For example, the follow code will trigger a medium confidence arrival at a venue.

FSQPPilgrimManager.shared().fireTestVisit(with: .medium, locationType: .venue, isDeparture: false)

Tips

Stop Monitoring Visits

The stopMonitoringVisits method should only be called if you need to stop monitoring the user’s visits, for example if they logged out of your app. Repeatedly starting and stopping the SDK will reduce overall accuracy and drain battery.

Battery Monitoring

The PilgrimSDK monitors the device battery in order to suspend background activity if it gets to low. Because of that, you should avoid disabling battery monitoring for your App, or else it will never run. Refrain from making this call: [UIDevice currentDevice].batteryMonitoringEnabled = NO;

Geofences

There is an OS level restriction that limits an app to 20 concurrent geofences - the SDK requires one available geofence to properly function. We strategically use a single geofence to minimize battery consumption. If your app is using geofences, be sure that one available slot is left open for the SDK.

Low Power Mode

If a user puts their device in Low Power Mode, we disable all network calls to help conserve battery. When this happens you won’t be notified of visits in real-time but can be notified of the backfilled visits through the webhook when Low Power Mode is disabled. You should NOT turn off the SDK in Low Power Mode.


Next Steps

You can view the full API reference in the Headers folder of Pilgrim.framework.

Be sure to check out the Advanced Setup Guide for more information on Webhooks, Nearby Venues, and more.

Advanced Setup Guide