Temporal States

Context is all about timing. With the Set SDK, developers have access to a wide range of temporal context features that capture the key moments in a user’s daily life. Is the user at home on the weekday? Did they arrive home late from work this evening? By characterizing a user’s activities into a set of core temporal features, it is easy for developers to time uniquely crafted notifications so that they arrive at the right moment in time to provide the best user experience possible.

Parts of the Week

Whether or not the given time is on a weekend/weekday. This is useful for separating (say) the work-week from weekend activities/contexts.

weekend / notWeekend

Whether or not it is currently the weekend (Saturday or Sunday). notWeekend is an alias for weekday.

SetSDK.on(.weekend) { event in () }
SetSDK.on(.notWeekend) { event in () }

weekday / notWeekday

Whether it is currently a weekday (Monday through Friday). weekday is an alias for weekend.

SetSDK.on(.weekday) { event in () }
SetSDK.on(.notWeekday) { event in () }

Parts of the Day

The Set SDK divides the day into four parts, including morning, afternoon, evening, and night. Useful for grouping activities into the parts of day they are most commonly associated with. All times are local to the user.

morning / notMorning

Whether or not it is currently morning-time. morning spans from 5 am to noon (12 pm).

SetSDK.on(.morning) { event in () }
SetSDK.on(.notMorning) { event in () }

afternoon / notAfternoon

Whether or not it is currently afternoon. afternoon spans from noon (12 pm) to 5pm.

SetSDK.on(.afternoon) { event in () }
SetSDK.on(.notAfternoon) { event in () }

evening / notEvening

Whether or not it is currently evening-time. evening spans from 5 to 9 pm.

SetSDK.on(.evening) { event in () }
SetSDK.on(.notEvening) { event in () }

night / notNight

Whether or not it is currently night-time. night spans from 9 pm to 5 am.

SetSDK.on(.night) { event in () }
SetSDK.on(.notNight) { event in () }

Composite Examples

Timing is everything, as the expression goes. With Set’s mobile SDK API, it is easy for developers to isolate key moments to engage with users.

// capture a moment during a user's weekend evenings
SetSDK.on(.weekend, .evening)
// A user's workweek morning
SetSDK.on(.weekday, .morning)

Places & Trips

A user’s context is largely driven where they are, where they’ve been, and where they’re going. Set provides a range a powerful place-based context features that allow developers to precisely customize their notifications to a place and time most useful for their users. The Set SDK provides an API for accessing a range of PlaceTypes, which may or may not have an actual geographic location.

For instance, if GPS data is not available, the current location of a user may be linked to a wifi hotspot instead. When geographic coordinates are available, a user is considered to be ‘at’ a location if they are observed dwelling at the specified PlaceType.

Used in combination with other context features, place-based context features can be a powerful tool for highlighting specific place-based behaviors. For example, to capture a user at home with wifi access in the evening, one can use:

SetSDK.on(.atPlace(type: .home, conditions: []), .evening, .onWifi)

[warning] Optional Permissions!

Places and Trips both work with the lowest level of user permissions, but both enhanced with Background Location permissions. Background Location allows the Set SDK to identify the temporal boundaries of places faster, identify more unique places, and classify places faster (e.g. .home).

atPlace / notAtPlace

The associated PlaceType may be one of any, home, work, or location(CLLocation). See Conditions for Places below for a detailed discussion of the conditions parameter. notAtPlace is the inverse of atPlace (i.e., whether the user is currently not ‘at’ a given PlaceType). The associated PlaceType is the same as in atPlace, although notAtPlace does not currently accept a conditions argument.

SetSDK.on(.atPlace(type: PlaceType, conditions: [Condition])) { event in () }

SetSDK.on(.notAtPlace(type: PlaceType)) { event in () }

departedFrom

Whether the user has departed from a given PlaceType. The associated PlaceType and conditions argument are the same as in atPlace. For contexts that involve a user leaving a given location, departedFrom provides an early indication of the start of a Trip or change of location.

SetSDK.on(.departedFrom(type: PlaceType, conditions: [Condition])) { event in () }

For example, to capture the start of a user’s morning commute, one can use:

SetSDK.on(.departedFrom(type: .home, conditions: []), .morning, .weekday) { event in () }

arrivedAt

The inverse of departedFrom: whether the user has arrived at a given PlaceType. The associated PlaceType and conditions argument are the same as in atPlace. For contexts that involve a user arriving at a given location, arrivedAt provides an indication of the end of a trip or change of location.

SetSDK.on(.arrivedAt(type: PlaceType, conditions: [Condition])) { event in () }

For example, to capture a user arriving at home in the evening on a weekday, one can use:

SetSDK.on(.arrivedAt(type: .home, conditions: []), .evening, .weekday) { event in () }

onTrip

Whether the user is currently ‘on a trip’. This means that the user is likely between PlaceType. The TripType may be one of any, walking, running, cycling, or automotive. Used in combination with other context features, onTrip can be a powerful tool for highlighting specific mobile behaviors.

SetSDK.on(.onTrip(type: TripType, from: PlaceType, to: PlaceType)) { event in () }

For example, to capture the weekday morning commute, one can use:

SetSDK.on(.onTrip(type: .any, from: .home, to: .work), .morning, .weekday) { event in () }

Behavior States

A user on the move is constantly changing contexts. For a developer, knowing when, where, and how a user is going about their daily activities is therefore crucial for providing a highly personalized and enjoyable user experience. The Set SDK provides an API for accessing a range of behavior states, including whether or not the user is moving, and the type (or mode) of movement.

[warning] Required Permissions!

Behavior states do not work without Motion Permission. See User Permissions.

moving / notMoving 

SetSDK.on(.moving) { event in () }
SetSDK.on(.notMoving) { event in () }

walking / notWalking 

SetSDK.on(.walking) { event in () }
SetSDK.on(.notWalking) { event in () }

running / notRunning 

SetSDK.on(.running) { event in () }
SetSDK.on(.notRunning) { event in () }

cycling / notCycling 

SetSDK.on(.cycling) { event in () }
SetSDK.on(.notCycling) { event in () }

automotive / notAutomotive 

SetSDK.on(.automotive) { event in () }
SetSDK.on(.notAutomotive) { event in () }

Device States

Knowing how a user is using their device provides useful information about their context, and about their availability for notifications. For example, a device that is backgrounded, plugged in, and unreachable is probably sitting in a desk, not being used… no point in sending a notification now. Why not wait until the user is ready to engage with your product: maybe that means unplugged and on the move? Or maybe that means later tonight, when they are on wifi and sitting at home? Either way, the Set SDK provides the API to capture those crucial moments.

foreground / background

Whether the app is in the foreground (and therefore probably in use) or in the background (and therefore probably not in use). Useful for capturing user intents and building on current app state.

SetSDK.on(.foreground) { event in () }
SetSDK.on(.background) { event in () }

onWifi / notOnWifi

Whether or not the user’s device is 'reachable' via wifi (i.e., is connected to wifi).

SetSDK.on(.onWifi) { event in () }
SetSDK.on(.notOnWifi) { event in () }

pluggedIn / notPluggedIn

Whether or not the user’s device is plugged in (and charging).

SetSDK.on(.pluggedIn) { event in () }
SetSDK.on(.notPluggedIn) { event in () }

Composite Example

Imagine not only knowing when a user is commuting to home from work, but also how they are commuting, and whether or not you can reach them? Differentiate between users based on their preferred mode of transportation as a way to fully engage with your users in a way that customizes every aspect of their in-app experience.

SetSDK.on(onTrip(type: .automotive, from: .home, to: .any), .weekend, .onCell) { event in () }

Custom Events

tracked

You can subscribe to your own custom events by the ID you provide. See SetSDK.track. While a handy tool alone, their value comes from joining these events with specific contexts of interest, see Composite Examples next.

SetSDK.on(.tracked("my-event-id", conditions: [
  .greaterThan(count: 5, inPastInterval: 3600)
])) { event in () }

Composite Examples

Respond to a specific in-app event when it occurs under desired context variables. Here, your event is triggered in the .evening on the .weekend

SetSDK.on(.tracked("my-event-id", conditions: [
  .greaterThan(count: 5, inPastInterval: 3600),
  .lessThan(count: 20, inPastInterval: 3600)
]), .weekend, .evening)

Context Conditions

As specified above, tracked and most of Set’s place-based contexts accept a conditions argument. This allows developers to enhance the existing contexts with learned conditions, making powerful contexts such as “arrived at home later than normal in the evening” possible. As non-count-based conditions are ‘learned’ over time, they also improve over time. In general, two to three days of app life is recommended. Consider results of these context triggers ‘stable’ only after a minimum of two days after app install.

normalTime

Whether the user is at a given PlaceType at a time they are often seen there. In this case, ‘normal’ is learned over time, and represents the temporal window between a user’s earliest 5% of appearances and latest 5% of appearances at the given PlaceType.

SetSDK.on(.atPlace(type: .any, conditions: [.normalTime])) { event in () }

earlierThanNormal

Whether the user is at a given PlaceType at a time earlier than normal. Again, ‘normal’ is learned over time, and earlier than normal represents any time earlier than or equal to the earliest 5% of appearances the user has made at the given PlaceType. SetSDK.on(atPlace(type: .any, conditions: [.earlierThanNormal]))

SetSDK.on(.atPlace(type: .any, conditions: [.earlierThanNormal])) { event in () }

laterThanNormal

Whether the user is at given PlaceType at a time later than normal. Again, ‘normal’ is learned over time, and later than normal represents any time later than or equal to the latest 5% of appearances the user has made at the given PlaceType.

SetSDK.on(.atPlace(type: .any, conditions: [.laterThanNormal])) { event in () }

normalDuration

Whether the user has been ‘dwelling’ at a given PlaceType for a ‘normal’ amount of time. In this case, normal is learned over time, and represents a duration range between the shortest 5% and longest 5% of their previous dwell times at the given PlaceType.

SetSDK.on(.atPlace(type: .any, conditions: [.normalDuration])) { event in () }

longerThanNormal

Whether the user has been ‘dwelling’ at a given PlaceType longer than ‘normal’. Again, normal is learned over time, and longer than normal represents dwell times greater than or equal to the longest 5% of their previous dwell times at the given PlaceType.

SetSDK.on(.atPlace(type: .any, conditions: [.longerThanNormal])) { event in () }

lowFrequency

Whether the user has spent a relatively limited amount of time at a given PlaceType. In this case, normal is learned over time, and represents up to 25% of a user’s relative dwell time. For example, if a user spends about 10% of their time at the gym, this PlaceType would qualify as a low frequency PlaceType. Conversely, if a user spends 45% of their time at work, then work would qualify as a medium frequency PlaceType.

SetSDK.on(.atPlace(type: .any, conditions: [.lowFrequency])) { event in () }

mediumFrequency

Whether the user has spent an average (i.e., sometimes visits) amount of time at a given PlaceType. Again, normal is learned over time, and medium frequency represents between 25% and 75% of a user’s relative dwell time. See above example for details.

SetSDK.on(.atPlace(type: .any, conditions: [.mediumFrequency])) { event in () }

highFrequency

Whether the user has spent a significant amount of time at a given PlaceType. Again, normal is learned over time, and high frequency represents more than about 75% of a user’s relative dwell time. See above example for details.

SetSDK.on(.atPlace(type: .any, conditions: [.highFrequency])) { event in () }

lessThan

Whether the context has occurred less than count times in the provided past interval (seconds).

SetSDK.on(.atPlace(type: .any, conditions: [
  .lessThan(count: 3, inPastInterval: 3600)
])) { event in () }

lessThanOrEqualTo

Whether the context has occurred less than or equal to count times in the provided past interval (seconds).

SetSDK.on(.tracked(event: "my-event", conditions: [
  .lessThanOrEqualTo(count: 3, inPastInterval: 3600)
])) { event in () }

greaterThan

Whether the context has occurred greater than count times in the provided past interval (seconds).

SetSDK.on(.atPlace(type: .any, conditions: [
  .greaterThan(count: 3, inPastInterval: 3600)
])) { event in () }

greaterThanOrEqualTo

Whether the context has occurred greater than or equal to count times in the provided past interval (seconds).

SetSDK.on(.tracked(event: "my-event", conditions: [
  .greaterThanOrEqualTo(count: 3, inPastInterval: 3600)
])) { event in () }

equalTo

Whether the context has occurred equal to count times in the provided past interval (seconds).

SetSDK.on(.tracked(event: "my-event", conditions: [
  .equalTo(count: 3, inPastInterval: 3600)
])) { event in () }

Composite Examples

As mentioned above, the combination of temporal, and place-based context features, with a growing list of context conditions, provides a powerful framework for developing highly nuanced user contexts. This allows developers to hone their notifications to that perfect moment when their users are ideally situated to receive updates, new information, or gentle app reminders.

// To respond to a user at a place later and longer than normal on a weekday morning:
SetSDK.on(.atPlace(type: .any, conditions: [.laterThanNormal, .longerThanNormal]), .morning, .weekday)


Get in touch

results matching ""

    No results matching ""