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 you have 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
work instead of
venue. For example, a webhook payload for a work arrival might look something like this:
To check if a user has configured their home/work locations, you can see if this has been set by checking the
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. An example of this simple check on iOS is below:
Non Home and Work user states will be accessible as an array of states via the
userStates property on the
visit object in the SDK, as well as via any
visit webhook events. Each state will have a
name and a
properties array that could contain additional relevant data pertaining to the state.
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 travelling. 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.
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.”
For examples of how user states are sent via webhook events, see the webhook examples.
If you are interested in learning more about this feature, please reach out to your Foursquare contact.