• 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.


1. Download and unzip the latest release

Foursquare must whitelist your app to enable access to the Pilgrim SDK.

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
    func fsqpPilgrimManager(_ locationManager: FSQPPilgrimManager, didBackfillVisit visit: FSQPVisit) {
        // Process the backfilled visit however you like here

Note the two delegate callbacks you may receive:

  • didVisit: The primary visit callback that receives arrival and departure events.
  • didBackfillVisit: This callback receives visits that occurred historically when their was no network connectivity or for failed visits that have been retried.

3. Start Pilgrim

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


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 {
            } 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)


Stop Monitoring Visits

If you need to stop monitoring the user’s visits, for example if they opt out or turn off your background feature, you can turn off the Pilgrim SDK by calling:


This will stop all Pilgrim activity. To resume Pilgrim, just call startMonitoringVisits() again. Repeatedly starting and stopping the SDK will temporarily reduce accuracy and drain battery.

Clearing All History

In certain instances, you may want to clear a users visit history entirely from the device, including their Home and Work locations. An example of this may be a user logging out of your app. For this you should use:

FSQPPilgrimManager.shared().clearAllVisitHistory(completion: nil);

Note: You cannot call this when monitoring visits. You must call stopMonitoringVisits first.

Battery Monitoring

The Pilgrim SDK monitors the device battery in order to suspend background activity if it gets too 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;


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