Stop Monitoring Visits
If you need to stop monitoring the user’s visits (for example, if they opt out or turn off your background feature), you can turn off the Pilgrim SDK by calling:
This will stop all Pilgrim activity. To resume Pilgrim, just call
Clearing All History
In certain instances, you may want to clear a users visit history entirely from the device, including their Home and Work locations. An example of this may be a user logging out of your app. For this you should use:
Note: You cannot call this when monitoring visits. You need to call
Home and Work Detection
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
Note: 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:
Other Possible Venues
By default, Pilgrim only returns the single venue that it believes the device is at. There is also a setting to return 4 alternate places (ordered by confidence) for arrival events. To enable these other venues, there is a checkbox on the Pilgrim Console of your Foursquare Developer account that you can turn on to begin to receiving these venues.
Once enabled, you can access the other places as follows:
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.
The best and quickest way to test and confirm that you are accurately setting the custom user data is to set up 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.
If you maintain your own venue database, you may want to know if a visit has occurred at one of those venues. We have a guide for venue harmonization in our API documentation, but we can also store a copy of the harmonization and return your venue Id in the Pilgrim visit callback. We enable this on a parter-by-partner basis, please contact us if you feel like this feature should be enabled for you. Once enabled, you will start seeing your venue Ids returned for visits where we have a mapping.
Check out the Changelog for the latest updates.