Install

Get API keys

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


Setup Cocoapods

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:

Install SDK

Then you can use install as usual

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.

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

Handle Visits

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)

Overview

Embed the most sophisticated contextual awareness engine into your app, providing a persistent background awareness feature enablement and a deeper understanding of your customers.

Min Operating System 8.0+
Xcode Version 8.0+
Support pilgrim-sdk-support@foursquare.com

Code Examples

Test Visit

Test a visit by firing a test visit e.g. from your AppDelegate or from a ViewController.

import UIKit
import Pilgrim

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        FSQPPilgrimManager.shared().fireTestVisit(with: .medium, locationType: .venue, isDeparture: false)
    }

}

Visit Feedback

Provide visit feedback.

/**
 *  @param pVisitId         The visit ID to provide feedback for.
 *  @param feedback         See FSQPVisitFeedback for options.
 *  @param actualVenueId    If the correct Foursquare venue ID is known, let pilgrim know.
 *  @param completion       A completion handler called when the transaction finishes.
 */
- (void)provideFeedbackForPVisit:(NSString *)pVisitId feedback:(FSQPVisitFeedback)feedback actualVenueId:(nullable NSString *)actualVenueId completion:(nullable void (^)(NSError * _Nullable error))completion;
/**
 *  @param pVisitId         The visit ID to provide feedback for.
 *  @param feedback         See FSQPVisitFeedback for options.
 *  @param actualVenueId    If the correct Foursquare venue ID is known, let pilgrim know.
 *  @param completion       A completion handler called when the transaction finishes.
 */
- (void)provideFeedbackForPVisit:(NSString *)pVisitId feedback:(FSQPVisitFeedback)feedback actualVenueId:(nullable NSString *)actualVenueId completion:(nullable void (^)(NSError * _Nullable error))completion;