eBook

A guide to getting the most out of Pilgrim SDK

  • Foursquare
  • August 18, 2021

Learn to create better app experiences and more.

Christian Wiediger Unsplash
Thanks so much for your interest. One of our location experts will get back to you ASAP.

User experience separates the good apps from the great.

Study after study proves that users stick with apps that give them more personalized experiences. That’s exactly what developers can accomplish by using Pilgrim SDK, which Foursquare embeds in its own consumer apps City Guide and Swarm and which can be embedded in any app, to provide:

  • Visibility into users’ and venues’ precise locations – not just approximate locations.
  • A detailed picture of users’ lifestyles and preferences
  • The ability to deliver enriching user experiences that edge out the competition

Take advantage of Pilgrim by:

  • Understanding iOS and Android location permissions best practices
  • Boosting location opt-in rates with operating system–specific strategies
  • Building better contextual experiences with key Pilgrim SDK features

Location Permission Best Practices

User journey data provides insight into who your users are based on the chains or venue categories they visit in the real world. But for developers to get an “always-on” view into users’ movements, users first must consent to sharing their background location data. That’s becoming trickier with newer releases of Apple iOS and Google Android. In general, this push for increased transparency and opt-in permissions instead of opt-out means that developers need to make a clear case for requesting location data and ensure that the value to the user is evident.

For Apple iOS

Location: Apple now allows users to choose when they want to share their precise location with an app: always, only when the app is in use, or never. They also can choose to share only their approximate location instead of their specific location.

If a user opts out of “Precise Location,” the app will receive approximate locations based on regions four times per hour. If a user moves around inside this region without ever crossing its boundaries, the app will continue to receive the exact same latitude, longitude, and horizontal accuracy. For this reason, it’s very important that an app identifies when a user opts out of “Precise Location.”

If users choose to share only their approximate location, Pilgrim SDK 3.0 still has you covered. The enhanced User States functionality can deliver events to apps by city, state, country, Designated Market Area (DMA) or zip code where a user exists. Although limited, this location context can still be used to trigger notifications and provide insights about your users. (Read more here for more info on how to accurately interact with your users based on their state.)

Privacy: Starting with iOS 14, Apple also made some big privacy changes that allow users to block the IDFA identifier at the app level. The prompt includes a map and a trail of the locations that they have visited and that have been shared with app developers. To solve this challenge, Pilgrim supports new forms of identification that emerge to replace IDFAs. That means that developers will still be able to tie Pilgrim events to a specific user with an ID of the developer’s choice Of course, you’ll still need to request permission from your users to use this alternative ID, which is why it’s important to explain exactly how this data is being used through your onboarding experience or primer message. (Read more here for more info on how to set custom user unique identifiers.)

For Google Android

Location: With Android 11, Android’s most recent OS (although Android 12 is currently in beta), users have three location permissions options: “While Using this App”, “Only this time” or “Deny” access, which applies to when an app is in use, for a single session, or not at all. If users have selected “While Using the App” the next step is to push them to Settings to enable “Allow all the time”. This can be done immediately following the native location prompt or on a subsequent launch with a primer to give the user more context on the need for that permission.

Like Apple, Android 12 is expected to allow users to share only their approximate location. Since the traditional version of Pilgrim doesn’t work with approximate location, the best workaround is to perform contextual location changes with Pilgrim’s “user states” feature, which provides details like city, state and zip code changes.

This brings Android generally in line with the options available to Apple iOS users. As always, Pilgrim SDK features are most impactful when users opt for background location sharing. But take note: Android requires that app developers requiring background location tracking must have a valid use for capturing the data. It must be user-facing and properly disclosed to users.

Privacy: New privacy features in Android 12 will help you prevent apps from collecting unwanted information, and turn off your camera and microphone across all apps. The impact is similar to that of IoS.

It’s critically important that anyone using Pilgrim SDK has a privacy policy that covers location consent. If a privacy policy doesn’t exist, please connect with a legal professional. Before building with Pilgrim, remember to review Foursquare’s privacy policy.

Boost Location Opt-In Rates with Key Platform Strategies

To boost background location-sharing opt-in rates, developers should showcase the value that location experiences powered by Pilgrim SDK provide.

Here are some Foursquare pro tips about location:

  • Display the opt-in prompt before the OS displays its prompt so location permissions are only requested after users have already indicated they will agree.
  • Show users the location-enabled feature before asking for location permission so they have the correct context for the feature that their location powers, or
  • Display a series of onboarding screens explaining the use of location and/or notifications. We have found that explanations of pings dramatically increase the number of users who opt-in to them. Read more here.

When it comes to opt-in language, users are most receptive to direct and transparent messaging that explains how data is collected and what the app’s sharing practices are. The most impactful opt-in language will be short and clearly explain the following:

  • Why the app needs the user’s location information
  • How location data is used
  • What your sharing practices are
  • What the value of sharing location is to users

While these tips are useful across the board, each operating system does have its own unique attributes. Here’s a rundown:

Apple iOS

You can use Pilgrim SDK to send contextual notifications when users arrive at a venue, which requires that users have background location sharing enabled. To ensure that users grant permission, ask for background location access only after the user has already granted permissions for notifications. That way, they understand what feature location powers
(e.g., location-based notifications), see its value and are less likely to deny location permissions when prompted.

Google Android

Many apps have a name that indicates why location sharing is useful—weather, navigation, or fitness apps, for instance. No matter which app you choose to build, we recommend that you ask for location permission immediately when the app opens. Historically, users are happy to grant permission because they understand that location powers the app, and simply want to clear the dialogue box to explore. This is how Google’s Maps application asks for permission on iOS, for instance.

Developers also should demonstrate the value of location in the first few days of the app’s use. By showcasing the value that users receive from “always-on” location and Pilgrim SDK, developers can ensure that users won’t disable background location-sharing when the next OS prompt appears.

Img9232
Img9233
Img 9234
Img 9235

Build better contextual experiences with key Pilgrim SDK features

“Here” Location Targeting: Snap-to-Place

Snap-to-Place, a core part of Pilgrim SDK’s visit detection technology, uses machine learning to passively identify when someone has visited a place, allowing developers to pinpoint when a user has visited a specific venue. These location-based pings consider the frequency and recency of when users have visited specific chains or venue categories (i.e., fitness centers) to create more targeted communications.

How we do it: Our proprietary technology returns a list of venues at the user’s location, according to how well the venue “matches” the location. Pilgrim SDK lists up to 50 venue results, applies confidence levels to them, and specifies their accuracy in terms of latitude and longitude. By considering a range of signals to achieve an accurate prediction, including Wi-Fi, Bluetooth, and GPS, Pilgrim SDK automatically recognizes more than 60 million commercial venues.

“Near” Location Targeting: Geofences

With Pilgrim SDK’s geofencing feature, developers know when a user is nearing or has entered a venue depending on set thresholds. This is invaluable information for developers who want to ping users the moment they enter a location, instead of waiting two to three minutes for Foursquare’s visit detection technology (i.e., Snap-to-Place, featured above) to provide a more accurate prediction. Developers can also ping users who are approaching a venue, helping to convince them to stop rather than walk past.

User States for On-the-Go Consumers

User States help developers understand when and where consumers move through the world—providing them with actionable data and context needed to drive better app experiences. User States covers three areas: Home/Work, Commute, and Travel.

  • Home/Work and Commute: Provides deeper context into daily patterns. After three to seven days of use, Pilgrim SDK will determine the user’s home and work location. Commute knows when consumers leave home or work, automatically flagging these repeat destinations.
  • Travel: Travel understands when consumers move further than 200 miles from their homes. This feature empowers developers to cater to consumer travel preferences, as well as reach consumers as they move to new locations.

How we do it: Developers can configure geofences around specific venues through Foursquare’s Pilgrim web console or by using our Geofence API to post multiple geofences. This is ideal for developers who want to bulk-upload geofences and manage their preferences. You can also use Geofence Builder, which allows non-developers to add geofences, one-by-one —configuring size, shape, dwell times and more—using an intuitive, step-by-step geofence wizard in our console.

Mockup1

Pilgrim SDK Segments and Attribute-Based Targeting
Pilgrim SDK Segments provides the data-driven insight needed to reach specific consumer groups and cater directly to their needs. Using 750 pre-defined user segments like the Super Shopper, the Technophile, and the Foodie, businesses can target audiences with highly tailored messaging, or even empower advertisers to send behavior-based campaigns.
Pilgrim SDK Segments also are plug-and-play, which means that developers can immediately apply them to their customer segments. There are a number of options for user data-delivery methods, including:

  • Native integrations with leading MMA platforms (Airship, Braze, Iterable, mParticle…)
  • Webhook
Pilgrim Image 1
  • Export via Secure File Transfer Protocol (SFTP) or a service like
  • Amazon Simple Storage Service (S3)
Pilgrim Image 2

How we do it: Foursquare uses a data-driven approach to build these segments, analyzing many consumer attributes. Segments can be based on different windows of time, looking back 30, 60, 90 days or beyond. Once Segments are turned on, they are updated and published to your AWS S3 bucket every two weeks. Developers must receive user location permissions to use this feature. Segments include:

  • Demographics (age and gender)
  • Category depth (the types of places users visit)
  • Ratings (the popularity of the places users visit)
  • Pricing (the amount that users are willing to spend)
  • Visitation history (the frequency and timing of user visits)

Conclusion

Basing your app on technology from a trusted independent location data and technology platform is an efficient and powerful way to understand your users, their interests and where they go. This information is the pathway to engaging with your customers more effectively and creating true personalization at scale.

To learn more about using Pilgrim SDK to drive your business forward, test Pilgrim by creating a free account at developer.foursquare.com or reach out to Foursquare using the form below.