Using the Awareness API for Android

Context and the Creation of Delightful, Intelligent, Apps

The Awareness API helps you engage users in specific situations using simple, battery efficient ways to check their current context, and to create “fences” so your app can react to a specific set of conditions.

A unified sensing platform, enabling apps to be aware of all aspects of a user’s context, while managing system health.

At launch, Awareness offers 7 context types describing:

  • “when” in local time.
  • “where” in terms of specific locations, and semantic descriptions such as categories of places.
  • “what” activity the user is doing.
  • “nearby” beacons
  • “device state” such as connected headphones.
  • “ambient conditions” beginning with the local weather.

I’ve talked about incorporating user context into your app before. Quite a lot. It’s one of my favorite topics for making your apps delightful, intuitive, and intelligent.

Your phone knows you; just how much does it know?

We take our phones with us everywhere; packed with sensors phones are increasingly aware of their environments. As app developers, this gives us an amazing opportunity to create personalized, contextualized experiences and delight our users.

Try this thought experiment:

Imagine. You’re sitting in a train, or at a concert. I ask you to take out your phone — unlock it — and hand it over to whoever happens to be sitting next to you.

Can you actually imagine that, or did your vision fade to white and a high-pitched sound slowly overwhelm your senses while your mind screamed in rebellion at the very thought of such horror?

Me? I’d rather give strangers my home address and vacation schedule than access to my unlocked phone.

It’s always been possible to take advantage of sensors to better understand your user’s environment

Combining device state with the results from a dozen different sensors, and combining those signals with additional web-sourced information is a challenging proposition. Keeping track of changes adds a further layer of difficulty, compounded by the need to balance all this with ensuring you aren’t draining the battery.

In contrast, the following code will allow your app to react — even if it’s not currently open — whenever your user drives within 1,000 meters of a specific location during a certain time window each day.

void createFence() {
AwarenessFence areaAroundStore =, STORE_LONGITUDE, 1000, 0L);
  AwarenessFence duringDriving = 
  AwarenessFence openHours =   
  AwarenessFence drivingNearStore =
AwarenessFence.and(areaAroundStore, duringDriving, openHours);

new FenceUpdateRequest.Builder()
.addFence(DRIVING_NEAR, drivingNearStore, mPendingIntent)
void onReceive(Context context, Intent intent) {
FenceState fenceState = FenceState.extract(intent);
if (fenceState.getFenceKey().equals(“startDriving”))
if (fenceState.getCurrentState() == FenceState.TRUE) {
// TODO: React to user driving past a specific business
// during their open hours.

This part is simple and efficient, so you’re free to focus on creating innovative experiences using this information, rather than spending months tweaking refresh rates.

Making your app smarter reduces the friction for users

Understanding your user’s context gives you a great opportunity to increase engagement through improved relevance.

For example, if your user has asked for notifications to encourage them to exercise more, you could use a combination of an Awareness Fence and the Snapshot API to react to good weather, proximity to a local park, and being after work to suggest they go for a run.

If you have a music app, you could use the Snapshot API at startup to learn that your user is sitting in a cafe with their headphones on at 9am on a rainy day, and offer them some suitably mellow tunes. Or if they’re on a beach on a hot Summer’s night you can suggest their party mix.

Or you could get really creative

Each time your app starts, take a Snapshot of the current context and look for patterns in behavior. Do they always put on the same playlist at a certain time and place? Do they always go for a jog on the same trail when the weather is good / use the same gym when it’s raining?

Make sure the app starts in the right state, so they can just hit play, or “start tracking” when they open your app. Perhaps even ask them if they’d like a notification as a shortcut when these conditions are met, so they don’t even have to start the app themselves.

You can use a similar approach to tweaking efficiency. Notice that they always read stock tips on the bus each morning? Pre-fetch those articles ahead of time to minimize load latency.

Be delightful not disturbing

Your app should be an intuitive friend, not a creepy stalker; use Awareness to improve the quality of notifications, not to spam your users.

Tell your users what you’re doing, why you’re doing it, and whenever possible let them say no.

Your phone knows you, so it’s not weird if your exercise tracker is ready to track the run you do every afternoon, or that your news app has cached the topics you read every morning.

As you add more context awareness to your app, the more useful and intuitive it becomes, BUT — don’t fall into the Uncanny App Valley.

Delight measured against the amount of contextual information you’re using

The more context you ask of your users, the more trust you’re asking for — so remember that it’s hard to build that trust but very easy to lose it — even if what you’re doing is confusing or obscure rather than malicious.

To avoid the Uncanny App Valley, you have to avoid surprising your users by using data they didn’t realize you had.

In practice that means:

  • Always explain how you’re using their context, and what you’re doing with the data — both on the device, and especially if that data is being stored or transmitted.
  • Don’t transmit or store location or contact details unless that’s clear to the user, and a critical part of your app’s functionality.
  • Have a clear privacy policy that’s easy for users to find and understand.
  • If you are storing any context data, make it simple and easy for users to erase it — both on their device and on your servers.

The Awareness team has built an extensible platform, and they’re looking forward to adding addition contexts to the Awareness API. They’d love to hear from you to learn which signals you’d find most powerful to help make your apps more delightful.

How will you use the Awareness API? Which additional signals would you like it to offer?