Circumstances are the primary element of Engine.
Following are some typical Circumstances you might configure Engine to handle:
|Any time a user is at a restaurant on a weekend night, in an area they don’t often frequent, and they are near a bar that will be showing live music in an hour|
|Any time a user is at a coffee shop they’ve never been to, but the user regularly frequents other coffee shops.|
|Any time a user is at a big electronics store that is closed, and is near another one that is open.|
The preferred method for rolling out Circumstances in Engine is through the Garage UI. However, Engine also allows for programmatically defined Circumstances, as described below.
Programmatically, Circumstances are defined as S-expressions. We’ve chosen this format because it’s:
(<comparison op> ...),
true. More will be added later.
<comparison op>is one of
notcan be nested in one another.
any-factual-placecan only occur within
nearexpressions. Exceptions to this rule are
local-minute-of-day, which can occur anywhere.
nearexpressions are implicitly
(= factual-id "foo"), where the second element of the list is one of
local-minute-of-dayare currently allowed in comparison predicates other than
any-ofpredicate must be in the form
(any-of factual-id "foo" "bar"), like
any-ofexpression whose second element is
threshold-metmust have values
The DSL runner returns only a boolean result initially. Another method returns the relevant
Places for an
near expression are returned if the
near is the only filter or is only in an
or. If the
near is in an
and, the places are only returned if the outermost
and succeeds. An
near inside a
not never returns the places.
is-open for a place that doesn’t have an
hours field is false.
The following examples reference Factual Ids, category Ids, and chain Ids.
(at (= category-id 347))
(or (at (= category-id 312)) (at (= category-id 347)))
(at (any-of category-id 312 347))
(and (at (= chain-id "ab4c54c0-d68a-012e-5619-003048cad9da")) (near (= chain-id "e60a5d2d-6e9e-4d3b-bfe4-5cebfc0c3d97")))
(and (at (= chain-id "ab4affd0-d68a-012e-5619-003048cad9da") (not is-open)) (near (= category-id 133) is-open))
(near (= factual-id "d9d3c9e1-983d-438b-8970-ebaddaa71386"))
The default threshold for Engine determining a user is at a place is
"low". It is intended to provide a reasonable
level of confidence that the device is at the place defined in your DSL expression. If you find that the false positive rate for users being at specific places is too high for your use case, you can override the threshold:
(at (= chain-id "ab4c54c0-d68a-012e-5619-003048cad9da") (= threshold-met "high"))