1. I’m not receiving any notifications
  2. I’m only receiving notifications at a percentage of the venues I visit
  3. What do the different confidence levels mean?
  4. How large is the SDK Framework?
  5. What is the minimum OS for Pilgrim?
  6. Does the iOS SDK use the region monitoring framework for geofencing?
  7. I’m receiving an “Unsupported Architectures” error when submitting to Apple! Help
  8. Apple is rejecting my app for having Always On location

I’m not receiving any notifications

First, try firing a test notification locally on app start and verify that the Pilgrim notification handler is being called. If the notification handler is not being called, insure everything is configured properly for iOS and Android

If the Pilgrim notification handler is called when you fire a test notification but not in real life visits, verify the SDK is configured with the appropriate client Id and secret for your Pilgrim enabled Foursquare app. You can check if your client Id is Pilgrim enabled by accessing the Pilgrim console at https://foursquare.com/developers/app/YOUR_CLIENT_ID/pilgrim

Also read I’m only receiving notifications at a fraction of the venues I visit

I’m only receiving notifications at a percentage of the venues I visit

If you’re only receiving notifications at a percentage of the venues you visit there are a few things you should check in your Pilgrim console configuration. You can access your pilgrim console at https://foursquare.com/developers/app/YOUR_CLIENT_ID/pilgrim

  1. Is the Venue triggers Minimum confidence is set to All? This will ensure that a notification is sent from our servers regardless of the confidence level. We recommend using this setting for testing until you are are familiar with the observed accuracy of the different confidence levels. Read more about confidence levels here

  2. Ensure all of the notification settings are on and venue triggers is set to All venue types. Read more about notification settings here.

What do the different confidence levels mean?

The minimum confidence level that triggers a Pilgrim notification can be set from your Pilgrim console. Available settings are None, Low, Medium and High that translate to <70%, 70%, 80% and 90%, respectively. Depending on your use case, it may make sense to use a confidence level that is higher or lower. For testing purposes, we recommend setting the confidence to All. Setting the confidence to All will trigger a pilgrim notification for every stop - even if it’s below the Low confidence threshold. While testing you can observe the confidence level of notifications to decide on the level that is most suitable for your app.

For reference, the Foursquare app uses a confidence level of Medium or above to send users push notifications.

How large is the SDK Framework?

The compressed framework size is 248K on Android and 0.7MB on iOS once stripped down to device architectures.

What is the minimum OS for Pilgrim?

The Pilgrim SDK requires v15 (ICE_CREAM_SANDWICH_MR1) for Android and iOS8+.

Does the iOS SDK use the region monitoring framework for geofencing?

While the SDK does not use geofences to detect entrances to POIs, it does use the iOS region monitoring framework to set a single iOS geofence while the user is stationary to shut down background location usage, to improve battery efficiency. The geofence will be removed when the user leaves their stationary location.

In order to do this, the SDK needs there to be one geofence slot available for use. At the time of writing, iOS gives each app 20 geofences to use, so we would request that you allow your app to add at most 19 geofences. If there are no available slots for the Pilgrim SDK, it will still work but you can expect the exit notifications to be inaccurate and the SDK may miss visits close to the original. Lastly, when you are modifying your geofences, take care to not remove a geofence that Pilgrim has added. All the Pilgrim geofences should start with the identifier FSQPLS, so that you can leave those in place.

I’m receiving an “Unsupported Architectures” error when submitting to Apple! Help

This error is because you’re trying to submit a build with an x86_64 architecture included -, the x86_64 architecture is there so you can run Pilgrim apps in the simulator. If you’re using Carthage, this can usually be solved by including /usr/local/bin/carthage copy-frameworks in your Run Script and adding $(SRCROOT)/Carthage/Build/iOS/Pilgrim.framework as an input file.

If that still doesn’t work there is another handy little run script that loops through frameworks to remove ones that aren’t required - paste into your projects Build Phases > Run Scripts


# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)


for ARCH in $ARCHS

echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"

echo "Replacing original executable with thinned version"


Apple is rejecting my app for having Always On location

This happens occasionally, even for apps that have previously passed App Store review with background location enabled. It’s almost always resolved on appeal. Apple is looking for explanations in general on what background location is being used for and why it is required to power the user experience. Let us know if you’re getting blocked here and we will do what we can to help.

To file an appeal with Apple, head over here.

To prevent future submissions from being rejected, it’s helpful to leave an explanation about how background location is used in the app in the Review Notes field. An example we use in Foursquare:

Foursquare uses background location to send users contextually relevant push notifications when they visit a place, like “At In-N-Out Burger? Make sure to order your burger animal style”, and to help users keep track of places they visit in the History tab.

Below are a few standard questions we have seen from Apple before on Pilgrim-enabled apps.

Please revise your app to include features that require the persistent use of real-time location updates while the app is in the background.

Apple reviewers do not normally have the ability to see your functionality in use since it requires people to be out and about to get your content. Explaining the functionality to them in a appeals process is generally the way to resolve this issue. Your app description also needs to have the phrase “continued use of GPS running in the background can dramatically decrease battery life”. Here is a sample from the Foursquare app.

We’ve spent years developing the location technology that powers Foursquare, making it extremely power efficient. But, as with all apps of this type, please note that continued use of GPS running in the background can dramatically decrease battery life.

Does this app detect startMonitoringForRegion:, startRangingBeaconsInRegion:, or both?

Pilgrim uses both, we use region monitoring, significant location changes, and iBeacons to minimize the amount of time spent and power used with continuous location updates turned on. After we detect a user has entered a new venue we turn continuous location monitoring off to conserve power and re-enable after we estimate the user has left that venue.

What is the user experience when the app detects the presence of a beacon?

Pilgrim uses beacon detection as an additional input signal - if we see a beacon when we request input from the phones sensors we will capture this and feed it into our location detection algorithms. Simply stated - if there’s a beacon there it helps us more accurately snap a user to venue.

Background location and Beacons are fairly independent here in the sense that the use of beacons does not necessitate background location, rather beacons are used to reduce the amount of background location used. Our SDK does read iBeacons, however background location needs to be enabled to function regardless of beacons being present.