Our Pilgrim SDK v2 is a major update with numerous improvements such as geofences, debug mode, and unified naming. Because the changes are breaking, please use this migration guide to help you move to the new version.


iOS Migration

Changelog Notes

  • Breaking: Authenticate with iOS Bundle Id set in your Foursquare App configuration
  • Breaking: Swift renaming of public facing methods
  • Added a debug view
  • Added support for geofences at venues, categories, or chains
  • Added visitTester to simulate visits at lat/lngs or specific venues
  • API reference documentation

Upgrade Checklist

  1. Add your iOS Bundle Identifier (found in your App’s General tab) to your Foursquare App’s configuration here: https://foursquare.com/developers/app/<CLIENT_ID>
  2. Update your CocoaPods pod spec:
    • Update your podfile to lock in v2: pod 'pilgrim-sdk', '2.0'
    • From your project folder in terminal, update your pod spec: pod repo-art update foursquare
    • Then: pod update pilgrim-sdk
  3. Continue reading this document to familiarize yourself with changes made in v2
  4. Check our iOS API reference docs to ensure all existing code references are updated

Note: Xcode should help you identify Swift classes that have been updated by suggesting auto correction of the class when clicking on the red dot with the error.


Example of Typical Configuration Migration

FSQPPilgrimManager.shared().configure(withConsumerKey: "MY_CLIENT_ID", secret: "MY_CLIENT_SECRET", delegate: self, completion: nil)

FSQPPilgrimManager.shared().requestAlwaysAuthorization { (authorized) in
    if authorized {
        FSQPPilgrimManager.shared().startMonitoringVisits()
    }
}
// Note: delegate is now optional
PilgrimManager.shared().configure(withConsumerKey: "MY_CLIENT_ID", secret: "MY_CLIENT_SECRET", delegate: self, completion: nil)

PilgrimManager.shared().requestAlwaysAuthorization { (authorized) in
    if authorized {
        PilgrimManager.shared().start()
    }
}

Example of Pilgrim Delegate

extension AppDelegate : FSQPPilgrimManagerDelegate {
    func fsqpPilgrimManager(_ locationManager: FSQPPilgrimManager, didVisit visit: FSQPVisit) {
        print "\(visit.isArrival ? "Arrival at" : "Departure from") \(visit.venue != nil ? visit.venue!.name : "somewhere?")"
    }
    func fsqpPilgrimManager(_ locationManager: FSQPPilgrimManager, didBackfillVisit visit: FSQPVisit) {
        print "\(visit.isArrival ? "Backfilled arrival at" : "Backfilled departure from") \(visit.venue != nil ? visit.venue!.name : "somewhere?")"
    }
}
extension AppDelegate: PilgrimManagerDelegate {
    func pilgrimManager(_ pilgrimManager: PilgrimManager, handle visit: Visit) {
        print "\(visit.hasDeparted ? "Departure from" : "Arrival at") \(visit.venue != nil ? visit.venue!.name : "somewhere?")"
    }
    func pilgrimManager(_ pilgrimManager: PilgrimManager, handleBackfill visit: Visit) {
        print "\(visit.hasDeparted ? "Backfilled departure from" : "Backfilled arrival at") \(visit.venue != nil ? visit.venue!.name : "somewhere?")"
    }
}

Breaking API Changes

V1 to V2 Mapping of Changed Classes

For Swift, all classes have have been aliased to be referenced without the FSQP prefix. Examples:

v1 v2
FSQPCategory Category
FSQPPilgrimManager PilgrimManager
FSQPPilgrimManagerDelegate PilgrimManagerDelegate
FSQPVenue Venue
FSQPVenueLocation VenueLocation
FSQPVisit Visit

Note: a full list of available classes and their methods for v2 is available in our API reference documentation.

V1 to V2 Mapping of Changed Event Callbacks

v1 v2
fsqpPilgrimManager:handleVisit PilgrimManager:handleVisit
fsqpPilgrimManager:handleNearbyVenues PilgrimManager:handleNearbyVenues
fsqpPilgrimManager:handleBackfillVisit PilgrimManager:handleBackfillVisit
  PilgrimManager:handleGeofenceEvents

V1 to V2 Mapping of Changed Methods

v1 v2
fireTestVisitWithConfidence visitTester?.fireTestVisit(location: <CLLocation>)
startMonitoringVisits start
stopMonitoringVisits stop
userinfo.setUserInfoData userinfo.setUserInfo
visit.isArrival <removed>
visit.isDeparture visit.hasDeparture

V1 to V2 Mapping of Changed User Info

let userInfo = FSQPUserInfo()
userInfo.setUserId(myCustomUserId)
FSQPPilgrimManager.shared().userInfo = userInfo
PilgrimManager.shared().userInfo.setUserId(myCustomUserId)

Webhook V2

We have fundamentally rebuilt how our webhook works and the payload returned to users. For existing Pilgrim apps, you will need to opt in to turning on v2 of the webhook. You can do this from your https://foursquare.com/developers/app/<CLIENT_ID>/pilgrim console.

We highly encourage people to read more about the changes to begin updating to this new version of the webhook.


Common Issues

Error

If you are not seeing Pilgrim 2.0 in CocoaPods, please make sure to update your pod spec.

Fix

Update your podfile to lock in v2: pod 'pilgrim-sdk', '2.0'. In your project’s folder in terminal, use pod repo-art update foursquare followed by pod update pilgrim-sdk.


Further reading

For full list of current available classes and methods, please refer to our API reference documentation.

You can also checkout our Pilgrim SDK Developer Docs for the most up-to-date documentation.

Android Migration

Changelog Notes

  • Breaking: Authenticate with Android SHA-1 fingerprint set in your Foursquare App configuration
  • Added a debug view
  • Added support for geofences at venues, categories, or chains
  • Added visitTester to simulate visits at lat/lngs or specific venues
  • API reference documentation

Upgrade Checklist

  1. Add your Android SHA-1 fingerprint set in your Foursquare App’s configuration here: https://foursquare.com/developers/app/<CLIENT_ID>
    • keytool -list -v -keystore /dir/to/keystore/signing.keystore -alias release -storepass android -keypass android
  2. Update your build.gradle to use the latest version of Pilgrim SDK:
    • compile 'com.foursquare:pilgrimsdk:2.0.0' or
    • implementation 'com.foursquare:pilgrimsdk:2.0.0'
  3. Continue reading this document to familiarize yourself with changes made in v2
  4. Check our Android API reference docs to ensure all existing code references are updated

Example of Typical Configuration Migration

protected final com.foursquare.pilgrim.PilgrimNotificationHandler sdkNotificationHandler = new com.foursquare.pilgrim.PilgrimNotificationHandler() {
        @Override
        public void handleVisit(Context context, com.foursquare.pilgrim.PilgrimSdkPlaceNotification pilgrimSdkPlaceNotification) {
         }
    };
protected final com.foursquare.pilgrim.PilgrimNotificationHandler sdkNotificationHandler = new com.foursquare.pilgrim.PilgrimNotificationHandler() {
        @Override
        public void handleVisit(Context context, com.foursquare.pilgrim.PilgrimSdkVisitNotification pilgrimSdkVisitNotification) {
         }
    };

Breaking API Changes

V1 to V2 Mapping of Changed Classes

v1 v2
CurrentPlace Visit
RegionType LocationType

Note: a full list of available classes and their methods for v2 is available in our API reference documentation.

V1 to V2 Mapping of Changed Event Callbacks

v1 v2
handlePlaceNotification handleVisit
handleNearbyNotification handleNearbyVenues
handleBackfillNotification handleBackfillVisit
handleGeofenceNotification handleGeofenceEvents

V1 to V2 Mapping of Changed Methods

v1 v2
sendNotification PilgrimNotificationTester.fireTestVisit
sendConnectedTestNotification PilgrimNotificationTester.sendConnectedTestVisit
clear clearAllData
getLogs getDebugLogs
getPilgrimInstallId getInstallId
enablePersistentLogs enableDebugLogs
visit.hasExited visit.hasDeparted

Note: new and existing test functions can be found the PilgrimNotificationTester class.


Webhook V2

We have fundamentally rebuilt how our webhook works and the payload returned to users. For existing Pilgrim apps, you will need to opt in to turning on v2 of the webhook. You can do this from your https://foursquare.com/developers/app/<CLIENT_ID>/pilgrim console.

We highly encourage people to read more about the changes to begin updating to this new version of the webhook.


Further reading

For full list of current available classes and methods, please refer to our API reference documentation.

You can also checkout our Pilgrim SDK Developer Docs for the most up-to-date documentation.