Semantic Time support now available on the Awareness APIs

Posted by Ritesh Nayak M, Product Manager

Last year at I/O we launched the href="https://developers.google.com/awareness/">Awareness API, a simple yet
powerful API that let developers use signals such as Location, Weather, Time and
User Activity to build contextually relevant app experiences.

Available via Google Play services, the Awareness API offers two ways to take
advantage of context signals within your app. The href="https://developers.google.com/awareness/android-api/snapshot-api-overview">Snapshot
API lets your app request information about the user's current context,
while the href="https://developers.google.com/awareness/android-api/fence-api-overview">Fence
API lets your app react to changes in user's context, and when it matches a
certain set of conditions. For example, "tell me whenever the user is walking
and their headphone is plugged in".

Until now, you could specify a time fence on the Awareness APIs but were
restricted to using absolute/canonical representation of time. Based on
developer feedback, we realized that the flexibility of the API in regards to
building time fences did not support higher level abstractions people use when
they think and talk about time. "This weekend", "on the next
holiday", "after sunset", are all very common and colloquial ways
of expressing time. That's why we're adding Semantic time support to these APIs
starting today

For e.g., if you were building a fitness app and wanted a way to prompt users
everyday morning to start their routine, or if you're a reading app that wants
to turn on night mode after dusk; you would have to query a 3p API for
sunrise/sunset information at the user location and then write up an Awareness
fence with those canonical time values. With our latest update, you can use our
href="https://developers.google.com/android/reference/com/google/android/gms/awareness/fence/TimeFence.html#TIME_INSTANT_SUNRISE">TIME_INSTANT_SUNRISE
and href="https://developers.google.com/android/reference/com/google/android/gms/awareness/fence/TimeFence.html#TIME_INSTANT_SUNSET">TIME_INSTANT_SUNSET
constants and let the platform manage all the complexity for you.

Let's look at an example. Suppose you're building a fitness app which prompts
users on Tuesday, and Thursday around sunrise to begin their morning work out.
You can set up this triggering using the following lines of code.

class="prettyprint">// A sun-state-based fence that is TRUE only on Tuesday and Thursday during Sunrise
AwarenessFence.and(
TimeFence.aroundTimeInstant(TimeFence.TIME_INSTANT_SUNRISE,
-10 * ONE_MINUTE_MILLIS, 5 * ONE_MINUTE_MILLIS),
AwarenessFence.or(
TimeFence.inIntervalOfDay(TimeFence.DAY_OF_WEEK_TUESDAY,
0, ONE_DAY_MILLIS),
TimeFence.inIntervalOfDay(TimeFence.DAY_OF_WEEK_THURSDAY,
0, ONE_DAY_MILLIS)));

One of our favorite semantic time features is public holidays. Every country and
regions within it have different holidays. Assume you were a local hiking &
adventure app that wants to show users activities they can indulge in on a
holiday that falls on a Friday or a Monday. You can use a combination of Days
and Holiday flags to identify this state for all your users around the world.
You can do this with just 3 lines of code and have this work in any part of the
world.

class="prettyprint">// A local-time fence that is TRUE only on public holidays in the
// device locale that fall on Fridays or Mondays.
AwarenessFence.and(
TimeFence.inTimeInterval(TimeFence.TIME_INTERVAL_HOLIDAY),
AwarenessFence.or(
TimeFence.inIntervalOfDay(TimeFence.DAY_OF_WEEK_FRIDAY,
9 * ONE_HOUR_MILLIS, 11 * ONE_HOUR_MILLIS),
TimeFence.inIntervalOfDay(TimeFence.DAY_OF_WEEK_MONDAY,
9 * ONE_HOUR_MILLIS, 11 * ONE_HOUR_MILLIS)));

In both example cases, Awareness does the heavy lifting of localizing time and
holidays based on the device locale settings.

We're excited to see what problems you'll solve using this powerful API. Please
join our href="https://groups.google.com/forum/#!forum/google-context-apis/join">mailing
list to get updates about this and other Context APIs at Google.