Add Features

The Pilgrim SDK also offers features which you can use to augment your in-app experience, bringing location to the forefront to offer more compelling interactions to your users.

Journeys

Pilgrim Journeys allows partners to build powerful, location-aware experiences. You can use Journeys to power in-store & curbside pickup, delivery tracking, location-based marketing, and more.

When a user is ready to embark on a journey (i.e. they tap on "I'm on my way"), Journeys will start monitoring for their arrival, provide live ETAs throughout the way, and automatically detect when a user has arrived at their destination.

Requirements

Pilgrim SDK v3.1.0+
Background Location & Precise Location Enabled
- While we recommend ensuring your app has background location and precise location enabled, the Journeys functionality will work with the “When In Use” permission, provided that your app uses the startForeground functionality to enable always on location collection.

Required NotificationHandler

Include the following delegate methods to track journey state/eta/etc. Foursquare will return one of the following journey states:

In Progress: The journey has started successfully and will now send regular updates.
Approaching: The user is now approaching the destination.
Arrived: The user has arrived at the destination.
Completed: The journey has been completed. This is a user-generated action
Canceled: The journey has been canceled. This is a user-generated action.

public abstract class PilgrimNotificationHandler {
…
    public void handleJourneyUpdate(@NonNull Context context, Journey journey)
…
}

Available Methods

Include the following methods to ensure the correct Journeys behaviors are tracked.

// method
PilgrimSdk.startJourney(destinationId: String, destinationType: JourneyDestinationType, metadata: Map<String, String> = emptyMap(), callback: ((Result<Journey, JourneyException>) -> Unit)? = null)
// usage
PilgrimSdk.get().startJourney(venueId, JourneyDestinationType.VENUE) { result ->
    if (result.isErr) {
        // handle error
        return@startJourney
    }                
}

// method
fun getCurrentJourney(context: Context): Journey?
// usage
PilgrimSdk.get().getCurrentJourney(this)?.let { journey ->
    // do something with journey
}

// method
fun completeJourney(callback: ((JourneyException?) -> Unit)? = null)
//usage
PilgrimSdk.get().completeJourney { err ->
    if (err != null) {
        // handle error
        return@checkinJourney
    }
}

// method
fun checkinJourney(callback: ((JourneyException?) -> Unit)? = null)
//usage
PilgrimSdk.get().checkinJourney { err ->
    if (err != null) {
        // handle error
        return@checkinJourney
    }
}

// method
fun completeJourney(callback: ((JourneyException?) -> Unit)? = null)
//usage
PilgrimSdk.get().completeJourney { err ->
    if (err != null) {
        // handle error
        return@checkinJourney
    }
}

Error Handling

Using the exception handler:

PilgrimSdk.with(
    PilgrimSdk.Builder(this)
        …
        .exceptionHandler { ex ->
            // handle error
        }
)

Get Current Location

Current Location is the most comprehensive of the in-app features, allowing you to get precise place information for any user who has given your app permission to use location.

For e.g you may want to display a nearby venue to your user, or you may want to determine whether or not to send an in-app notification or display a modal if your user is at or near a specific geofence.

Note: This does not require always on background location and can also handle location scenarios while your users are in motion.

Using Current Location you can:

Get Current Place

Get the same place name, category, and chain information you would receive in the background callbacks in real time in your app.

if (ContextCompat.checkSelfPermission(this, android.Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
    new Thread(new Runnable() {
        @Override
        public void run() {
            Result<CurrentLocation, Exception> currentLocationResult = PilgrimSdk.get().getCurrentLocation();
            if (currentLocationResult.isOk()) {
                CurrentLocation currentLocation = currentLocationResult.getResult();
                Log.d("PilgrimSdk", "Currently at " + currentLocation.getCurrentPlace().toString() + " and inside " + currentLocation.getMatchedGeofences().size() + " geofence(s)");
            } else {
                Log.e("PilgrimSdk", currentLocationResult.getErr().getMessage(), currentLocationResult.getErr());
            }
        }
    }).start();
}

Get Matched Geofences

If you utilize the explicit geofence functionality of Pilgrim, Current Location will return any Geofence Events, e.g if your user is currently inside one (or many) of your drawn geofences.

if (ContextCompat.checkSelfPermission(this, android.Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
    new Thread(new Runnable() {
        @Override
        public void run() {
            Result<CurrentLocation, Exception> currentLocationResult = PilgrimSdk.get().getCurrentLocation();
            if (currentLocationResult.isOk()) {
                CurrentLocation currentLocation = currentLocationResult.getResult();
                Log.d(currentLocation.getMatchedGeofences().size() + " geofence(s)");
            } else {
                Log.e("PilgrimSdk", currentLocationResult.getErr().getMessage(), currentLocationResult.getErr());
            }
        }
    }).start();
}

Get Last Known User State

The general location context information delivered through Pilgrim’s User States features return city, state, zip and country level information for all users, in addition to home, work, traveling, commuting for users who have enabled always on location.

You can access User State in one of two ways:

Subscribing to changes via the PilgrimNotificationHandler callbacks

 @Override
    public void handleUserStateChange(@NonNull Context context, @NonNull PilgrimSdkUserStateNotification notification) {
        // Process the new user state however you'd like:
        UserState userState = notification.getUserState()
        for (UserState.Component component : notification.getChangedComponents()) {
            Log.d("Changed Component", component.name)
        }
    }

Accessing via the PilgrimManager Instance

PilgrimSdk.get().userState()

Receive Geofence Events

The Pilgrim SDK v2.0+ allows geofencing around a configurable set of venues or points. Geofences can be set for the venues, categories, or chains of your choosing. By default, Foursquare will use its knowledge of the venue's location to return the right fence for a given place. You may also configure a radius of your choosing, but we recommend letting Pilgrim pick the right one to give you the optimal experience.

In SDK version 2.2.0+, support for polygon shapes and arbitrary latitude/longitude points are also available. This allows greater customization and removes the reliance upon geofencing only Foursquare venue locations.

Why Use Geofences

For use cases that rely on accuracy, regular Pilgrim SDK place visit detection is superior to geofencing. However, there are certain instances where geofencing is preferable:

When speed and proximity to a specific subset of venues is more important than accurately detecting visits there.
When it’s more important to know if a user is nearby a certain place rather than visiting.
When you want to track when users that are en-route to a specific venue, and you want to know as soon as they arrive.

Geofencing runs independently alongside regular Pilgrim SDK visit detection so you can still get the benefit of understanding everywhere your users go while enabling additional use cases.

Event Types

Geofences have five potential event types that are delivered directly to the client and through an optional webhook:

Event Type	Description
entrance	Triggered on the first GPS signal that is received inside of the geofence.
dwell	Triggered after the user has "dwelled" within the geofence for a configurable length of time. Default is 1 minute.
venue confirmed	Triggered when the device has dwelled inside a geofence radius and confirmed a stop at the venue within the radius. Only available in SDK versions 2.1.2 or greater
exit	Triggered on the first GPS signal that is received outside of the geofence.
presence	Triggered when the device is in a geofence radius during a get location request. Only available in SDK versions 2.1 or greater

Receiving Events

To receive geofence events on the client, add the event handler below:

// In your implementation of the PilgrimNotificationHandler, add:
@Override
public void handleGeofenceEventNotification(Context context, PilgrimSdkGeofenceEventNotification pilgrimSdkGeofenceEventNotification) {
    List<GeofenceEvent> geofenceEvents = pilgrimSdkGeofenceEventNotification.getGeofenceEvents();
    // Code to handle geofenceEvents...
}

Geofences will need to be set to a specific Foursquare venue, chain, category or shape (see below). For example, a partner could set up geofences for Foursquare HQ, all coffee shops, and all Chick-fil-a’s. You can also set up a geofence for an arbitrary lat/lng or custom polygon shapes. For Foursquare venues, this means that some venue harmonization may need to take place beforehand if you already have a specific list of places you want to geofence.

Note: Geofences are set up globally across all users of the app. User specific geofences are not yet something we provide.

A geofence event will contain the following:

Field	Description
eventType	`entrance`, `dwell`, `venueConfirmed`, `exit`, or `presence`.
venue	Same as regular pilgrim venue object.
categoryIDs	Array of categoryIDs used by triggered geofence.
chainIDs	Array of chainIDs used by triggered geofence.
partnerVenueID	String of harmonized venueId.
location	Object containing location information about the geofence event.
timestamp	Unix/epoch timestamp in milliseconds of when the event occured.

Webhook Examples

{
  "eventType": "geofenceEnter",
  "timestamp": 1545078269223,
  "geofenceEvent": {
    "eventType": "entrance",
    "eventLat": 41.8893897,
    "eventLng": -87.6297896,
    "radius": 100.0,
    "geofenceId": "5c649335af2c3c526c06a898",
    "geofenceProperties": {
      "customGeofenceKey": "Custom Geofence Value"
    },
    "venueId": "4a9037fef964a5209b1620e3",
    "categoryIds": "4bf58dd8d48988d1e0931735",
    "chainIds": "",
    "partnerVenueId": "",
    "venues": [
      {
        "id": "4a9037fef964a5209b1620e3",
        "name": "Einstein Bros Bagels",
        "location": {
          "address": "400 N Dearborn St",
          "crossStreet": "",
          "city": "Chicago",
          "state": "IL",
          "postalCode": "60654",
          "country": "US",
          "lat": 41.8893897,
          "lng": -87.6297896
        },
        "categories": [
          {
            "id": "4bf58dd8d48988d179941735",
            "name": "Bagel Shop",
            "pluralName": "Bagel Shops",
            "shortName": "Bagels",
            "icon": {
              "prefix": "https://ss3.4sqi.net/img/categories_v2/food/bagels_",
              "suffix": ".png"
            }
          },
          {
            "id": "4bf58dd8d48988d1e0931735",
            "name": "Coffee Shop",
            "pluralName": "Coffee Shops",
            "shortName": "Coffee Shop",
            "icon": {
              "prefix": "https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
              "suffix": ".png"
            }
          }
        ],
        "venueChains": [
          {
            "id": "556ce8d9aceaff43eb0588d6",
            "name": "Einstein Bros."
          }
        ]
      }
    ]
  },
  "lat": 41.88928251303856,
  "lng": -87.62870316744883,
  "user": {
    "adid": "40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
    "userId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
  },
  "installId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
  "sdkType": "iossdk",
  "sdkBuild": "2.4.2"
}

{
  "eventType": "geofenceDwell",
  "timestamp": 1545078408140,
  "geofenceEvent": {
    "eventType": "dwell",
    "eventLat": 41.8893897,
    "eventLng": -87.6297896,
    "radius": 100.0,
    "geofenceId": "5c649335af2c3c526c06a898",
    "geofenceProperties": {
      "customGeofenceKey": "Custom Geofence Value"
    },
    "venueId": "4a9037fef964a5209b1620e3",
    "categoryIds": "4bf58dd8d48988d1e0931735",
    "chainIds": "",
    "partnerVenueId": "",
    "venues": [
      {
        "id": "4a9037fef964a5209b1620e3",
        "name": "Einstein Bros Bagels",
        "location": {
          "address": "400 N Dearborn St",
          "crossStreet": "",
          "city": "Chicago",
          "state": "IL",
          "postalCode": "60654",
          "country": "US",
          "lat": 41.8893897,
          "lng": -87.6297896
        },
        "categories": [
          {
            "id": "4bf58dd8d48988d179941735",
            "name": "Bagel Shop",
            "pluralName": "Bagel Shops",
            "shortName": "Bagels",
            "icon": {
              "prefix": "https://ss3.4sqi.net/img/categories_v2/food/bagels_",
              "suffix": ".png"
            }
          },
          {
            "id": "4bf58dd8d48988d1e0931735",
            "name": "Coffee Shop",
            "pluralName": "Coffee Shops",
            "shortName": "Coffee Shop",
            "icon": {
              "prefix": "https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
              "suffix": ".png"
            }
          }
        ],
        "venueChains": [
          {
            "id": "556ce8d9aceaff43eb0588d6",
            "name": "Einstein Bros."
          }
        ]
      }
    ]
  },
  "lat": 41.889335266663636,
  "lng": -87.62856037188838,
  "user": {
    "adid": "40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
    "userId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
  },
  "installId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
  "sdkType": "iossdk",
  "sdkBuild": "2.4.2"
}

{
  "eventType": "geofenceVenueConfirmed",
  "timestamp": 1545078428140,
  "geofenceEvent": {
    "eventType": "venueConfirmed",
    "eventLat": 41.8893897,
    "eventLng": -87.6297896,
    "radius": 100.0,
    "venueId": "4a9037fef964a5209b1620e3",
    "categoryIds": "4bf58dd8d48988d1e0931735",
    "chainIds": "",
    "venues": [
      {
        "id": "4a9037fef964a5209b1620e3",
        "name": "Einstein Bros Bagels",
        "location": {
          "address": "400 N Dearborn St",
          "crossStreet": "",
          "city": "Chicago",
          "state": "IL",
          "postalCode": "60654",
          "country": "US",
          "lat": 41.8893897,
          "lng": -87.6297896
        },
        "categories": [
          {
            "id": "4bf58dd8d48988d179941735",
            "name": "Bagel Shop",
            "pluralName": "Bagel Shops",
            "shortName": "Bagels",
            "icon": {
              "prefix": "https://ss3.4sqi.net/img/categories_v2/food/bagels_",
              "suffix": ".png"
            }
          },
          {
            "id": "4bf58dd8d48988d1e0931735",
            "name": "Coffee Shop",
            "pluralName": "Coffee Shops",
            "shortName": "Coffee Shop",
            "icon": {
              "prefix": "https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
              "suffix": ".png"
            }
          }
        ],
        "venueChains": [
          {
            "id": "556ce8d9aceaff43eb0588d6",
            "name": "Einstein Bros."
          }
        ]
      }
    ]
  },
  "lat": 41.889335266663636,
  "lng": -87.62856037188838,
  "user": {
    "adid": "40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
    "userId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
  },
  "installId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
  "sdkType": "iossdk"
}

{
  "eventType": "geofenceExit",
  "timestamp": 1545091987992,
  "geofenceEvent": {
    "eventType": "exit",
    "eventLat": 41.8893897,
    "eventLng": -87.6297896,
    "radius": 100.0,
    "geofenceId": "5c649335af2c3c526c06a898",
    "geofenceProperties": {
      "customGeofenceKey": "Custom Geofence Value"
    },
    "venueId": "4a9037fef964a5209b1620e3",
    "categoryIds": "4bf58dd8d48988d1e0931735",
    "chainIds": "",
    "partnerVenueId": "",
    "venues": [
      {
        "id": "4a9037fef964a5209b1620e3",
        "name": "Einstein Bros Bagels",
        "location": {
          "address": "400 N Dearborn St",
          "crossStreet": "",
          "city": "Chicago",
          "state": "IL",
          "postalCode": "60654",
          "country": "US",
          "lat": 41.8893897,
          "lng": -87.6297896
        },
        "categories": [
          {
            "id": "4bf58dd8d48988d179941735",
            "name": "Bagel Shop",
            "pluralName": "Bagel Shops",
            "shortName": "Bagels",
            "icon": {
              "prefix": "https://ss3.4sqi.net/img/categories_v2/food/bagels_",
              "suffix": ".png"
            }
          },
          {
            "id": "4bf58dd8d48988d1e0931735",
            "name": "Coffee Shop",
            "pluralName": "Coffee Shops",
            "shortName": "Coffee Shop",
            "icon": {
              "prefix": "https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
              "suffix": ".png"
            }
          }
        ],
        "venueChains": [
          {
            "id": "556ce8d9aceaff43eb0588d6",
            "name": "Einstein Bros."
          }
        ]
      }
    ]
  },
  "lat": 41.88709567122635,
  "lng": -87.63105850113463,
  "user": {
    "adid": "40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
    "userId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
  },
  "installId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
  "sdkType": "iossdk",
  "sdkBuild": "2.4.2"
}

{
  "eventType": "geofencePresence",
  "timestamp": 1549553712000,
  "geofenceEvent": {
    "eventType": "presence",
    "eventLat": 41.8893897,
    "eventLng": -87.6297896,
    "radius": 100.0,
    "geofenceId": "5c649335af2c3c526c06a898",
    "geofenceProperties": {
      "customGeofenceKey": "Custom Geofence Value"
    },
    "venueId": "4a9037fef964a5209b1620e3",
    "categoryIds": "4bf58dd8d48988d1e0931735",
    "chainIds": "",
    "partnerVenueId": "",
    "venues": [
      {
        "id": "4a9037fef964a5209b1620e3",
        "name": "Einstein Bros Bagels",
        "location": {
          "address": "400 N Dearborn St",
          "crossStreet": "",
          "city": "Chicago",
          "state": "IL",
          "postalCode": "60654",
          "country": "US",
          "lat": 41.8893897,
          "lng": -87.6297896
        },
        "categories": [
          {
            "id": "4bf58dd8d48988d179941735",
            "name": "Bagel Shop",
            "pluralName": "Bagel Shops",
            "shortName": "Bagels",
            "icon": {
              "prefix": "https://ss3.4sqi.net/img/categories_v2/food/bagels_",
              "suffix": ".png"
            },
            "primary": true
          },
          {
            "id": "4bf58dd8d48988d1e0931735",
            "name": "Coffee Shop",
            "pluralName": "Coffee Shops",
            "shortName": "Coffee Shop",
            "icon": {
              "prefix": "https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
              "suffix": ".png"
            }
          }
        ],
        "venueChains": [
          {
            "id": "556ce8d9aceaff43eb0588d6",
            "name": "Einstein Bros."
          }
        ]
      }
    ]
  },
  "lat": 41.889356,
  "lng": -87.628725,
  "user": {
    "adid": "40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
    "userId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
  },
  "installId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
  "sdkType": "iossdk",
  "sdkBuild": "2.4.2"
}

Geofence Management

Geofences can be managed through the Geofence builder in your Developer Console or via our Geofence API.

Set Custom User Data

Pilgrim enables developers to set custom user unique identifiers in addition to or as a replacement. This is common if you want to tie a Pilgrim event to a specific user in your own database or in a third-party integration.

For example, if your app is using a mobile number and/or an email as a user unique identifier, you can decide to add one or both to your Pilgrim events. Once set, the custom user data will be passed along in the Pilgrim webhook payload.

Where to set custom user data

Generally, we recommend that you set custom user info or user unique identifiers, as soon as you have a way to identify your user i.e upon logging in or once you have their session in the app.

While you do not need to worry about modifying the Pilgrim SDK when a user revokes location permissions, if a user logs out of your app, you should call PilgrimSdk.clearAllData() to reset any unique identifiers that you may have configured.

Examples

PilgrimUserInfo userInfo = new PilgrimUserInfo();

// the String myCustomUserId would be a previously set variable that stores the user's unique id:
userInfo.setUserId(myCustomUserId);

// You can also set other custom fields using:
userInfo.put("+123456789", "phoneNumber");
userInfo.put("[email protected]", "emailAddress");

// Starting in v2.1.2, you have the ability to persist userinfo across sessions:
PilgrimSdk.get().setUserInfo(userInfo, persisted: true);

// To unset persisted fields:
PilgrimSdk.get().setUserInfo(null, persisted: true)

kotlin
val userInfo = PilgrimUserInfo().apply {

// the String myCustomUserId would be a previously set variable that stores the user's unique id:
setUserId(myCustomUserId)

// You can also set other custom fields using:
set("+123456789", "phoneNumber")
set("[email protected]", "emailAddress")

}
// Starting in v2.1.2, you have the ability to persist userinfo across sessions:
PilgrimSdk.get().setUserInfo(userInfo, persisted: true)

// To unset persisted fields:
PilgrimSdk.get().setUserInfo(null, persisted: true)



### Testing

There are two ways to test and confirm that you're successfully setting custom user data, via:

- [Webhooks](/docs/configure-server-webhooks)
- [Event Logs](/docs/view-sdk-event-logs)

## Access User States

User states allow you to more accurately interact, or not interact, with your users based on their state. For example, you might not want to send a notification to any users that are at home but you may want to remind them of a great promotion while they are on their way to work or on vacation.

### Home and Work

As users of your app begin to establish regular behavior (usually after 3-7 week days), Pilgrim SDK will attempt to determine their home and work locations. This is a foundational feature of Pilgrim that is often used in the calculation of other user states.

> **Note:** The home and work locations that Pilgrim determines are a generalized "area", not a specific address. Instead of a specific venue, the arrival/departure events will designate the `locationType` as `home` or `work` instead of `venue`. For example, a webhook payload for a work arrival might look something like this:

```json
{
  "pilgrimVisitId": "4c4b64fdd807ee002cba1560",
  "eventType": "placeArrival",
  "timestamp": 1548444925000,
  "placeEvent": {
    "venues": [],
    "confidence": "high",
    "locationType": "work",
    "arrivalTime": 1548444925000
  },
  "lat": 41.889282,
  "lng": -87.62858,
  "user": {
    "adid": "40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
    "userId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
  },
  "installId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
  "sdkType": "iossdk",
  "sdkBuild": "2.4.2",
  "segments": [
    {
      "segmentId": 162,
      "name": "The Foursquare Coffee Drinker - U.S."
    }
  ]
}

To check if a user has configured their home/work locations, you can see if this has been set by checking the hasHomeOrWork property:

FrequentLocations.hasHomeOrWork(context)

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.

Additional States

Non Home and Work user states are accessible via the lastKnownUserState property on the PilgrimManager instance. This object will have a coordinate, timestamp and a state property.

Note: It is always a good idea to check the timestamp and coordinate of this property, as it’s possible that the user may have moved since the last time the user state was updated.

If you'd like to be notified of any changes in user state, you can do so via the handleUserState callback in the Android SDK.

Travel

We calculate the travel state by observing users home/work visit patterns. States trigger when users deviate from those patterns in a way that signifies traveling. This can be useful if you want to send targeted messaging that relates to a user traveling, as opposed to being in their normal home/work routine.

Commute

Pilgrim defines commuting as when a user is moving some distance between one's home and place of work on a regular basis. This can be useful, for example, if you want to send targeted messaging that relates to their morning or evening commute: "Need a pick me up? Stop by and grab a cup of joe on your way into the office."

Location Context

As part of enhancing and extending User State, Pilgrim also provides an additional Location Context.This can be useful for providing a contextual notification based on a regional change in your user's location. For example, your user entering the City of Wheaton.

The Location Context includes the following:

State
City
Postal Code
Country
DMA

Examples

PilgrimSdk.get().userState()

For examples of how user states are sent via webhook events, see the webhook examples.

Provide Visit Feedback

One of the best ways to help us improve the accuracy of the Pilgrim SDK and where we think devices are located is by providing feedback about a user's visit. The more feedback we get, the smarter, faster and more accurate visits from the Pilgrim SDK become. We provide the following methods to provide feedback.

Confirm and Deny a Visit

You can easily confirm whether a visit is accurate or not (and why). All you need is the pilgrimVisitId from the original visit.

/\*\*

- @param pilgrimVisitId The visit ID from the notification that is sent to you.
-                        Note not all enter notifications have visit ids.
- @param feedback The type of feedback you want to leave for the visit
- @param actualVenueId If you were at another venue than the one you were notified.
-                        Pass the actual venue ID here.
  \*/

public static void leaveVisitFeedback(@NonNull String pilgrimVisitId, @NonNull VisitFeedback feedback, @Nullable String actualVenueId)

The available feedback options are:

Feedback	Description
VisitFeedback.CONFIRM	The visit was at the correct venue.
VisitFeedback.FALSE_STOP	The user did not stop anywhere. If you are unsure, use `deny`
VisitFeedback.WRONG_VENUE	The wrong venue was detected. A Foursquare venue id can optionally be included to identify the correct venue.
VisitFeedback.DENY	Generic feedback that something was incorrect. If your feedback interface doesn’t allow for `wrongVenue` or `falseStop` or you are unsure, use this.

An example providing wrongVenue feedback with the correct venueId:

PilgrimSdk.leaveVisitFeedback(visitId, VisitFeedback.WRONG_VENUE, "4ed92126f5b92139871ce962");

Check-in at a FSQ Venue

If you know a device is at a specific Foursquare venue, irrespective of receiving a Pilgrim Visit, you can also inform Pilgrim by providing the Foursquare venue ID:

//\*\*

- @param venueId The foursquare venue ID where you believe the device is currently at.
  \*/
  checkInWithVenueId(@NonNull final String venueId)

An example:

final String foursquareHQVenueId = "4ef0e7cf7beb5932d5bdeb4e";
PilgrimSdk.checkInWithVenueId(foursquareHQVenueId);

Check-in at a Partner Venue

For partners that have already harmonized their venues with Foursquare, irrespective of receiving a Pilgrim Visit, you can also inform Pilgrim that a device is at a venue by providing the partner's harmonized venue ID:

/**
  * @param venueId A partner venue ID, that is harmonized with Foursquare, where you believe the device is currently at.
  */
  checkInAtVenueWithPartnerVenueId(@NonNull final String venueId)

An example:

// (string) venueId is a previously set variable that consists of an existing harmonized partner's venue ID.
PilgrimSdk.checkInAtVenueWithPartnerVenueId(venueId);