The Pilgrim SDK section of your Foursquare Developer Console allows you to remotely configure how the SDK will respond to different visit events, as well as control the flow of information to a webhook or third party service. The sections below provide further detail to help you configure your Pilgrim Console for success.
Accessing your Console
Once Pilgrim has been enabled for your account, you’ll be able to access the entire Pilgrim console from the side navigation or by going to (where
CLIENT_ID is the Client ID for your Pilgrim app):
The Visits tab is where you can control high-level events for which you would like to receive from the SDK.
You can choose to be notified for all venues or filter for a subset of venues based on categories, chains, and/or a specific venue. Please note that if you are filtering by a specific venue, you will need to select the geographical location first.
By default, the Minimum Confidence Level is set at All but the drop-down menu can be adjusted. Read more about confidence levels here.
After 3-7 days of use, the SDK will determine the user’s home and work location. If you would like to see these events, you can enable the Include events for Home stops and Include events for Work stops checkboxes. Read more about home/work stops here.
If you would like to know when a user leaves a venue, please enable Include exit events.
Enable Include other probable venues if you want to receive an object of nearby venues. Please note that if the minimum confidence level is not met for the nearby venues, then the nearby venue will not be triggered. When using this setting, we recommend setting the Minimum Confidence Level to All.
Pilgrim SDK allows geofencing around a configurable set of venues. Geofences can be set for the venues, categories, or chains of your choosing. Learn more about geofences here.
Pilgrim supports a number of third-party integration options such as Braze and mParticle. Learn more about configuration options.
In addition to regular callbacks from our SDK, you can also set up webhooks so we can send an event to your servers any time one of your users arrive at a venue. Learn more about webhooks.
The Pilgrim Console’s Event Logger is a useful tool that helps provide visibility into device activity while you are working to confirm Pilgrim is properly implemented into your app.
Before your Pilgrim Event Logger will start tracking activity, you must first register the devices that you’d like to see event logs for. You do this by going to the Event Logs section and clicking the Manage IDs link in the top right corner:
To add the new ID to track, you’ll be asked to select the ID type:
You have three options:
- Install ID: this is an ID specifically created by Pilgrim for each installation. If your app is uninstalled and reinstalled on this device, the Install ID will change and you’ll need to remember to add the new Install ID to continue logging events. An example:
8F8FD055-E2BE-497F-B666-49E4ED69D2A1. In Swift, you can get this by calling:
- Ad ID: this is also referred to as the MAID. Apple’s Mobile Ad ID is known as the IDFA, or ID for Advertisers. An example:
231A005B-700F-4119-zB1CE-991EAB2B605D. Google’s Mobile Ad ID is known as AAID, or Android Advertising ID. This is different than the Android ID, which was Android’s permanent device ID. An example:
c14e7fb1–4476–4b21-ba18–063-c35c0a3b. Note: These IDs are not hardcoded to a mobile device and can be reset or blocked by users. Both Apple and Android users can reset their MAIDs to flush all data. Apple users can also block ad tracking entirely, which resets the MAID to all zeros. For Swift, you can do something like:
- User ID: Pilgrim gives developers the ability to set Custom User Data. This allows you to then identify that user based on your own predefined ID.
Once you’ve registered the ID’s you want to log events for, you’ll see them listed and as they start generating visits or triggering geofences, the events will begin showing up in the logs.
As your registered devices start triggering event activity, those events will start showing up in the Event Logs:
To get more information about each individual event, just click the row and you’ll see more details:
Note: Event Logs only show events for the last 7 days. Past 7 days, events are dropped and no longer accessable.
Foursquare gives developers multiple ways of deleting their user’s data to help ensure they stay compliant with various privacy laws. In addition to the erasureRequest API endpoint, we also provide a form from your Developer Console that allows you to provide up to a 1000 install IDs to be processed and removes all visit data for those install IDs from our systems.
Now that you are familiar with the Pilgrim Console, here are additional resources that can help you successfully integrate with Pilgrim: