Pilgrim Reference

Pilgrim SDK

Pilgrim is a location intelligence framework by Foursquare Inc.

Build Status

Dependencies

Installation

  1. brew install swiftlint
  2. carthage bootstrap --use-xcframeworks --platform ios
  3. Run fastlane match (passwords are in 1Password DCX-Mobile vault (FASTLANE_PASSWORD is in devbeast, match passwords are in Match iOS password):
FASTLANE_PASSWORD=# MATCH_PASSWORD=# MATCH_KEYCHAIN_PASSWORD=# bundle exec fastlane run_match

Deployment

For internal releases use the format vX.X.X-rcX. External releases should look like vX.X.X. NOTE: Internal releases must have a -rc else the framework will be made available to the public!

You can find more detailed docs on everything that needs to be done for a release on the wiki.

Installation

Carthage

Add the following to your Cartfile where X.X.X-rcX refers to the latest internal release.

binary "https://foursquare.jfrog.io/foursquare/foursquare-internal/Pilgrim.json" ~> X.X.X-rcX

CocoaPods

Add the following to your Podfile where X.X.X-rcX refers to the latest internal release.

pod 'Pilgrim', '~> X.X.X'

Manual

Download a copy of the internal SDK from Artifactory where X.X.X-rcX refers to the latest internal release.

https://foursquare.jfrog.io/foursquare/foursquare-internal/vX.X.X-rcX

For more detailed steps take a look at our Quickstart Guide

Getting Started

In the simplest case, you will have your application delegate implement the FSQPPilgrimManagerDelegate protocol, configure and start Pilgrim. Note that it is not required to be on the application delegate, but we are using that here as an example.

import Pilgrim

class AppDelegate: UIResponder, UIApplicationDelegate, FSQPPilgrimManagerDelegate {
    let consumerKey = "insert here"
    let consumerSecret = "insert here"
    let locationManager = CLLocationManager()

func application(application: UIApplication,
                    didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        FSQPPilgrimManager.sharedManager().configureWithConsumerKey(consumerKey,
            secret: consumerSecret,
            delegate: self,
            completion: nil)

switch CLLocationManager.authorizationStatus() {
        case .authorizedAlways: FSQPPilgrimManager.sharedManager().startMonitoringVisits()
        case .notDetermined: locationManager.requestAlwaysAuthorization()
        default: break
        }

return true
    }

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

Also note that requestAlwaysAuthorizationWithCompletion is provided for convenience; you can call startMonitoringVisits at any time after you’ve requested location permission, and you are not required to use our convenience method for requesting permission.

Usage

Important:

startMonitoringVisits() should be called to kickstart the Pilgrim engine when the user is logged into your app, and stopMonitoringVisits() when the user is logged out.

Adding custom Triggers

There are a few different ways to customize the notifications that Pilgrim sends your app and these are done through Triggers.

You can configure you triggers on the developer site. https://foursquare.com/developers/app/. There you will be able to add triggers for places, categories and chains and a different confidence level.

The default Trigger set for the SDK will notify you of all stops at MEDIUM and above.

Also available on the developer site, is the option to change the notification for home and work, and whether or not you are notified on departures.

Server to server notifications

If you would like to have your visits sent directly to your servers, you can configure an endpoint to be hit on arrival and departure of your users. With the SDK you can specify your own custom parameters that will be sent along with the request. For more information please contact your Technical Account Manager.

Permissions

You must have UIBackgroundModes location and a NSLocationAlwaysUsageDescription in your Info.plist.

You must prompt the user for “Always” location permissions using CLLocationManager().requestAlwaysAuthorizationWithCompletion() to request this.

The SDK will take 3 days of running to determine the users home/work location. It’s possible that you won’t want to use notifications before they have a home/work set, and if that is the case you can check the state when you get a notification from the SDK by checking FSQPPilgrimManager‘s hasHomeOrWork property.

Provide visit feedback

You may provide feedback on venue visits with FSQPVisitFeedbackProvider, which is available through FSQPPilgrimManager’s visitFeedbackProvider property. A Foursquare venue id can optionally be included to identify a wrongly-flagged venue.

The available feedback options are:

public enum FSQPVisitFeedbackProvider : Int {
    case Confirm
    case FalseStop
    case WrongVenue
    case Deny
}

Feedback is used to make long-term improvements to our algorithms.