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.

FSQPPilgrimManager.shared().hasHomeOrWork()
    
FrequentLocations.hasHomeOrWork(context)
    

Important: 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. An example of this simple check on iOS is below:

func fsqpPilgrimManager(_ locationManager: FSQPPilgrimManager, didVisit visit: FSQPVisit) {
    if FSQPPilgrimManager.shared().hasHomeOrWork() {

        // Home and work are set. Lets print them out
        print(FSQPPilgrimManager.shared().homeLocations)
        print(FSQPPilgrimManager.shared().workLocations)

    } else if visit.confidence != .high {
        // Home and work aren't set and visit confidence isn't High
        // Depending on my application I might not want to trust this visit
    }
}
    

Other Possible Venues

To enable a list of “other venues” to be populated in your arrival events, there is a checkbox on the Pilgrim Console that you can turn on to began to receiving these venues. The venues are alternate places the device may be in order of confidence.

You can access the other places as follows:

func fsqpPilgrimManager(_ locationManager: FSQPPilgrimManager, didVisit visit: FSQPVisit) {
    let otherVenues = visit.otherPossibleVenues
    // Do something with the alternate venues
}
    
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
    }
}
    

Nearby Venues

You can configure proximity based nearby notifications at a global and user level. For global settings (one’s that apply to all of your users), you can configure those in the Pilgrim console on your developer site. You can read more about configuring global nearby triggers here.

User specific triggers might be useful if you have a specific piece of content that the user requested to be notified about (e.g “Remind me when I’m near the grocery store to get some candy”). You will set a list of NearbyTrigger on the Pilgrim SDK and those will be used on any subsequent stops to check for a match. These can be set and updated at any time.

To set nearby triggers on an individual device:

        var triggers = [FSQPNearbyTrigger]()
        triggers.append(FSQPNearbyTrigger(triggerType: .venue, fsqId: "venueId"))
        triggers.append(FSQPNearbyTrigger(triggerType: .category, fsqId: "categoryId"))
        triggers.append(FSQPNearbyTrigger(triggerType: .chain, fsqId: "chainId"))

        FSQPPilgrimManager.shared().nearbyTriggers = triggers
    
        List<NearbyTrigger> trigs = new ArrayList<>();
        trigs.add(new NearbyTrigger(TriggerPlaceType.CATEGORY, "categoryid"));
        trigs.add(new NearbyTrigger(TriggerPlaceType.CHAIN, "starbuckschainid"));
        trigs.add(new NearbyTrigger(TriggerPlaceType.PLACE, "specificvenueid"));
        PilgrimSdk.get().setNearbyTriggers(trigs);
    

To handle nearby place notifications:

    // Inspect the nearbyVenues property on the visit object in - (void)fsqpPilgrimManager:(FSQPPilgrimManager *)locationManager didVisit:(FSQPVisit *)visit; as follows:
    func fsqpPilgrimManager(_ locationManager: FSQPPilgrimManager, didVisit visit: FSQPVisit) {
        // The `nearbyVenues` property is an array of regular `FSQPVenue`s
        if let nearbyVenues = visit.nearbyVenues {
            for nearbyVenue in nearbyVenues {
                // Handle nearby venue
            }
        }
    }
    
    // Override the other method in PilgrimNotificationHandler as follows:
    protected static final PilgrimNotificationHandler pilgrimNotificationHandler = new PilgrimNotificationHandler() {
        @Override
        public void handlePlaceNotification(Context context, PilgrimSdkPlaceNotification notif) {
        }
        @Override
        public void handleNearbyNotification(Context context, PilgrimSdkNearbyNotification notif) {
            List<NearbyVenue> nearby = notif.getNearbyVenues();
            // A `NearbyVenue` object has a normal `Venue` and a `List<TriggerPlaceType>` that tells you the kind of trigger that it matched. For example, if you were triggering on nearby coffee shops and Starbucks, a Starbucks would be returned with both Chain and Category place types.
        }
    }
    

Custom User Data

On occasion, you may want to send custom user data into Pilgrim to pass along to another server or service. This is common if you want to tie a Pilgrim event to a specific user in your own database or in a third-party MMA integration. Once set, the custom user data will be passed along within our webhook payload.

Where to set

Ideally, the user info should be set in Application#onCreate (for Android) or in the AppDelegate’s didFinishLaunchingWithOptions (for iOS). Setting it in other locations of your app could result in only sending the user info once that specific process is open. If the app ever dies or the user closes the app, the next time Pilgrim wakes the app up, the value may not be stored (and thus not get sent to the webhook or MMA). The Pilgrim SDK doesn’t persist the userInfo dictionary, it needs to be set every time.

If setting the user info in the Application#onCreate or AppDelegate’s didFinishLaunchingWithOptions is not feasible, the general recommendation is that you set it as soon as you have a way to identify your user (upon logging in or once you have their session in the app).

It is also important to remember that while you are not responsible for if a user revokes location permissions, you’ll probably want to stop Pilgrim if a user logs out of their account within the app; otherwise, you’ll receive visits without any user associated.

Examples

// NOTE: the below code should be placed AFTER you set up the SDK (ideally in AppDelegate's didFinishLaunchingWithOptions) using PilgrimManager.configure(...)

// the String myCustomUserId would be a previously set variable that stores the user's unique id:
PilgrimManager.shared().userInfo.setUserId(myCustomUserId)
// You can also set other custom fields using:
PilgrimManager.shared().userInfo.setUserInfo("myData", forKey: "myKey")
// NOTE: the below code should be placed AFTER you set up the SDK (ideally in AppDelegate's didFinishLaunchingWithOptions) using [[FSQPPilgrimManager sharedManager] configureWith...]

// the String myCustomUserId would be a previously set variable that stores the user's unique id:
[FSQPPilgrimManager sharedManager].userInfo  setUserId:myCustomUserId];
// You can also set other custom fields using:
NSString *myCustomField = [NSString stringWithFormat:@"My custom value"];
[FSQPPilgrimManager sharedManager].userInfo  setUserInfo:myCustomField forKey:@"myCustomField"];
// NOTE: the below code should be placed AFTER you set up the SDK (ideally in Application#onCreate) using PilgrimSdk.with(builder);

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("myCustomField", "My custom value");
PilgrimSdk.get().setUserInfo(userInfo);

Testing

The best and quickest way to test and confirm that you are accurately setting the custom user data is to set up 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.


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 have a guide for venue harmonization in our API documentation, but we can also store a copy of the harmonization and return your venue Id in the Pilgrim visit callback. We enable this on a parter-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.

func fsqpPilgrimManager(_ locationManager: FSQPPilgrimManager, didVisit visit: FSQPVisit) {
    let partnerId = visit.venue?.partnerVenueId
    // Do something with your own venue Id
}
    
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
    }
}
    

Next Steps

Check out the Changelog for the latest updates.

Changelog