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 FreeEvery 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).
- location.
- 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:
XML
x
1
<application>
2
<meta-data
3
android:name="com.google.android.awareness.API_KEY"
4
android:value="YOUR_API_KEY"/>
5
</application>
Now you only have to add a dependency to Gradle:
Java
xxxxxxxxxx
1
1
implementation 'com.google.android.gms:play-services-awareness:{last_version}'
Don’t forget about the permissions; you should add the following to the manifest for that purpose:
XML
xxxxxxxxxx
1
1
<uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION"/>
2
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION"/>
*Don’t also forget about permissions checking in the app.
That’s all, now you can use the Awareness API in full.
Snapshot API
As I mentioned earlier, the Snapshot API informs about a users's live status.
You should first initialize the SnapshotClient.
Java
xxxxxxxxxx
1
1
al snapshotClient = Awareness.getSnapshotClient(this)
Now we can get data about the user’s activity right at the moment.
Headphones
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 PLUGGED_IN or UNPLUGGED.
It’s also reasonable to add addOnFailureListener, which returns Exception if something has gone wrong.
Example:
Java
xxxxxxxxxx
1
10
9
1
private fun snapshotCheckHeadphones() {
2
snapshotClient.headphoneState
3
.addOnSuccessListener {
4
snapshotHeadphonesContainer.text = it.headphoneState.toString(this)
5
}
6
.addOnFailureListener {
7
handleSnapshotError(snapshotHeadphonesContainer, it)
8
}
9
}
toString - this is the expanding feature to make the code look simpler.
Java
xxxxxxxxxx
1
13
1
fun HeadphoneState.toString(context: Context): String {
2
return context.getString(
3
R.string.headphones_state,
4
if (state == HeadphoneState.PLUGGED_IN) {
5
context.getString(R.string.headphones_state_connect)
6
} else {
7
context.getString(
8
R.string.headphones_state_disconnected
9
)
10
}
11
)
12
}
Location
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 getLocation() in 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.
Example:
Java
xxxxxxxxxx
1
14
1
private fun snapshotGetLocation() {
2
snapshotClient.location
3
.addOnSuccessListener {
4
with(it.location) {
5
snapshotLocationContainer.text = getString(
6
R.string.user_location,
7
latitude, longitude, altitude, accuracy
8
)
9
}
10
}
11
.addOnFailureListener {
12
handleSnapshotError(snapshotLocationContainer, it)
13
}
14
}
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.
User Activity
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.
Example:
Java
xxxxxxxxxx
1
14
1
snapshotClient.detectedActivity
2
.addOnSuccessListener {
3
with(it.activityRecognitionResult) {
4
snapshotActivityContainer.text = getString(
5
R.string.user_activity,
6
mostProbableActivity.stateString(),
7
mostProbableActivity.confidence
8
)
9
}
10
}
11
.addOnFailureListener {
12
handleSnapshotError(snapshotActivityContainer, it)
13
}
14
stateString - it’s the extension function, which returns the text value of the activity type.
Java
xxxxxxxxxx
1
18
1
fun DetectedActivity.stateString(): String {
2
return when (type) {
3
0 -> "IN_VEHICLE"
4
1 -> "ON_BICYCLE"
5
2 -> "ON_FOOT"
6
3 -> "STILL"
7
4 -> "UNKNOWN"
8
5 -> "TILTING"
9
6, 9, 10, 11, 12, 13, 14, 15 -> type.toString()
10
7 -> "WALKING"
11
8 -> "RUNNING"
12
16 -> "IN_ROAD_VEHICLE"
13
17 -> "IN_RAIL_VEHICLE"
14
18 -> "IN_TWO_WHEELER_VEHICLE"
15
19 -> "IN_FOUR_WHEELER_VEHICLE"
16
else -> type.toString()
17
}
18
}
Fence API
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 BroadcastReceiver.
Like this for example:
Java
xxxxxxxxxx
1
20
1
inner class FenceReceiver : BroadcastReceiver() {
2
3
override fun onReceive(context: Context, intent: Intent) {
4
val fenceState = FenceState.extract(intent)
5
if (fenceState.fenceKey == FENCE_KEY) {
6
when (fenceState.currentState) {
7
FenceState.TRUE -> {
8
// We've entered the fence
9
}
10
FenceState.FALSE -> {
11
// We're not in the fence
12
}
13
FenceState.UNKNOWN -> {
14
// Something went wrong
15
}
16
}
17
}
18
}
19
}
20
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 FenceReceiver in onCreate
registerReceiver(fenceReceiver, IntentFilter(FENCE_RECEIVER_ACTION))
And to disconnect it at onDestroy:
unregisterReceiver(fenceReceiver)
For the system to send us changes, we should create PendingIntent.
Java
xxxxxxxxxx
1
1
val intent = Intent(FENCE_RECEIVER_ACTION)
2
val mPendingIntent =
3
PendingIntent.getBroadcast(this, 0, intent, PendingIntent.FLAG_UPDATE_CURRENT)
Then we should define which activity we are interested in. Let’s take the headphones plugged in and running for example.
Java
xxxxxxxxxx
1
1
val fence = AwarenessFence.and(HeadphoneFence.during(HeadphoneState.PLUGGED_IN), DetectedActivityFence.during(DetectedActivityFence.RUNNING))
Now we gather it all together and register.
Java
xxxxxxxxxx
1
13
1
fenceClient.updateFences(
2
FenceUpdateRequest.Builder().addFence(
3
FENCE_KEY,
4
fence,
5
mPendingIntent
6
).build()
7
)
8
.addOnSuccessListener {
9
//Fence created
10
}
11
.addOnFailureListener {
12
// Error while creating
13
}
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.
Java
xxxxxxxxxx
1
1
fenceClient.updateFences(
2
FenceUpdateRequest.Builder()
3
.removeFence(FENCE_KEY).build()
4
)
*If it’s necessary, you can also add successListener and failureListener for deleting.
Now that we know how to create and delete Fence, we can look at what types exist in Fence.
Headphone 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;
Location Fence
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).
Java
xxxxxxxxxx
1
1
AwarenessFence inLocationFence = LocationFence.in(
2
latitude, longitude, radius, timeInMillis);
3
AwarenessFence exitingLocationFence = LocationFence.exiting(
4
latitude, longitude, radius);
5
AwarenessFence enteringLocationFence = LocationFence.entering(
6
latitude, longitude, radius);
Activity Fence
We can know when a user started, continued, or finished a certain activity. The class DetectedActivityFence is used for this purpose. It has the starting, during, and stopping features. The type of activity is added to these features as a parameter. Let’s, for example, create Fences for all running states:
Java
xxxxxxxxxx
1
1
AwarenessFence running = DetectedActivityFence.during(DetectedActivity.RUNNING);
2
AwarenessFence startRunning = DetectedActivityFence.starting(DetectedActivity.RUNNING);
3
AwarenessFence stopRunning = DetectedActivityFence.stopping(DetectedActivity.RUNNING);
Time Fence
We can create a Fence for a certain period of time or a certain day.
Java
xxxxxxxxxx
1
1
AwarenessFence workingHoursFence = TimeFence.inInterval(startTime, endTime);
2
AwarenessFence fridayFence = TimeFence.inFridayInterval(
3
timeZone, startTime, endTime);
That’s all.
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.
Topics:
api,
android,
app development,
mobile
Published at DZone with permission of Oleksandra Liubytska. See the original article here.
Opinions expressed by DZone contributors are their own.
Comments