• iOS 8.0+
  • Xcode 8.0+

Getting your Foursquare API keys

To use Pilgrim SDK, Foursquare must whitelist your app to enable access to the Pilgrim SDK. If you have not already, please read our guide on Pilgrim SDK Access.


Install using CocoaPods

Once your app has been enabled access to Pilgrim SDK, you will have been given a username and password from Foursquare, which will give you can access to the repository that has the Pilgrim SDK.


In order to use CocoaPods you will need to install the ‘cocoapods-art’. plugin. To install cocoapods-art run the following command

repo-art uses authentication as specified in your standard netrc file. Create the netrc file in your home directory

Then add the your login credentials like below using your favorite text editor

To add the Pilgrim specs repo run the following command

To resolve pods from the Pilgrim specs repo that you added, you must add the following to your Podfile:

Then you can use install as usual


To update first update the Pilgrim specs repo

Then you can use update as usual.

Install manually

1. Download and unzip the latest release

Once your app has been enabled to use Pilgrim SDK, the Foursquare team will provide you with instructions for accessing the latest Pilgrim SDK. If you do not wish to use CocoaPods, we can also supply you with a zip file that you can use to manually install the framework into your project.

Reminder: Foursquare must whitelist your app to enable access to the Pilgrim SDK. If you do not have access:

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.

Swift-Bridging-Header.h Obj-C

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.

2. Conform to Pilgrim delegate

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

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.

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.


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 how to provide visit confirmation feedback to help make Pilgrim more accurate:

Visit Feedback