Advanced Functionality

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:

PilgrimSdk.stop(context);

This will stop all Pilgrim activity. To resume Pilgrim, just call start() again.

Clear 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:

PilgrimSdk.clearAllData(context);

You cannot call this when monitoring visits. You need to call stop() first.

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 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.

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:

protected static final PilgrimNotificationHandler pilgrimNotificationHandler = new PilgrimNotificationHandler() {
    @Override
    public void handlePlaceNotification(Context context, PilgrimSdkPlaceNotification notif) {
        CurrentPlace currentPlace = notif.getCurrentPlace();
        List<Venue> otherVenues = currentPlace.getOtherPossibleVenues();
        // Do something with the alternate venues
    }
}

Venue Harmonization

If you maintain your own venue database, you may want to know if a visit has occurred at one of those venues. We can also store a copy of the harmonization and return your venue Id in the Pilgrim visit callback. We enable this on a partner-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.

protected static final PilgrimNotificationHandler pilgrimNotificationHandler = new PilgrimNotificationHandler() {
    @Override
    public void handlePlaceNotification(Context context, PilgrimSdkPlaceNotification notif) {
        String partnerId = notif.getContentId();
        // Do something with your own venue Id
    }
}

private val pilgrimNotificationHandler = object : PilgrimNotificationHandler() {
    // Primary visit handler
    override fun handleVisit(context: Context, notification: PilgrimSdkVisitNotification) {
        val visit = notification.visit
        val partnerId = visit.venue?.partnerVenueId
        Log.d("PilgrimSDK", partnerId.toString())
    }