Install

Get API keys

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


Set up your Foursquare app

In order for Pilgrim SDK to authenticate with our server, you’ll need to add your iOS Bundle Id to your Foursquare app’s configuration. This can be found in your project’s General tab:

Navigate to your Foursquare app settings page here: foursquare.com/developers/app/CLIENT_ID

  1. Near the bottom of the page, under Install options, paste your iOS Bundle Id in the iOS Bundle IDs field.
  2. Click ‘Save changes’.


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

Permissions

Make sure to turn Background Modes to On in your project’s Capabilities tab and enable the Location updates checkbox:

Add the following to your iOS permission strings in your project’s Info.plist file:

  • Privacy - Location Always Usage Description
  • Privacy - Location Always and When In Use Usage Description
  • Privacy - Location When In Use Usage Description

For example:

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 CLIENT_ID and CLIENT_SECRET with your real API credentials.

PilgrimManager.shared().configure(withConsumerKey: "CLIENT_ID", secret: "CLIENT_SECRET", delegate: self, completion: nil)

2. Conform to Pilgrim delegate

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

extension AppDelegate : PilgrimManagerDelegate {
    func pilgrimManager(_ pilgrimManager: PilgrimManager, handle visit: FSQPVisit) {
        // Process the visit however you like here
    }
}

Note the four delegate callbacks you may receive:

  • handle visit: The primary visit callback that receives arrival and departure events.
  • handleBackfill visit: This callback receives visits that occurred historically when their was no network connectivity or for failed visits that have been retried.
  • handle nearbyVenues: This callback receives any nearby venues that are configured in the pilgrim console.
  • handle geofenceEvents: This callback receives any genfence events configured in the pilgrim console.

3. Start Pilgrim

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

PilgrimManager.shared().start()

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.

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

Handle Visits

With Pilgrim properly configured, the delegate method(s) should be hit whenever you arrive or depart at one of our 105M+ places around the world. In order to test your visit callback without physically walking around, we provide a testing class visitTester. This class can be used to simulate visits with different confidence levels and location types.

For example, the following code will simulate a visit at a given lat/lng.

PilgrimManager.shared().visitTester.fireTestVisit(location: CLLocation(latitude: 37.7904311, longitude: -122.4066613))

The following code will trigger a medium confidence arrival at a venue.

PilgrimManager.shared().visitTester.fireTestVisit(confidence: .medium, type: .venue, departure: false)

Next Steps

Configuration

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 pilgrimsdk-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;