Awareness API: What Is It and How It May Help?
Learn when Awareness API may be of use in mobile app development, in what way, and how to implement it in a project.
Join the DZone community and get the full member experience.Join For Free
Every year our life and daily routine are more and more closely connected with mobile phones. Modern life is extremely dynamic and that’s why mobile apps should match the users’ activity. Awareness API exists just for that purpose.
What Is This API?
Google Awareness API allows us to monitor user activity. The API allows us to get data related to the user's:
- headphone state (plugged/unplugged).
- activity (standing, driving, running, walking).
- time (local user’s time to set certain frames).
- reaction to beacons.
There are plenty of situations where these features can be used. If it’s a sports app for running, for instance, it’s possible to find out when the user started his training, and if it’s a restaurant app, there is an opportunity to notify the user about special offers or invite them to visit the restaurant when they are somewhere nearby.
The Awareness API is divided into two parts, namely:
- Snapshot API — it allows to get live info at a certain moment.
- Fence API — it registers one or several triggers, which inform us if the user is active or not.
To better understand, you can run through the code on GitHub here: https://github.com/stfalcon-studio/GoogleAwarenessDemo.
To begin we should get an API key, here is a perfect guide from Google: https://developers.google.com/awareness/android-api/get-a-key.
As soon as we’ve got the key, we should add it to the manifest file of our project. It looks like this:
Now you only have to add a dependency to Gradle:
Don’t forget about the permissions; you should add the following to the manifest for that purpose:
*Don’t also forget about permissions checking in the app.
That’s all, now you can use the Awareness API in full.
As I mentioned earlier, the Snapshot API informs about a users's live status.
You should first initialize the SnapshotClient.
Now we can get data about the user’s activity right at the moment.
With a Snapshot API we can find the current state of a user's headphones, i.e. whether they are plugged in or unplugged. This can be useful for sports apps development, for instance, to notify the user about their goal achievement, if their headphones are plugged in.
To know the headphones' state, you should just call the function
getHeadphoneState(). To get the result, add
addOnSuccessListener, which will turn us back the
HeadphoneStateResponse, with the
headphoneState. Further on,
getState will return 1 or 2, which correspond to the status
It’s also reasonable to add
addOnFailureListener, which returns
Exception if something has gone wrong.
toString - this is the expanding feature to make the code look simpler.
With the help of Snapshot API we can also find out the current user’s location.
The examples of the usage are numerous in this case. If, for instance, the app has a list of some places, we can offer the user to visit this or that place if they are interested in it and it's somewhere nearby.
To get the location you should call
OnSuccess – after this we will get
LocationResponse, which contains information about the user’s locale. We can get the info with
getLocation(), which contains latitude, longitude, altitude, and so on.
Location - it’s a standard class of the Android SDK, so you can check the manual for the detailed description of all the available functions.
Note: don’t forget to add `
android permission ACCESS_FINE_LOCATION` to the manifest as well as permission for checking.
As I already mentioned, Awareness API also allows us to check the current user activity. This can be extremely useful in fitness or news apps.
The approach is the same: we need to call the
getDetectedActivity feature, which in case of success will return
DetectedActivityResponse. From this, we can take data about user activity. We have the following features available:
getMostProbableActivity, which will return the most probable activity and
getProbableActivities, which will return a list of possible activities sorted from the most probable one.
Activity has two parameters, namely:
- Activity type — we use
getType()for getting the type of activity, the example will be below.
- Probability of the activity — which is retreived via the
getConfidence()feature — will return an int value from 0 to 100.
stateString - it’s the extension function, which returns the text value of the activity type.
Awareness API allows us to put certain conditions and listen when the activity of the users coincide with it.
We can check:
- the location of a user and if they entered a certain area.
- the user's activity when they, for instance, are walking, running, driving, etc.
- headphones' state, when they have been plugged in or unplugged.
- when the user has entered the area of beacons operation.
- time frames, when the user is in a certain timeframe of a certain weekday.
We can also combine several features, using the operators AND, OR, or NOT. We can, for instance, check the following:
- The user runs with headphones plugged in.
- The user drives and has entered a certain area.
- The headphones are plugged in during the evening time, without activity (so the user is likely in bed).
How to Start Using Fence
Firstly, to get the information about Fence's state change we should create our own
Like this for example:
Fence will receive all the changes, which refer to our registered fences. For instance, we wait till the user plugs the headphones in:
- We check if the
FENCE_KEYcoincides with the one we have registered (what it is and where it’s gotten from we’ll see below).
- Then we check the state. If it’s TRUE, then the headphones are plugged in, if it’s FALSE, then the headphones are unplugged, and the UNKNOWN state means an error has occurred and the system failed to understand the headphones’ status.
Note: don’t forget to register
And to disconnect it at
For the system to send us changes, we should create
Then we should define which activity we are interested in. Let’s take the headphones plugged in and running for example.
Now we gather it all together and register.
FENCE_KEY is necessary for us to distinguish various registered fences.
You should also not forget about Fence deleting when we have finished working with it. We use
removeFence() for this purpose, where the necessary
FENCE_KEY is rendered as a parameter.
*If it’s necessary, you can also add
failureListener for deleting.
Now that we know how to create and delete Fence, we can look at what types exist in Fence.
With headphones, everything is alike and we have the following fences:
- AwarenessFence headphonesPluggedInFence = HeadphoneFence.during(HeadphoneState.PLUGGED_IN;
- AwarenessFence headphonesUnpluggedFence = HeadphoneFence.during(HeadphoneState.UNPLUGGED;
We can create so-called "locations" and as soon as the user enters them we’ll know about it. We can check if they have entered/left a certain area or stayed in it.
You need to specify the data about the latitude, longitude, and radius of the location (for checking if the user is inside the area, you should also indicate how many milliseconds should a user stay in it).
We can know when a user started, continued, or finished a certain activity. The class
DetectedActivityFence is used for this purpose. It has the
stopping features. The type of activity is added to these features as a parameter. Let’s, for example, create Fences for all running states:
We can create a Fence for a certain period of time or a certain day.
We have had an overlook what an API is and how to use Fences and Snapshots. Thanks to them we can create more flexible apps, which facilitate the user’s usage of the application.
Published at DZone with permission of Oleksandra Liubytska. See the original article here.
Opinions expressed by DZone contributors are their own.