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/Deny a Visit

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

/**
 *  @param pVisitId         The visit ID to provide feedback for.
 *  @param feedback         See FSQPVisitFeedback for options.
 *  @param actualVenueId    If the correct Foursquare venue ID is known, let pilgrim know.
 *  @param completion       A completion handler called when the transaction finishes.
 */
- (void)provideFeedbackForPVisit:(NSString *)pVisitId feedback:(FSQPVisitFeedback)feedback actualVenueId:(nullable NSString *)actualVenueId completion:(nullable void (^)(NSError * _Nullable error))completion;
/**
 * @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.
 */
PilgrimSdk.leaveVisitFeedback(@NonNull String pilgrimVisitId, @NonNull VisitFeedback feedback, String actualVenueId)
    

The available feedback options for iOS are:

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

The available feedback options for Android are:

Feedback Description
VisitFeedback.CONFIRM The visit was at the correct venue.
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 UX doesn’t allow for wrongVenue, use this.

An example providing wrongVenue feedback with the correct venueId:

FSQPPilgrimManager.shared().visitFeedbackProvider?.provideFeedback(forPVisit: visit.pilgrimVisitId,
                                                                   feedback: FSQPVisitFeedback.wrongVenue,
                                                                   actualVenueId: "4ed92126f5b92139871ce962",
                                                                   completion: nil)
PilgrimSdk.leaveVisitFeedback(visitId, VisitFeedback.WRONG_VENUE, "4ed92126f5b92139871ce962");

A more robust example of how you might add a feedback drawer to easily allow users to confirm or deny the accuracy of their visit on iOS:

//
//  UIAlertController+Feedback.swift
//  Copyright © 2018 Foursquare. All rights reserved.
//
import Foundation

extension UIAlertController {
    static func presentFeedbackAlertControllerForVisit(_ visit: FSQPVisit, controller: UIViewController, dismiss: (() -> Void)? = nil) {
        let alertController = UIAlertController(title: "Provide feedback:", message: visit.description, preferredStyle: .actionSheet)

        if let pilgrimVisitId = visit.pilgrimVisitId, let feedbackProvider = FSQPPilgrimManager.shared().feedbackProvider {
            let correctAction = UIAlertAction(title: "Confirm", style: .default) { (action) -> Void in
                feedbackProvider.provideFeedback(
                    forPVisit: pilgrimVisitId,
                    feedback: .confirm,
                    actualVenueId: nil,
                    completion: nil)
            }
            alertController.addAction(correctAction)

            let falseStopAction = UIAlertAction(title: "False stop", style: .default) { (action) -> Void in
                feedbackProvider.provideFeedback(
                    forPVisit: pilgrimVisitId,
                    feedback: .falseStop,
                    actualVenueId: nil,
                    completion: nil)
            }
            alertController.addAction(falseStopAction)

            let wrongVenueAction = UIAlertAction(title: "Wrong venue", style: .default) { (action) -> Void in
                // TODO: If selected, you should probably add an option for users to select the accurate venue
                // and send in the actual venue ID.
                feedbackProvider.provideFeedback(
                    forPVisit: pilgrimVisitId,
                    feedback: .wrongVenue,
                    actualVenueId: nil,
                    completion: nil)
            }
            alertController.addAction(wrongVenueAction)

            let denyAction = UIAlertAction(title: "Deny", style: .default) { (action) -> Void in
                feedbackProvider.provideFeedback(
                    forPVisit: pilgrimVisitId,
                    feedback: .deny,
                    actualVenueId: nil,
                    completion: nil)
            }
            alertController.addAction(denyAction)
        }

        let cancelAction = UIAlertAction(title: "Cancel", style: .cancel, handler: nil)
        alertController.addAction(cancelAction)

        controller.present(alertController, animated: true, completion: dismiss)
    }
}

Check-in at a (Foursquare) 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 foursquareVenueId    The foursquare venue ID where you believe the device is currently at.
 */
- (void)checkInAtVenueWithFoursquareVenueId:(NSString *)foursquareVenueId;
/**
 *  @param venueId      The foursquare venue ID where you believe the device is currently at.
 */
checkInAtVenueWithFoursquareVenueId(@NonNull final String venueId)

An example:

let foursquareHQVenueId = "4ef0e7cf7beb5932d5bdeb4e";
FSQPPilgrimManager.shared().visitFeedbackProvider?.checkInAtVenue(foursquareVenueId: foursquareHQVenueId)
final String foursquareHQVenueId = "4ef0e7cf7beb5932d5bdeb4e";
PilgrimSdk.checkInAtVenueWithFoursquareVenueId(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 partnerVenueId   A partner venue ID, that is harmonized with Foursquare, where you believe the device is currently at.
 */
- (void)checkInAtVenueWithPartnerVenueId:(NSString *)partnerVenueId;
/*
 *  @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.
FSQPPilgrimManager.shared().visitFeedbackProvider?.checkInAtVenue(partnerVenueId: venueId)
// (string) venueId is a previously set variable that consists of an existing harmonized partner's venue ID.
PilgrimSdk.checkInAtVenueWithPartnerVenueId(venueId);

Next Steps

Be sure to check out the Advanced Setup Guide for more information on Webhooks, Nearby Venues, and more.

Advanced Setup Guide