Fence API Overview

In the Awareness API, the concept of "fences" is taken from geofencing, in which a geographic region, or "geofence", is defined, and an app receives callbacks when a user enters or leaves this region. The Fence API expands on the concept of geofencing to include many other context conditions in addition to geographical proximity. An app receives callbacks whenever the context state transitions. For example, if your app defines a fence for headphones, it will get callbacks when the headphones are plugged in, and when they are unplugged.

Using the Fence API, you can define fences based on context signals such as:

  • The user's current location (lat/lng).
  • The user's current activity (walking, driving, etc.).
  • Device-specific conditions, such as whether the headphones are plugged in.
  • Proximity to nearby beacons.

The Fence API lets you create fences by combining multiple context signals using AND, OR, and NOT boolean operators. Your app then receives callbacks whenever the fence conditions are met. Some examples of possible fences include:

  • User plugs in headphones and starts walking.
  • User enters a 100-meter geofence before 5 p.m. on a weekday.
  • User enters range of a specific BLE beacon.

The following example shows defining a fence that activates whenever the user is walking:

AwarenessFence walkingFence = DetectedActivityFence.during(DetectedActivityFence.WALKING);

Once you have defined a fence, you must:

  • Register the fence to receive callbacks by calling updateFences.
  • Define a callback that will be invoked when the fence state changes.

The following example shows a method that creates and registers a fence. In this example, a custom subclass of BroadcastReceiver is used to handle the Intent when the fence is triggered.

// Declare variables for pending intent and fence receiver.
private PendingIntent myPendingIntent;
private MyFenceReceiver myFenceReceiver;

// Initialize myPendingIntent and fence receiver in onCreate().
protected void onCreate(Bundle savedInstanceState) {
    Intent intent = new Intent(FENCE_RECEIVER_ACTION);
    myPendingIntent = PendingIntent.getBroadcast(this, 0, intent, 0);
    MyFenceReceiver = new myFenceReceiver();
    registerReceiver(myFenceReceiver, new IntentFilter(FENCE_RECEIVER_ACTION));

// Create a fence.
AwarenessFence headphoneFence = HeadphoneFence.during(HeadphoneState.PLUGGED_IN);

// Register the fence to receive callbacks.
// The fence key uniquely identifies the fence.
        new FenceUpdateRequest.Builder()
            .addFence("headphoneFenceKey", headphoneFence, myPendingIntent)
        .setResultCallback(new ResultCallback<Status>() {
            public void onResult(@NonNull Status status) {
                if (status.isSuccess()) {
                    Log.i(TAG, "Fence was successfully registered.");
                } else {
                    Log.e(TAG, "Fence could not be registered: " + status);

// Handle the callback on the Intent.
public class MyFenceReceiver extends BroadcastReceiver {
    public void onReceive(Context context, Intent intent) {
        FenceState fenceState = FenceState.extract(intent);

        if (TextUtils.equals(fenceState.getFenceKey(), "headphoneFence")) {
            switch(fenceState.getCurrentState()) {
                case FenceState.TRUE:
                    Log.i(TAG, "Headphones are plugged in.");
                case FenceState.FALSE:
                    Log.i(TAG, "Headphones are NOT plugged in.");
                case FenceState.UNKNOWN:
                    Log.i(TAG, "The headphone fence is in an unknown state.");

Send feedback about...

Google Awareness API