The true power of Pilgrim begins to showcase itself once you start integrating its event detection with other services. Pilgrim supports a number of server-side and third-party integration options.

Webhooks

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.


Setup

From your Pilgrim Configuration console, fill in the Webhook URL:

webhook

For each arrival and departure, we will send a POST request with visit details along with a secret key so you know it’s us.


v2

v1

v2

v1

Payload

The notification will come to your server endpoint as a x-www-urlencoded POST request. You can download example webhook notification JSON from Dropbox here.

Params

Param Value
json The content of the notification in a JSON serialized string
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.
arbitrary params In the SDK, there is a property available for you to set called userInfo. This is a set of arbitrary parameters that you set on the SDK that will then be passed through to your endpoint here. For example, if you set a map of “userId” -> “123456” in the SDK, the request to your server you would also see a parameter of “userId” alongside JSON. The arbitrary params should be set before starting the SDK.
JSON

The content represented in the JSON string from the top level parameter.

Key Type Description
venues Array<Venue> The place the user is at. Currently, a max of 1 item is sent.
confidence String The venue confidence, which is one of none, low, med, or high
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
pilgrimVisitId String The unique ID of the visit. Required for confirming visits back to Foursquare
timestamp long Time of the event in milliseconds since epoch
visitType String The type of notification that is coming through: arrival, departure, historical.
locationType String The type of place the event corresponds to. One of venue, home, work, none, or unknown
sdkType String The SDK that generated the notification iosSdk or androidSdk
arrivalTime long Time of the arrival in milliseconds since epoch
departureTime (Optional) long Time of the departure in milliseconds since epoch. Available on exit and historical visit types.
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
nearbyVenues (Optional) Array<Venue> The list of places nearby that matched your selected nearby triggers as configured on the Pilgrim console or locally in the SDK on a per user basis.
Venue
Key Type Description
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
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
Location
Key Type Description
crossStreet String Venue cross street
address String The address of the venue
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
Category
Key Type Description
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
Icon
Key Type Description
prefix String URL prefix
suffix String URL suffix
Chain
Key Type Description
id String The chain id

Example webhook payload

{
  "secret": "XXXXXX",
  "json": {
    "venues": [
      {
        "id": "412d2800f964a520df0c1fe3",
        "name": "Central Park",
        "location": {
          "address": "59th St to 110th St",
          "crossStreet": "5th Ave to Central Park West",
          "city": "New York",
          "state": "NY",
          "postalCode": "10028",
          "country": "US",
          "lat": 40.788859944495,
          "lng": -73.961162567139
        },
        "categories": [
          {
            "id": "4bf58dd8d48988d163941735",
            "name": "Park",
            "pluralName": "Parks",
            "shortName": "Park",
            "icon": {
              "prefix": "https:\/\/ss3.4sqi.net\/img\/categories_v2\/parks_outdoors\/park_",
              "suffix": ".png"
            }
          }
        ],
        "venueChains": [

        ]
      }
    ],
    "confidence": "med",
    "locationType": "venue",
    "pilgrimVisitId": "593eede7d48ec143c034a349",
    "visitType": "arrival",
    "timestamp": 1497296359056,
    "lat": 40.777502,
    "lng": -73.969508,
    "sdkType": "androidsdk"
  }
}

The notification will come to your server endpoint as an application/json POST request. You can see example webhook notification JSON from Github here.

Headers

Param Value  
Content-Length Integer Size of body content in bytes. Example: 708
Content-Type String Will be: application/json
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: Foursquare-PilgrimSDK/$version. Example: Foursquare-PilgrimSDK/2.0
X-Forwarded-For IP Address Example: 199.38.179.113
X-Forwarded-Proto String Example: https

Body

Param Value  
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 userInfo. This is a set of arbitrary parameters that you set on the SDK that will then be passed through to your endpoint here. For example, if you set a map of “userId” -> “123456” in the SDK, the request to your server you would also see a parameter of “userId”. The arbitrary params should be set before starting the SDK.
sdkType String The SDK that generated the notification iosSdk or androidSdk
placeEvent
Key Type Description  
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 exit and historical visit types.  
confidence String The venue confidence, which is one of none, low, med, high  
locationType String The type of place the event corresponds to. One of venue, home, work, none, unknown  
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  
nearbyVenues (Optional) Array<Venue> The list of places nearby that matched your selected nearby triggers as configured on the Pilgrim console or locally in the SDK on a per user basis.  
Venue
Key Type Description
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
Location
Key Type Description
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
Category
Key Type Description
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
Icon
Key Type Description
prefix String URL prefix
suffix String URL suffix
Chain
Key Type Description
id String The chain id

Example webhook payload

{
    "pilgrimVisitId": "5b8821d9bcbf7a002dab91fc",
    "eventType": "placeArrival",
    "timestamp": 1535648217088,
    "placeEvent": {
        "venues": [
            {
                "id": "3fd66200f964a52098ed1ee3",
                "name": "The Irish Bank",
                "location": {
                    "address": "10 Mark Ln",
                    "crossStreet": "at Harlan Pl.",
                    "city": "San Francisco",
                    "state": "CA",
                    "postalCode": "94108",
                    "country": "US",
                    "lat": 37.7903451920591,
                    "lng": -122.40459322929382
                },
                "categories": [
                    {
                        "id": "52e81612bcbc57f1066b7a06",
                        "name": "Irish Pub",
                        "pluralName": "Irish Pubs",
                        "shortName": "Irish",
                        "icon": {
                            "prefix": "https://ss3.4sqi.net/img/categories_v2/nightlife/pub_",
                            "suffix": ".png"
                        }
                    }
                ],
                "probability": 0.6088516762188961
            }
        ],
        "otherPossibleVenues": [
            {
                "id": "49e7e380f964a52027651fe3",
                "name": "Akiko’s Restaurant & Sushi Bar",
                "location": {
                    "address": "431 Bush St",
                    "crossStreet": "at Mark Ln.",
                    "city": "San Francisco",
                    "state": "CA",
                    "postalCode": "94108",
                    "country": "US",
                    "lat": 37.790623,
                    "lng": -122.404657
                },
                "categories": [
                    {
                        "id": "4bf58dd8d48988d1d2941735",
                        "name": "Sushi Restaurant",
                        "pluralName": "Sushi Restaurants",
                        "shortName": "Sushi",
                        "icon": {
                            "prefix": "https://ss3.4sqi.net/img/categories_v2/food/sushi_",
                            "suffix": ".png"
                        }
                    },
                    {
                        "id": "4bf58dd8d48988d111941735",
                        "name": "Japanese Restaurant",
                        "pluralName": "Japanese Restaurants",
                        "shortName": "Japanese",
                        "icon": {
                            "prefix": "https://ss3.4sqi.net/img/categories_v2/food/japanese_",
                            "suffix": ".png"
                        }
                    }
                ],
                "probability": 0.042400647818909835
            },
            {
                "id": "4ed92126f5b92139871ce962",
                "name": "Foursquare SF",
                "location": {
                    "address": "425 Bush St Ste 500",
                    "crossStreet": "btwn Grant & Kearny",
                    "city": "San Francisco",
                    "state": "CA",
                    "postalCode": "94108",
                    "country": "US",
                    "lat": 37.7905997608588,
                    "lng": -122.40459154855427
                },
                "categories": [
                    {
                        "id": "4bf58dd8d48988d125941735",
                        "name": "Tech Startup",
                        "pluralName": "Tech Startups",
                        "shortName": "Tech Startup",
                        "icon": {
                            "prefix": "https://ss3.4sqi.net/img/categories_v2/shops/technology_",
                            "suffix": ".png"
                        }
                    }
                ],
                "venueChains": [
                    {
                        "id": "556e5779bd6a82902e28bcea",
                        "name": "Foursquare"
                    }
                ],
                "probability": 0.01599619603673202
            },
            ...
        ],
        "confidence": "high",
        "locationType": "venue"
    },
    "lat": 37.790459,
    "lng": -122.404695,
    "user": {
        "userId": "jIkQZBHGrDJt6gMeXlcrWBRO8fStdETO"
    },
    "sdkType": "iossdk"
}

Testing

The quickest way to test and confirm 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. We also recommend using RequestInspector or http://req if you’re testing outside of a webhook you own.

Important: We no longer recommend using requestb.in, as we’ve noticed that sometimes pings are not delivered.


Third Party Integrations

Many teams use a Mobile Marketing Automation (MMA) solution to manage events and create content based on those events. Similar to webhooks, we will send a notification to partners you have configured every time there is an arrival or departure event. We now allow you to directly integrate the Pilgrim SDK events into the platform your company is using. If yours is not on the list, let us know and we can look into offering an integration with that as well.

Braze

How We Work Together

Together, Foursquare and Braze (formerly Appboy) are powering the future of location-based engagement. Foursquare’s Pilgrim SDK delivers a hyper-accurate understanding of where your users go, and our integration with Braze means you can seamlessly personalize your users’ experiences and drive deeper engagement. Foursquare will provide real-time event triggering based upon your users’ location in the physical world, allowing you to harness our powerful geotargeting capabilities and take action with Braze.

Examples of What You Can Do

Integrating w/ Braze opens up a variety of powerful use-cases to help you personalize your users’ experiences:

  • Send customers a notification when they arrive at or leave a particular location based upon Foursquare contextual data, such as a concert venue or Home.
  • Trigger coupons or promotions for high-value customers when they arrive at a location.
  • Gather key demographic or behavioral data over time for richer retargeting.

Integration Details

  1. Make sure both Braze and Pilgrim SDKs are properly setup.
  2. In order to properly map the Braze and Foursquare SDKs, you will need to set the same user ID in both systems, using the changeUser method in the Braze SDK and the setUserId method of PilgrimUserInfo in the Pilgrim SDK.
  3. Enter your Braze REST API Key and (optionally) App IDs in to your app’s Foursquare Pilgrim Console:
  4. Once you have configured the Pilgrim Console, the Pilgrim SDK will automatically track location events and forward them to Braze, allowing you to retarget and segment your customers.
  5. See the Braze developer documentation for more details.

Iterable

How We Work Together

Iterable is a powerful cross channel customer engagement suite that, when combined with Foursquare’s Pilgrim SDK, allows you to seamlessly communicate with your users and ensure they are getting a personalized and highly engaging experience. Foursquare will provide real-time event triggering based upon your users’ location in the physical world, allowing you to harness our powerful geotargeting capabilities and take action on multiple channels with Iterable.

Examples of What You Can Do

Integrating w/ Iterable introduces new location-based engagement, segmentation and personalization:

  • Target Customers when they’re most likely to engage: Trigger targeted messages to users when they are most likely to engage with your brand, such as when they enter your store location or when they depart from a home or work location.
  • Re-capture lapsed customers or customers from competitors: Trigger targeted messages to users when they are in your competitors’ locations or send messages to customers who have strayed from your brand while they are at nearby locations.
  • Discover your customers’ personal preferences ‘in the background’: Segment your mobile users based on their real-world preferences. Pilgrim can reveal which of your users are coffee-lovers or sports-fans allowing you to engage on a deeper level. Pilgrim does this by tracking visit patterns to specific venue types and then by assigning ‘personas’ based on the meta-data associated with to those venues.

Integration Details

  1. Make sure the Pilgrim SDK is properly setup. If you are also looking to utilize Iterable’s In App Push Notification capability, you’ll also need to get the Iterable SDK setup also.
  2. Make sure that you’ve set any user specific ID in using the setUserId method of PilgrimUserInfo in the Pilgrim SDK.
  3. Enter your Iterable API Key in to your app’s Foursquare Pilgrim Console:
  4. Once you have configured the Pilgrim Console, the Pilgrim SDK will automatically track location events and forward them to Iterable, allowing you to easily engage with your users.

Localytics

More details coming soon.

Integration Details

  1. Make sure the Pilgrim SDK is properly setup.
  2. Make sure that you’ve set any user specific ID in using the setUserId method of PilgrimUserInfo in the Pilgrim SDK.
  3. Enter your Localytics App UUID, API Key and App Secret in to your app’s Foursquare Pilgrim Console:
  4. Once you have configured the Pilgrim Console, the Pilgrim SDK will automatically track location events and forward them to Localytics, allowing you to easily engage with your users.

mParticle

More details coming soon.

Integration Details

  1. Make sure the Pilgrim SDK is properly setup.
  2. Optionally, set any user specific ID in using the setUserId method of PilgrimUserInfo in the Pilgrim SDK.
  3. Enter your relevant mParticle keys in to your app’s Foursquare Pilgrim Console:
  4. Once you have configured the Pilgrim Console, the Pilgrim SDK will automatically track location events and forward them to mParticle.

UrbanAirship

More details coming soon.

Integration Details

  1. Make sure the Pilgrim SDK is properly setup.
  2. Make sure that you’ve set any user specific ID in using the setUserId method of PilgrimUserInfo in the Pilgrim SDK.
  3. Enter your relevant UrbanAirship keys in to your app’s Foursquare Pilgrim Console:
  4. Once you have configured the Pilgrim Console, the Pilgrim SDK will automatically track location events and forward them to UrbanAirship.

SalesForce Marketing Cloud

More details coming soon.

Integration Details

  1. Make sure the Pilgrim SDK is properly setup.
  2. Optionally, set any user specific ID in using the setUserId method of PilgrimUserInfo in the Pilgrim SDK.
  3. Enter your SalesForce MC Client ID, Client Secret and Event Definition Key in to your app’s Foursquare Pilgrim Console:
  4. Once you have configured the Pilgrim Console, the Pilgrim SDK will automatically track location events and forward them to SalesForce MC.

Next Steps

Help improve the accuracy of the Pilgrim SDK and where we think devices are located is by providing feedback about a user’s visit.

Visit Feedback