Get started

This document explains how to start to develop with the Awareness API on Android. The Awareness API is part of Google Play services.

To use the Awareness API, you need a Google Account. If you already have an account, then you're all set. You might also want a separate Google Account for testing purposes.

Set up Google Play services

To access the Awareness API, your app's development project must include Google Play services. Download and install the Google Play services component through the SDK Manager and add the library to your project. For details, see Set up Google Play services.

Update gradle dependencies

Awareness API version 17.1.0 introduced a connectionless Google Play services model, which removed the need for GoogleAPIClient. To learn more about this change, review the associated Release notes. However, you need to update your build.gradle file to include dependencies for the Awareness API and the Places SDK for Android, as shown in the following example:

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile 'com.android.support:appcompat-v7:25.3.1'
    compile 'com.android.support.constraint:constraint-layout:1.0.2'
    compile 'com.android.support:design:25.3.1'
    compile 'com.google.android.gms:play-services-awareness:17.1.0'

Add your API key

If you haven't already enabled the Awareness API and obtained a Google API key, follow the steps in Signup and API keys to do so.

Add your API key to your app manifest, as shown in the following code sample. Replace YOUR_API_KEY with your own API key:

<application>
  ...
  <meta-data
      android:name="com.google.android.awareness.API_KEY"
      android:value="<var>YOUR_API_KEY</var>"/>
</application>

If you want beacon snapshots, or you use beacon fences, declare the following:

<meta-data
   android:name="com.google.android.nearby.messages.API_KEY"
   android:value="<var>YOUR_API_KEY</var>" />

Declare Android permissions in AndroidManifest.xml

Your app must declare permissions for each API method that's used. The required permissions vary. It depends on the API methods and fence types used by your app.

See Required permissions for more information.

Import Awareness API dependencies

With the connectionless Google Play services model, it's not required that you connect to the Awareness API. Instead, you can import the functionality of the Awareness API into your main activity. Use the following sample code to do so:

import com.google.android.gms.awareness.Awareness;
import com.google.android.gms.awareness.fence.AwarenessFence;
import com.google.android.gms.awareness.fence.DetectedActivityFence;
import com.google.android.gms.awareness.fence.FenceState;
import com.google.android.gms.awareness.fence.FenceUpdateRequest;
import com.google.android.gms.awareness.fence.HeadphoneFence;
import com.google.android.gms.awareness.snapshot.DetectedActivityResponse;
import com.google.android.gms.awareness.snapshot.HeadphoneStateResponse;
import com.google.android.gms.awareness.state.HeadphoneState;
import com.google.android.gms.location.ActivityRecognitionResult;
import com.google.android.gms.location.DetectedActivity;
import com.google.android.gms.tasks.OnFailureListener;
import com.google.android.gms.tasks.OnSuccessListener;

Example call

The following example call to getDetectedActivity() demonstrates how to use the connectionless Google Play services model with the Awareness API:

    // Each type of contextual information in the snapshot API has a corresponding "get" method.
    // For instance, this is how to get the user's current Activity.
    Awareness.getSnapshotClient(this).getDetectedActivity()
        .addOnSuccessListener(new OnSuccessListener<DetectedActivityResponse>() {
            @Override
            public void onSuccess(DetectedActivityResponse dar) {
                ActivityRecognitionResult arr = dar.getActivityRecognitionResult();
                // getMostProbableActivity() is good enough for basic Activity detection.
                // To work within a threshold of confidence,
                // use ActivityRecognitionResult.getProbableActivities() to get a list of
                // potential current activities, and check the confidence of each one.
                DetectedActivity probableActivity = arr.getMostProbableActivity();

                int confidence = probableActivity.getConfidence();
                String activityStr = probableActivity.toString();
                mLogFragment.getLogView().println("Activity: " + activityStr
                    + ", Confidence: " + confidence + "/100");
            }
        })