General

  1. What’s the difference between Snap-to-Place and geofencing?
  2. Does Pilgrim require background location permissions?
  3. How large is the SDK Framework?
  4. What are the minimum requirements for Pilgrim?
  5. How do I remove my data from Pilgrim?
  6. How do I send custom user data to another server or service?
  7. What are the different ways to receive Pilgrim events?

Free Tier

  1. I’m interested in the free tier of Pilgrim SDK. Where can I apply for access?
  2. What usage requirements must be met in order to qualify for the free tier of Pilgrim SDK?
  3. Where can I inquire about the status of my application?
  4. What are the monthly active user limits for the free version of the SDK?
  5. What happens when a Pilgrim SDK free tier account hits their MAU limit?
  6. Do we store any user data collected from free tier partners?
  7. You mentioned that free tier partners may be audited to ensure they are using the SDK appropriately. What are the details of the audit?

Snap-to-Place Stop Detection

  1. Why am I seeing “Error simulating visit” in debug mode?
  2. Why am I not receiving any notifications?
  3. Why am I only receiving notifications at a percentage of the venues I visit?
  4. What do the different confidence levels mean?
  5. How does Home/Work detection work?

Geofencing

  1. What is Foursquare’s geofencing solution?
  2. Can I use geofencing in addition to Pilgrim Stop Detection?
  3. What are the benefits of geofencing?
  4. When should I use geofences?
  5. How do I enable and set up geofencing?

Segments

  1. What are Pilgrim segments?
  2. How do I get access to segments?
  3. What segments are currently available?
  4. Where can I learn more about segments?

iOS

  1. Why do I need to configure Pilgrim in the AppDelegate?
  2. Does the iOS SDK use the region monitoring framework for geofencing?
  3. Apple is rejecting my app for having Always On location
  4. I’m receiving an “Unsupported Architectures” error when submitting to Apple. Help!
  5. How do I integrate the SDK now that Artifactory is not supported?

Android

  1. Why do I need to put the Pilgrim builder in the application’s onCreate?
  2. What permissions does Pilgrim add to my manifest?

What’s the difference between Pilgrim’s Snap-to-Place and geofencing?

Pilgrim is the most comprehensive location awareness engine that helps your app to engage users with contextually relevant and geo-aware content. Pilgrim SDK has multiple features that help provide this location-based awareness: stop detection (a device is “here”) and geofencing (a device’s GPS has crossed a specific threshold). Stop detection uses Foursquare’s Snap-to-Place intelligence to attempt to accurately identify when a user has entered and stopped at a specific location (using the place shapes of the 105M+ POIs from the Foursquare Venues Database). Geofencing is a bit simpler of a technology that can tell you when a device’s GPS has entered, exitted, or remained within a place for a certain amount of time (dwell).

Does Pilgrim require background location permissions?

By default, Pilgrim SDK runs in the background and pushes you visits when it detects a stop or when you cross a geofence threshold. But you can also actively request the current location manually when the app is in use as a workaround to satisfy our SDK’s background location permission requirements. Further documentation can be found for iOS and Android.

How large is the SDK Framework?

As of 2.1.2, the compressed framework size is 393.87 KB on Android and 696 KB on iOS once stripped down to device architectures.

What are the minimum requirements for Pilgrim?

The Pilgrim SDK requires v16 (Jelly Bean) for Android and iOS 8+.

How do I remove my data from Pilgrim?

SDK developers can request the removal of user data from our system via two methods. Both methods require the submission of the install IDs associated with the accounts for which you would like removed. These install IDs have been provided to you by Pilgrim and it is your responsibility as the app developer to provide these install IDs to Foursquare in order for us to properly remove the user’s data records. An example install id would be: 2B82C786-7BB8-4601-9A86-372417AAD4AC

The first method of requesting data removal is by submitting a form through your app’s developer console. This form will accept up to 1000 install IDs at a time and the list is comma delimited.

The second method is via our erasureRequest endpoint, which documents how to request data removal for an account directly from your app using our API.

How do I send custom user data to another server or service?

On occasion, you may want to send custom user data into Pilgrim to pass along to another server or service. This is common if you want to tie a Pilgrim event to a specific user in your own database or in a third-party MMA integration. Once set, the custom user data will be passed along within our webhook payload. For implementation directions, please refer to our documentation.

What are the different ways to receive Pilgrim events?

Pilgrim delivers visit and geofence events in a few ways:

  1. To the client (phone) via event callbacks in the SDK.
  2. To a server via webhook configuration.
  3. To third-party integrations.

If you need data delivered in a way that is not listed above, please contact us.


I’m interested in the free tier of Pilgrim SDK. Where can I apply for access?

Developers can get access to the free tier of the SDK by following these three steps:

  1. Create a developer account at developer.foursquare.com
  2. Complete the free tier application by creating a new app (Note: Expect a response within 2-3 business days)
  3. Start building on top of the industry’s leading location tech platform

What usage requirements must be met in order to qualify for the free tier of Pilgrim SDK?

Because location technology is a powerful tool, we believe that location-aware mobile applications should always ensure:

  • Consumer value related to location
  • Transparency and clear consent
  • Consumer protection

As such, we require that applicants meet the requirements below to be eligible for the free tier of Pilgrim. These requirements include but aren’t limited to:

  • Privacy: Licensee shall post a privacy policy to users of the app compliant with all applicable laws, rules, regulations and industry standards that clearly discloses how Licensee collects, uses, stores and discloses user data.
  • Use case: Licensee must use the SDK for purpose that was described and approved by Foursquare through the application process.
  • Data security: Foursquare data should only be passed to vendors already approved by Foursquare. Additionally, location data should be secured using industry standard administrative, technical, and organizational security.

To see our thorough list of our do’s and don’ts, check out our Terms of Use.

Where can I inquire about the status of my application?

The Foursquare team will be evaluating applications in the order they’re submitted. While we aim to deliver a response within 2-3 business days, response times may be a bit longer. Email us at developers@foursquare.com with any questions or concerns.

Thanks for your patience—we’ll get to your application as soon as possible!

What are the monthly active user limits for the free version of the SDK?

Apps that utilize the free tier of Pilgrim SDK can have no more than 10K monthly active users (MAU) and can integrate the SDK on a single app. To unlock more MAU and additional apps, learn more about our Enterprise tier at enterprise.foursquare.com/pilgrim.

What happens when a Pilgrim SDK free tier account hits their MAU limit?

In order to ensure free tier customers do not surpass MAU limits, Foursquare tracks usage on a rolling basis. When an account reaches or exceeds 10K MAU, each additional user could result in an error.

Do we store any user data collected from free tier partners?

Foursquare will store some transient data that may be used for troubleshooting and debugging—for a maximum of 2-3 days. Please note, no stored data will be used to supplement our panel in any way.

You mentioned that free tier partners may be audited to ensure they are using the SDK appropriately. What are the details of the audit?

At least every six months, Foursquare will reserve the right to conduct audits of applications currently using the Pilgrim SDK. This will include re-reviewing the application and conducting additional investigations to ensure continued use case validity, in addition to ensuring continued consent and adherence to our Privacy Policies and Terms of Use.


Why am I seeing “Error simulating visit” in debug mode?

This usually happens for the following reasons:

  1. Your Foursquare app doesn’t have the proper bundle IDs (iOS) or key hash (Android) added to the console settings.
  2. Proper location permissions have not been set up in your app.
  3. Your Foursquare account is not enabled to use the Pilgrim SDK. Request access if you haven’t already.

If you continue to have issues, please email pilgrimsdk-support@foursquare.com with your app’s client_id and we will help troubleshoot what might be happening.

Why am I not receiving any notifications?

For Pilgrim SDK v2 or newer, make sure you have added your Android Key Hash and/or iOS Bundle Identifier in your developer console.

Once you’ve confirmed your app’s authorization credentials are properly set up, 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, ensure 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>

For Android, make sure you add your Android Key Hash in your developer console. For iOS, make sure you’ve added your iOS Bundle Identifier.

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

Why am I 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 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 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 does Home/Work detection work?

After 3-7 days of use, the SDK will determine the user’s home and work location. You can see if this has been set by checking the hasHomeOrWork property.

FSQPPilgrimManager.shared().hasHomeOrWork()
    
FrequentLocations.hasHomeOrWork(context)
    

Important: It’s possible that you won’t want to process any visits or only trust visits that have a ‘High’ confidence until home/work has been set. This is due to the fact that a user’s home is not in our venue database, so we may be attributing ‘home’ visits to a venue nearby until we learn that this is in fact their home. An example of this simple check on iOS is below:

func fsqpPilgrimManager(_ locationManager: FSQPPilgrimManager, didVisit visit: FSQPVisit) {
    if FSQPPilgrimManager.shared().hasHomeOrWork() {

        // Home and work are set. Lets print them out
        print(FSQPPilgrimManager.shared().homeLocations)
        print(FSQPPilgrimManager.shared().workLocations)

    } else if visit.confidence != .high {
        // Home and work aren't set and visit confidence isn't High
        // Depending on my application I might not want to trust this visit
    }
}
    

What is Foursquare’s geofencing solution?

Geofences enable the Pilgrim SDK to trigger events based off of multiple geofencing methods. We support point and radius for Foursquare POIs from our venues database and arbitrary lat/lng points (with customizable radius), as well as ability to add custom polygon shapes. Foursquare POI support is configurable at any level in the venue hierarchy (category, chain, venue, etc.). Geofences fire Entrance, Dwell, and Exit events. The Dwell event fires after the device has been inside the geofence for a certain amount of time. The dwell time is also configurable.

Can I use geofencing in addition to Pilgrim Stop Detection?

Yes! Geofencing runs in parallel with traditional Pilgrim stop detection. Most apps that end up using geofencing to power a consumer-facing feature would also benefit from all the other visits captured by stop detection.

What are the benefits of geofencing?

There are two main benefits to geofences:

  1. They allow for more control over the timing of events. With geofences, an event triggers as soon as a device is detected as crossing a boundary or after a specific amount of time has passed while in the geofence.
  2. They are useful for driving engagement to nearby venues as opposed to confirming a visit at a specific venue.

When should I use geofences?

We generally say that stop detection is for “Here” and geofencing is for “Near,” but here are some additional examples of when geofencing might be the best option:

  • Geofence management: Apps that have built their own geofences tend to struggle with keeping their geofence database up-to-date and run into the OS limitations on number of geofences. Using Pilgrim SDK, we can relieve the developer of maintaining this on their own by enabling them to simply enter a set of chains, categories, or specific venues and we will take care of the rest.
  • When a user is known to be on their way: If an app knows a user will be heading to a specific venue, geofencing can alert them as soon as that user arrives (i.e., order-ahead).
  • When a niche subset of venues are most important: Geofencing can help in situations where an app needs to know if a user is near a rarely visited place (i.e., auto dealerships).
  • Proximity-based engagement/nearby: When an app wants to drive users into nearby venues.
  • Lower the bar of “visit” detection: Make it easier/faster to detect visits around venues at the cost of accuracy/false positives. False positives go up significantly at venues with a small geographic footprint and/or in dense urban environments.

How do I enable and set up geofencing?

Geofences are part of the Pilgrim SDK versions 2.0.0 and above. We have put together a Migration Guide for partners using older versions to help update to the latest version. Once you are using a geofence enabled version, you can go to the Geofencing tab of your Pilgrim Console to upload new geofences. For more details on geofence management, please see our documentation. You can also get in touch with your Foursquare rep, who can help you get set up properly.


What are Pilgrim segments?

Segments are the most sophisticated way to understand users, powered by years of Foursquare data science and analysis of visit patterns. Segments allow you to intelligently target your users based on their visit behavior for deeper customer engagement with 17 pre-built user segments. With segments, you can build personalized experiences for your users based on “who they are” according to each user’s visit patterns and history.

How do I get access to segments?

Segments are currently in an early access phase and require account enablement by your Foursquare contact. Once turned on, segments can be accessed with each visit via the Pilgrim SDK (iOS & Android), webhook event payload, or delivery to third-party integrations.

What segments are currently available?

Partners can now bucket their users based on their visit patterns into our 17 segment personas. These are:

  1. The Foursquare Arts & Entertainment Fan
  2. The Foursquare Beauty Enthusiast
  3. The Foursquare Casual Diner
  4. The Foursquare Coffee Drinker
  5. The Foursquare College Student
  6. The Foursquare Fast Food Fan
  7. The Foursquare Fitness Fanatic
  8. The Foursquare Foodie
  9. The Foursquare Host
  10. The Foursquare Life of the Party
  11. The Foursquare Movie Goer
  12. The Foursquare Professional
  13. The Foursquare Sports Lover
  14. The Foursquare Super Shopper
  15. The Foursquare Technophile
  16. The Foursquare Traveler 1.The Foursquare Trendsetter

For more information about what each segment means, please feel free to reach out to your Foursquare contact and they will be happy to provide more information.

Where can I learn more about segments?

Further documentation about segments can be found in our developer documentation. You can also get in touch with your Foursquare rep, who can help answer further questions.


Why do I need to configure Pilgrim in the AppDelegate?

For Pilgrim’s stop detection and geofence capabilities, Pilgrim needs to configured at the earlier point in the app’s life cycle because it often needs to run in the background, not just when the app is open and in the foreground. For iOS, this is in the AppDelegate’s didFinishLaunchingWithOptions or willFinishLaunchingWithOptions. If Pilgrim is not configured here, it’s possible that Pilgrim will not stay active and visits could be missed.

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 and 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 to indicate you can leave those in place.

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 (such as “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 an 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 phone’s sensors, we will capture this and feed it into our location detection algorithms. Simply stated, if there’s a beacon, 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, and background location needs to be enabled to function regardless of beacons being present.

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

You are getting this error because you are trying to submit a build with an x86_64 architecture included and the x86_64 architecture is there so you can run Pilgrim apps in the simulator. There is a handy little run script that loops through frameworks to remove ones that aren’t required (paste this into your project’s Build Phases > Run Scripts):

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# 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
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"

EXTRACTED_ARCHS=()

for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done

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

echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"

done

How do I integrate the SDK now that Artifactory is not supported?

Checkout our migration docs so you can use Carthage, CocoaPods or Manually integrate the SDK.

Why do I need to put the Pilgrim builder in the application’s onCreate?

For Pilgrim’s stop detection and geofence capabilities, Pilgrim needs to configured at the earlier point in the app’s life cycle because it often needs to run in the background, not just when the app is open and in the foreground. For Android, this is in the App.java’s onCreate method. If the Pilgrim builder is not included here, it’s possible that Pilgrim will not stay active and visits could be missed.

What permissions does Pilgrim add to my manifest?

The following permissions are automatically added to your manifest file when you import the Pilgrim SDK library:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

Please let us know if you have any questions about this list. An example AndroidManifest.xml file can be found here.


Next Steps

Changelog

Was this page helpful?
Yes
No
Thank you!