In the standard integration of the Pilgrim SDK, the SDK will call your app with a notification that your user has arrived at a place. From there, it is likely that you will take some/all of the pieces of information that are handed to you and send those up to your servers for logging or other actions like notification sending. This is a good flow for most apps, but does require the upfront work of defining the client/server protocol to get this information up from your application. To get around this, Foursquare offers the ability to have your servers called anytime one of your user arrives at a place.
Some possible benefits:
- Reduced mobile network traffic and potential battery savings for your users via cutting out an API request to your servers from the device.
- Faster development iteration on your side without having to deploy a new app version.
- Allows Foursquare to potentially offer new data to you without requiring an app or SDK update.
Important: Webhooks get triggered in addition to the regular callback in the SDK and don’t alter SDK behavior at all.
From your Pilgrim Console, click on the Webhooks tab and input your webhook URL:
<img src=”/docs/images/pilgrim-webhooks.png” style=”display: block; height: auto; max-width: 600px;” class=”image-border” alt=”screenshot showing Webhook settings on Pilgrim console>
For each arrival, departure, and geofence event, we will send a
POST request with details about the event. We will also include the secret key provided in your Pilgrim Console so you know it’s us.
The following is the payload structure for version 2 of the webhook. If you are still on version 1, you will find webhook v1 documentation, which contains instructions for updating.
The notification will come to your server endpoint as an
POST request. Examples are available below.
|Content-Length||Integer||Size of body content in bytes. Example:
|Pilgrim-Secret||String||A unique string that will be included on every request. You can find your secret in the developer console on the Pilgrim page.|
|User-Agent||String||The payload’s user agent will now be:
|pilgrimVisitId||String||The unique ID of the visit. Required for confirming visits back to Foursquare|
|eventType||String||The type of notification that is coming through: placeArrival, placeDeparture, placeHistorical.|
|timestamp||long||Time of the event in milliseconds since epoch|
|placeEvent||JSON Hash||Contains the venue and event information about the visit|
|lat||Double||The latitude of the user when they arrived at the place|
|lng||Double||The longitude of the user when they arrived at the place|
|user||JSON Hash||In the SDK, there is a property available for you to set called
|sdkType||String||The SDK that generated the notification
|venues||Array<Venue>||The place the user is at. Currently a max of 1 item is sent.|
|arrivalTime||long||Time of the arrival in milliseconds since epoch|
|departureTime (Optional)||long||Time of the departure in milliseconds since epoch. Available on
|confidence||String||The venue confidence, which is one of
|locationType||String||The type of place the event corresponds to. One of
|otherPossibleVenues (Optional)||Array<Venue>||A list of other venues that the user might be at. Only returned if you have the checkbox selected in the Pilgrim console|
|id||String||The venue id|
|name||String||The venue name|
|location||Location||The location of the venue|
|categories||Array<Category>||The categories of the venue|
|probability||Double||Likelihood of this being the venue the device is actually at|
|hierarchy (optional)||Array<Venue>||The parent venues of this place, containing a subset of venue information (id, name, categories)|
|venueChains (optional)||Array<Chain>||The chains for which the venue belongs|
|address||String||The address of the venue|
|crossStreet||String||Venue cross street|
|city||String||The city of the venue|
|state||String||The state of the venue|
|postalCode||String||The postal code of the venue|
|country||String||The country of the venue|
|lat||Double||The latitude of the venue center|
|lng||Double||The longitude of the venue center|
|id||String||The category id|
|name||String||The category name|
|shortName||String||The shortened version of the category name i.e. American vs American Restaurant|
|pluralName||String||The plural name of the categories|
|icon||Icon||The category icon|
|id||String||The chain id|
The following examples are also available for download.
The true power of Pilgrim begins to showcase itself once you start integrating its event detection with other services. Pilgrim supports a number of third-party integration options.