Pilgrim Console

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. After your API key is whitelisted you’ll be able to access your console via:

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

Where CLIENT_ID is the CLIENT_ID from your whitelisted Pilgrim app. The console link can also be found in the right sidebar of your app detail view.

Important:

Any changes made here do not automatically go into effect. You need to click the ‘Save changes’ button at the bottom of the page to save updates.


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 restrict that set by a few criteria if you select 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

Here 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 that 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’re using Nearby Triggers.

nearby-triggers

Setting Description
Venue IDs A comma separated list of venue ids that 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.


Webhook

Instead of handling the event locally in your SDK, you can have them sent directly to your server as well. If you enter a URL here, we will send a POST request with visit details along with a secret key so you know it’s us.

Important:

Webhooks get triggered in addition to the regular callback in the SDK, and don’t alter SDK behavior at all.

webhook

Important:

When testing your webhook, we’ve noticed that pings to requestb.in are sometimes not delivered. We recommend using HookBin if you’re testing outside of a webhook you own.

See our Advanced Setup Guide on Webhooks for more info.


Third Party Integrations

Many companies use a Mobile Marketing Automation (MMA) solution to manage events and create content based on those events. The Pilgrim SDK allows you to directly integrate events into certain platforms. Similar to webhooks, we will send a notification to partners you have configured every time we detect an event. If you are using a partner that we currently don’t support, let us know and we can look into offering an integration for that as well.

More information on how to configure these in the SDK can be found in our Advanced Setup Guide for Third Party Integrations.

Appboy

The Appboy integration requires your Group Id and an optional Android App Id and/or iOS App Id. appboy

Localytics

The Localytics integration requries your App UUID, API Key and App Secret. localytics

MParticle

The MParticle integration requires an Android App Key and Android App Secret and/or an iOS App Key and iOS App Secret. mparticle

Urban Airship

The Urban Airship integration requires your App ID and App Token. urbanairship


Up Next

Check out our quickstart guides for iOS and Android.

iOS Quickstart

Android Quickstart