General

  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 does Home/Work detection work?
  5. How large is the SDK Framework?
  6. What is the minimum OS for Pilgrim?
  7. Does the iOS SDK use the region monitoring framework for geofencing?
  8. I’m receiving an “Unsupported Architectures” error when submitting to Apple! Help
  9. Apple is rejecting my app for having Always On location

Geofencing

  1. What is our new Geofencing solution?
  2. Do I need to choose between Geofencing or traditional Pilgrim Snap-to-Place?
  3. What are the benefits of Geofences?
  4. What are the drawbacks to using Geofences?
  5. What are some examples of good use cases for Geofences?
  6. When is Geofencing probably not the best solution?
  7. How are we pricing this solution?
  8. How do I update to Geofences?
  9. Is there technical documentation for this feature?
  10. How do I enable geofencing?

I’d like to remove my data from Pilgrim

In compliance with GDPR privacy laws, Foursquare will make available to all SDK developers the means to request user data be removed from our system via two methods. Both methods require the submission of the install ids associated with the accounts you would like removed. These install ids have been provided to you by Pilgrim and starting May 25th, 2018 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 a form submitted from your app’s developer console. This form will accept up to 1000 install ids at a time, 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.

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 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 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
    }
}
    

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. There is a handy little run script that loops through frameworks to remove ones that aren’t required - paste into your projects 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

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.


What is our new Geofencing solution?

Geofences enable events to trigger based off point + radius circles drawn around POIs from our venues database. They are configurable at any level in the venue hierarchy (category, chain, venue etc.). They default to 100 meters (industry standard), but can be configurable to any size. They fire ‘Entrance’, ‘Dwell’ and ‘Exit’ events. The ‘Dwell’ event fires after a certain amount of time has passed with a device being inside of a geofence. This is also configurable.

Do I need to choose between Geofencing or traditional Pilgrim Snap-to-Place?

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

What are the benefits of Geofences?

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 of being within the geofence.
  2. They are useful for driving engagement to venues nearby as opposed to ensuring a visit at a specific venue.

What are the drawbacks to using Geofences?

The main drawback is that geofences lack stop detection and our machine-learning model to determine if a ‘visit’ occurred. As such, using geofence events to count ‘visits’ greatly increases the likelihood of false positives. Geofence events will fire any time the “blue dot” of a device is detected inside the fence. As we all know, this can be imprecise due to limitations with GPS technology, building obstructions, varying capabilities of device hardware, etc.

This is especially true in dense, urban environments and for venues that have a small geographic footprint. Geofencing a football stadium in Nebraska will likely yield more desirable results than geofencing a coffee shop in Manhattan.

What are some examples of good use cases for Geofences?

  • 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, where they can simply enter a set of chains, categories or specific venues and we 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 venues that are close to them, but they are not necessarily “at”.
  • 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.

When is Geofencing probably not the best solution?

If the goal is to accurately capture ‘visits’ to any more than a small subset of venues, then snap-to-place is the best solution.

How are we pricing this solution?

Geofences will be included with our existing Snap to Place offering at no additional charge.

How do I update to Geofences?

Geofences is part of the most recent release version of the SDK (2.0.0). We have put together a Migration Guide for partners to help update to the latest version.

Is there technical documentation for this feature?

Yes, we have already updated our Pilgrim SDK documentation to include this feature at https://developer.foursquare.com/docs/pilgrim-sdk/geofencing.

How do I enable geofencing?

You can get in touch with your TS rep, who can get you set up properly with Geofences.


Next Steps

Changelog