The Pilgrim Console allows you to remotely configure how the SDK will respond to different visit events and control the flow of information to a webhook or third party. The sections below provide further detail on configuring your Pilgrim Console for success.


Console

After your API key is whitelisted, access your console here (where CLIENT_ID is the CLIENT_ID from your whitelisted Pilgrim app):

https://foursquare.com/developers/app/CLIENT_ID/pilgrim


The console link can also be found in the right sidebar of your app detail view:

console-screenshot

Important: Please remember to click the Save changes button at the bottom of the page to save updates.


Triggers

Notification Settings

These settings control high-level events that you want to receive from the SDK.

notification-settings

Setting Description
Include other venues If enabled, we will include an array of up to 4 other possible venues the user may be at with every arrival event
Trigger notifications on Home stops If enabled, we will trigger visit events for the user’s home location
Trigger notifications on Work stops If enabled, we will trigger visit events for the user’s work location
Trigger notifications on exits If enabled, we will trigger a departure event when the user exits a venue (or home/work if enabled)
Use exact category matches If using a category custom venue trigger this setting will ignore child categories and only match on the exact category

At a Place Triggers

By default, you will receive an event for visits at all venue types that are at or above a confidence threshold. We recommend starting by receiving All events to get a feel for what these confidence levels look like. It’s also common to keep this set to All and filter out events in a separate process (as a reference, Foursquare uses Medium for all our push notifications in our apps).

at-a-place-triggers

Setting Description
Minimum Confidence Controls the minimum confidence level for places to trigger a notification

Custom Venue Types

By default, you will get notifications for all venues but you have the option to receive notifications for select venues by choosing the Custom venue types radio button.

at-a-place-triggers-custom

Setting Description
Venue IDs A comma separated list of venue IDs that you care about. You can easily find the venue ID in the Foursquare webpage URL: https://foursquare.com/v/foursquare-hq/4ef0e7cf7beb5932d5bdeb4e
Category IDs A comma separated list of category IDs. Find our list of categories and their IDs here (by default this will also include child categories)
Chain IDs A comma separated list of chain IDs

Nearby Triggers

With Nearby Triggers, you can configure proximity-based nearby notifications at a global level. If one of your users stops near a venue that’s of interest to you, that venue will be included in the visit object. The settings here are similar to the At a Place Triggers.

Important: The Minimum Confidence setting will override a Nearby Trigger, meaning if the minimum confidence of the visit is not met, an event that may have included a nearby venue will not be triggered. For this reason, we recommend setting the Minimum Confidence to All if you are using Nearby Triggers.

nearby-triggers

Setting Description
Venue IDs A comma separated list of venue IDs you care about. For example, you could do Foursquare HQ, and grab the venue ID from the Foursquare page. https://foursquare.com/v/foursquare-hq/4ef0e7cf7beb5932d5bdeb4e
Category IDs A comma separated list of category IDs. Find our list of categories and their IDs here (by default this will also include child categories)
Chain IDs A comma separated list of chain IDs
Radius The distance in meters to search for venues that match your Nearby triggers, in the range of 100m to 2000m. You can leave this blank to use the default radius, which is a smart radius based on venue density that will vary from 200m in dense urban areas up to 3km in sparse rural areas.

For more information on Nearby Triggers, including how to set them at a user level, check out our Advanced Setup Guide on Nearby venues.


Custom User Data

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.


Where to set

Ideally, the user info should be set in Application#onCreate (for Android) or in the AppDelegate’s didFinishLaunchingWithOptions (for iOS). Setting it in other locations of your app could result in only sending the user info once that specific process is open. If the app ever dies or the user closes the app, the next time Pilgrim wakes the app up, the value may not be stored (and thus not get sent to the webhook or MMA). The Pilgrim SDK doesn’t persist the userInfo dictionary, it needs to be set every time.

If setting the user info in the Application#onCreate or AppDelegate’s didFinishLaunchingWithOptions is not feasible, the general recommendation is that you set it as soon as you have a way to identify your user (upon logging in or once you have their session in the app).

It is also important to remember that while you are not responsible for if a user revokes location permissions, you’ll probably want to stop Pilgrim if a user logs out of their account within the app; otherwise, you’ll receive visits without any user associated.


Examples

// NOTE: the below code should be placed AFTER you setup the SDK (ideally in AppDelegate's didFinishLaunchingWithOptions) using FSQPilgrimManager.configure(...)

let userInfo = FSQPUserInfo()
// the String myCustomUserId would be a previously set variable that stores the user's unique id:
userInfo.setUserId(myCustomUserId)
// You can also set other custom fields using:
userInfo.setData("myData", forKey: "myKey")
FSQPPilgrimManager.shared().userInfo = userInfo
// NOTE: the below code should be placed AFTER you setup the SDK (ideally in AppDelegate's didFinishLaunchingWithOptions) using [[FSQPPilgrimManager sharedManager] configureWith...]

FSQPUserInfo *userInfo = [[FSQPUserInfo alloc] init];
// the String myCustomUserId would be a previously set variable that stores the user's unique id:
[userInfo setUserId:myCustomUserId];
// You can also set other custom fields using:
NSString *myCustomField = [NSString stringWithFormat:@"My custom value"];
[userInfo setData:myCustomField forKey:@"myCustomField"];
[FSQPPilgrimManager sharedManager].userInfo = userInfo;
// NOTE: the below code should be placed AFTER you setup the SDK (ideally in Application#onCreate) using PilgrimSdk.with(builder);

PilgrimUserInfo userInfo = new PilgrimUserInfo();
// the String myCustomUserId would be a previously set variable that stores the user's unique id:
userInfo.setUserId(myCustomUserId);
// You can also set other custom fields using:
userInfo.put("myCustomField", "My custom value");
PilgrimSdk.get().setUserInfo(userInfo);

Testing

The best and quickest way to test and confirm that you are accurately setting the custom user data is to setup and test via our webhook. If you do not already have webhook ingestion set up, you can easily use a tool called ngrok, which can be used to create a tunnel to monitor activity on your local dev machine.


Next Steps

Now that your user info has been set, you’re ready to start working with our webhook and third-party MMAs!

Integrations