Segment

How We Work Together

Foursquare provides real-time event triggering based upon your users’ location in the physical world, allowing you to harness our powerful geotargeting capabilities to send those events to other services via Segment.

Installing Pilgrim SDK's integration with Segment will automatically pipe your Pilgrim event data (like visit arrivals and departures) into your Segment account so that you can send it to other destinations. All you need to do is add the Integration in your Foursquare Developer Console's Pilgrim SDK Integrations page. No need to update your iOS or Android applications with anything from Segment.

Examples of What You Can Do

Integrating with Segment opens up a variety of powerful use-cases to help you personalize your users’ experiences:

• Build location-aware features using the most advanced foreground and background location detection so you can understand, engage and retain your users with contextual content in real-time.
• Increase User Engagement Using Location Context: Send targeted notifications to users when they’re at or near one of 60 million commercial points-of-interest (POIs) around the globe. Deliver proximity-based alerts when customers enter or exit a geofence, and drive engagement at the highest moment of impact like along a user’s daily commute.
• Create Smart, Location-Based Audience Segments: Understand user preferences by knowing what categories and chains your customers like to visit over time. Access pre-built customer profiles, strengthened by descriptive venue attributes such as venue category, ratings, and price, for more intelligent targeting.

Example JSON Payloads

Visits HistoricalVisits ArrivalCurrent Location

{
    "userId": "{String}",
    "context": {
        "traits": {},
        "localeactions": "en",
        "device": {
            "advertisingId": "{String}"
        }
    },
    "event": "placeHistorical",
    "properties": {
        "visitType": "historical",
        "probability": "{Double}",
        "confidence": "{String}",
        "lat": "{Double}",
        "lng": "{Double}",
        "locationType": "{String}",
        "visitId": "{String}",
        "timestamp": "{YYYY-MM-DDTHH:MM:SS.XXXZ}",
        "venueName": "{String}",
        "venueId": "{String}",
        "primaryCategoryName": "{String}",
        "primaryCategoryId": "{String}",
        "primaryChainName": "{String}",
        "primaryChainID": "{String}",
        "address": "{String}",
        "crossStreet": "{String}",
        "city": "{String}",
        "state": "{String}",
        "zipCode": "{String}",
        "country": "{String}",
        "supervenueId": "{String}",
        "supervenueName": "{String}",
        "supervenuePrimaryCategoryId": "{String}",
        "supervenuePrimaryCategoryName": "{String}",
        "supervenuePrimaryChainId": "{String}",
        "supervenuePrimaryChainName": "{String}"
    },
    "type": "track"
}

{
    "EventDefinitionKey": "pilgrimArrivalEntrySource",
    "ContactKey": "{String}",
    "Data": {
        "visitType": "arrival",
        "confidence": "{ConfidenceLevel}",
        "lat": "{lat}",
        "lng": "{long}",
        "locationType": "venue",
        "visitId": "{VisitID}",
        "timestamp": "{Timestamp}",
        "venueName": "{VenueName}",
        "venueId": "{VenueID}",
        "primaryCategoryName": "{PrimaryCategoryName}",
        "primaryCategoryId": "{PrimaryCategoryID}",
        "address": "{Address}",
        "crossStreet": "{Cross Street}",
        "city": "{CityName}",
        "state": "{StateCode}",
        "zipCode": "{ZipCode}",
        "country": "{CountryCode}",
        "ContactKey": "{String}",
        "userId": "{String}"
    }
}

{
    "userId": "{String}",
    "context": {
        "traits": {},
        "device": {}
    },
    "event": "currentLocation",
    "properties": {
        "visitType": "currentLocation",
        "probability": "{Double}",
        "confidence": "{String}",
        "lat": "{Double}",
        "lng": "{Double}",
        "locationType": "{String}",
        "visitId": "{String}",
        "timestamp": "{YYYY-MM-DDTHH:MM:SS.XXXZ}",
        "venueName": "{String}",
        "venueId": "{String}",
        "primaryCategoryName": "{String}",
        "primaryCategoryId": "{String}",
        "primaryChainName": "{String}",
        "primaryChainID": "{String}",
        "address": "{String}",
        "crossStreet": "{String}",
        "city": "{String}",
        "state": "{String}",
        "zipCode": "{String}",
        "country": "{String}",
        "supervenueId": "{String}",
        "supervenueName": "{String}",
        "supervenuePrimaryCategoryId": "{String}",
        "supervenuePrimaryCategoryName": "{String}",
        "supervenuePrimaryChainId": "{String}",
        "supervenuePrimaryChainName": "{String}"
    },
    "type": "track"
}

Integration Details

1. In Segment, add Foursquare Pilgrim as a Source via their Catalog. It's listed in the "Enrichment" category.
2. In your iOS and Android apps, make sure the Pilgrim SDK are properly setup.
3. In order to properly map the Segment and Foursquare SDKs, you will need to set the same user ID in both systems. In the Pilgrim SDK, you will use the setUserId method of PilgrimUserInfo.
4. From your Foursquare Pilgrim Console, Enable Third Party Integrations and enter your Segment Write Key.
5. Once you have configured the Pilgrim Console, the Pilgrim SDK will automatically track location events and forward them to Segment, allowing you to send them to other Segment supported destinations. New Pilgrim events should start showing in your Segment app's SourceDebugger screen.
6. See the Segment documentation for more details.