Affiliate links on Android Authority may earn us a commission.Learn more.
Using the Awareness API in your Android app
July 23, 2025
The Awareness API was introduced at Google I/O 2016, and is a new way of engaging users in specific situations, by either checking their current device context/state or by creating virtual fences around specific conditions. When these conditions are met, your app is notified by the OS.
Via the Awareness API an app can get data about what Android has inferred about what is going on. That way an app can tell when a person is in a moving vehicle, when a person is in a vehicle moving through a given area, when a person is in a vehicle moving through a given area at a given time, when a person is in a vehicle moving through a given area at a given time with their headphones on… You get the picture.
Using the Awareness API helps your app react intelligently, and in a battery efficient way. Rather than multiple apps polling the user’s context to find if any given set of conditions are met, the API allows apps define their fence conditions, and then get a notification when the device current state matches the defined conditions.
Be aware that while some uses of the Awareness API can make your app feel smart, delightful and intuitive, too much use, or usage in an unexpected way can have the opposite effect and make your app users uncomfortable, and your app feel creepy. Remember, similar to great power, with great APIs, comes great responsibility. Use at your own discretion.
Context Types
The Awareness API offers 7 different context types as at the time of this article, but there is no reason why this can’t be expanded in the future. The current seven contexts include
Most of the above tasks can be accomplished with other previously existing APIs. However, the power of the Awareness API is
Awareness APIs
There are two sets of APIs available under the Awareness API family.
Preparation
The awareness API is a part of Google Play Services, and to use it, your application must be set up to use Google Mobile Services (com.google.android.gms). So, you need to setup GMS via the Google developer Console, and also on the application.
On Google Developer Console
To setup GMS on the cloud, navigate to thedeveloper consoleand follow these steps:1. Create a project.
- Go to the API Manager page, select the Awareness API and Enable it.
Go to the Credentials tab, and Create credentials. What you want to do here is create an Android API key, so selectCreate credentials – API key – Android Key. Enter a key name, and click Add package name and fingerprint. For help creating a key, check out theGoogle support page.
A key is generated for you. Copy this key, because we are going to need it when calling the Awareness API from our application.
On Android Studio
Ensure Google Play Services is up to date on your Android SDK Manager.
Create a new project, and make sure the package name matches the package name used in step four in the section above.
Add the Awareness API dependency to your app build.gradle file
Add the following permissions to thetag in the AndroidManifest.xml file
The ACCESS_FINE_LOCATION permission is used to access Location data, used by Location, Places, Weather and Beacon. The ACTIVITY_RECOGNITION permission, as you must have guessed, is used to detect a user’s current activity. Detecting headphone plug in status doesn’t require any extra permission, neither does getting device time (Imagine if apps needed user permission to fetch device time).
- Add the followingtags to the AndroidManifest.xml tag
Replace ‘YOUR_API_KEY’ in the code snippet above with the key generated from step five of the previous section.
At this point, your app should be ready to begin using the Awareness APIs.
The Sample App
For our sample app, we have implemented three Activities:
The SnapshotActivity
The SnapshotActivity has a single button, which when clicked, fetches a Snapshot of the user’s current context across all seven contexts.
The first thing we do in the SnapshotActivity is to build a GoogleApiClient client object, and add the Awareness API, by calling addApi(Awareness.API).
When the button is clicked, the only action performed is a method call to getSnapshots();
Get DetectedActivity
The sample code below is how we fetch the DetectedActivity on the device. While developing, this would most likely be STILL. Some other possible Activities include WALKING, IN_VEHICLE and RUNNING among others.
That is all! Simply call getDetectedActivity() on Awareness.SnapshotApi, and define a ResultCallback, that gets called when the User Activity has been detected. ActivityRecognitionResult also has a method to return a list of ProbableActivities using getProbableActivities(). In the snippet above, we simply get the most probable activity and display that.
Headphone State
This is also very straightforward, and incredibly similar to the UserActivity snippet above. Actually, all the Awareness APIs are quite similar.
To get the HeadphoneState, call the getHeadphoneState() method. The callback expects a HeadphoneStateResult, and the contained HeadphoneState is either HeadphoneState.PLUGGED_IN or HeadphoneState.UNPLUGGED.
For time, we simply fetch the device time. This doesn’t require any special APIs.
For all the Location dependent Awareness contexts, we must check the user has granted permission to the ACCESS_FINE_LOCATION permission, before we attempt to fetch the device location. Also, you might want to check if the device’s location setting is turned on, before making the calls.
Sample code to check for device permission:
For more details, Google has good documentation onRequesting Permissions at Run Time.
Using the Awareness API to get Location information is shown below:
To get the Weather conditions, use the code snippet below
While we simply display the Weather using toString(), there are other more useful means of getting information from the Weather object, including getTemperature(), getFeelsLikeTemperature(), getHumidity(), getConditions() among others.
To get places around a user, you have to enable the Google Places API for Android on the Developer Console for your project.
To fetch the places around a user, use the following code snippet
Using this API, we can get a list of Places, along with a likelihood score (a number indicating the inferred likelihood that the device is at that place). The Place object returned also contains information including Address, Latitude/Longitude, phone number, and ratings among others. The Places returned with this API is backed by the same database used by both Google+ and Google Maps. It features up to 100 million businesses and points of interest worldwide (at least according to Google).
Beacons are Bluetooth low energy devices, that can be deployed, say in a store or other locations, to provide some contextual and engaging experience. For a more in depth explanation of beacons, check out theBeacon Google Developer page. For your app to get information about beacons, you have to enable the Nearby Messages API on the Developer Console for your app.
You must define a list of the beacon types you want to fetch data for. You must have already added these beacons to your Beacon Dashboard.
The implementation is pretty consistent with the other API methods.
The FenceAPI
The Fence API allows an application define certain conditions for user contexts, and when the conditions are satisfied, the app receives an alert through a PendingIntent. There are many different ways to build and handle a PendingIntent, but for the purpose of this tutorial and for brevity, we will use a BroadcastReceiver to handle it.
The FenceActivity
There are many different ways to combine Fence conditions. Multiple conditions can be combined using the logic structures AND, OR and NOT. We are going to create three different simple Fences:
All three will be handled with the same BroadcastReceiver.
The BroadcastReceiver
We define a class called FenceBroadcastReceiver.
The FenceBroadcastReceiver is pretty straightforward. In the onReceive() method, we get the FenceState from the parsed Intent. We expect three possible Fence Keys, HEADPHONE_FENCE_KEY, HEADPHONE_AND_WALKING_FENCE_KEY or HEADPHONE_OR_WALKING_FENCE_KEY.
We simply show a Toast when we get a Fence update. You will most likely want to do something much more advanced.
FenceActivity
Add Headphone Fence
To add a fence to detect when the user either plugs in or unplugs his headphones, we implement an addHeadphoneFence() method, shown below
Note that MY_FENCE_RECEIVER_ACTION and HEADPHONE_FENCE_KEY are both constants defined in the FenceActivity class. The Fence that monitors the Headphone plug in state is created with the HeadphoneFence.during() method call. The subsequent lines are used to register the headphoneFence with the API, and set the Fence’s key and PendingIntent.
Congrats. Your application is now ready to receive alerts whenever the user plugs in or unplugs headphones from the device.
Deleting a Fence
To remove a Fence, we implemented the removeFence() method below
For example, to remove the Headphone Fence added above, we simply call
Combining Fences
In the example above, we created the HeadphoneFence using HeadphoneFence.during(…). In the same vein, we can create UserActivity Fences using DetectedActivityFence.during(…). The Fence classes include:
To combine HeadphoneFence and DetectedActivityFence for example, we create both fences with the parameters we are interested in, and combine them using AwarenessFence.and() or AwarenessFence.or().
Conclusion
There are so many different possible combinations using the Awareness Fence API. You are really limited only by your imagination (and coding ability :P).
Remember, the Awareness API is one of those APIs that when used well, can result in really magical apps, but when used poorly will feel creepy and jarring. As usual, the complete source for the sample project developed for this article is available ongithubfor all. Happy coding
Thank you for being part of our community. Read ourComment Policybefore posting.
