Geofencing with Android

Let's create a new Android project.

create android project

There's no need to add an Activity because we will only be using the project to perform a test.

create android project

Once the project is created we can add the Kuzzle Android SDK. Add this line to your build.gradle file:

Copied to clipboard!
    implementation 'io.kuzzle:sdk-android:3.0.2'

Now create a Class that will handle the Geofencing test, we will call it GeoFenceSnippet.

Connect to Kuzzle

The first thing we need to do is connect to Kuzzle. To do this write the following code:

Copied to clipboard!
kuzzle  = new Kuzzle("localhost");

Here we assume you have installed Kuzzle on your localhost, if this is not the case replace the localhost with the ip or name of the Kuzzle server.

Create a Geographical Boundary

Now that we have established a connection to Kuzzle, we will perform a subscription request that tells Kuzzle that the App wants to be notified anytime a user leaves a geographical boundary.

We define the geographical boundary in a JSONObject as follows:

Copied to clipboard!
JSONObject bigBen = new JSONObject().put("lat", 51.510357).put("lon",  -0.116773);
JSONObject filter = new JSONObject().put("geoDistance", new JSONObject().put("location", bigBen).put("distance", "2km"));

This defines a circular boundary centered around Big Ben with a radius of 2km. For more information about the geoDistance filter click here.

Note that we use the field name location to store the geopoint we are centered around. This means that Kuzzle will monitor the field named location for position changes, and so any user location document sent to Kuzzle must also contain this field.

Now the App must request a subscription to the geographical boundary defined in our filter object. To ensure that the App only receives a message when the location changes from inside the boundary to outside the boundary, we need to set the subscription scope to out, for more scope options click here.

Let's create a subscribe method and add the following code to it:

Copied to clipboard!
private void subscribe() throws JSONException {

    kuzzle.collection("mycollection", "myindex")
            .subscribe(filter, new RoomOptions().setScope(Scope.OUT), new ResponseListener<NotificationResponse>() {
                @Override
                public void onSuccess(NotificationResponse response) {
                    // triggered each time the user leaves the circular area around Big Ben
                    System.out.println("User has left Big Ben!");
                    doSomething(response);
                }

                @Override
                public void onError(JSONObject error) {
                    handleError(error);
                }
            });
}

Since we are also going to publish the user's location from the same App, we will want to know when the subscription is successful so that we can then publish the user's location. We can do this by using the .onDone() method on our subscription request:

Copied to clipboard!
kuzzle.collection("mycollection", "myindex")
      .subscribe(/* ... */).onDone(new ResponseListener<Room>() {
            @Override
            public void onSuccess(Room response) {
                try {
                    publish();
                }
                catch(Exception e){
                    handleError(e);
                }
            }

            @Override
            public void onError(JSONObject error) {
                handleError(error);
            }
      });

We have now programmed the subscription side of the test.

Place the User Inside the Geographical Boundary

Now let's move on to the publish side of the test. Here we will create a document that represents the user's location, placed inside the circular boundary around Big Ben.

We will program a publish method that creates a document that contains three fields: firstName, lastName and location.

Let's start by creating the user Ada Lovelace located at Big Ben. Create the Document object as follows:

Copied to clipboard!
private void publish() throws JSONException {
    Collection collection = kuzzle.collection("myindex", "mycollection");
    Document document = new Document(collection);
    JSONObject bigBen = new JSONObject().put("lat", 51.510357).put("lon", -0.116773);
    JSONObject currentLocation = new JSONObject().put("firstName", "Ada").put("lastName", "Lovelace").put("location", bigBen);
    document.setContent(currentLocation, true);
}

Now we create this document in Kuzzle.

Copied to clipboard!
private void publish() throws JSONException {
    /* ... */
    collection.createDocument("326c8f08-63b0-429f-8917-b782d3093011", currentLocation, new ResponseListener<Document>() {
        @Override
        public void onSuccess(Document response) {

        }

        @Override
        public void onError(JSONObject error) {

        }
    });
}

Notice that we have included a document id, this is so that we can easily reference the document later on. We can also leave the id empty and Kuzzle will generate one automatically.

Place the User Outside the Geographical Boundary

If the document creation is successful we can go ahead and update it to change the user's location to somewhere outside the geographical boundary. Let's move the user to Hyde Park. Since this is an update we need to do it after the first location document is created.

Copied to clipboard!
private void publish() throws JSONException {
    /* ... */
    collection.createDocument("326c8f08-63b0-429f-8917-b782d3093011", currentLocation, new ResponseListener<Document>() {
        @Override
        public void onSuccess(Document response) {
            try {
                JSONObject hydePark = new JSONObject().put("lat", 51.507268).put("lon", -0.165730);
                JSONObject newLocation = new JSONObject().put("location", hydePark);
                kuzzle.collection("mycollection", "myindex")
                        .updateDocument("326c8f08-63b0-429f-8917-b782d3093011", newLocation);
            }
            catch(Exception e){
                handleError(e);
            }
        }

        @Override
        public void onError(JSONObject error) {

        }
    });
}

When the document update request is sent to Kuzzle, it will detect the change in location and send a message to the subscriber, which in this case is our App.

Run the Test

The full code should look something like this:

Copied to clipboard!

/* Test Class */

public void test(){
    try {
        kuzzle  = new Kuzzle("localhost");
        subscribe();
    } catch (Exception e) {
        handleError(e);
    }
}

/**
 * The subscription side of the pubsub
 */
private void subscribe() throws JSONException {

    /**
    * Subscribe:
    * A client subscribes to Kuzzle and is notified when the user leaves a circular area
    */

    //Create a filter that defines the circular area around Big Ben
    JSONObject bigBen = new JSONObject().put("lat", 51.510357).put("lon",  -0.116773);
    JSONObject filter = new JSONObject()
            .put("geoDistance", new JSONObject()
                    .put("location", bigBen)
                    .put("distance", "2km"));

    //Create a subscription that triggers a notification when a user the circular area
    kuzzle.collection("mycollection", "myindex")
            .subscribe(filter, new RoomOptions().setScope(Scope.OUT), new ResponseListener<NotificationResponse>() {
                @Override
                public void onSuccess(NotificationResponse response) {
                    // triggered each time the user leaves the circular area around Big Ben
                    System.out.println("User has left Big Ben!");
                    doSomething(response);
                }

                @Override
                public void onError(JSONObject error) {
                    handleError(error);
                }
            }).onDone(new ResponseListener<Room>() {
                @Override
                public void onSuccess(Room response) {
                    try {
                        publish();
                    }
                    catch(Exception e){
                        handleError(e);
                    }
                }

                @Override
                public void onError(JSONObject error) {
                    // Handle subscription error
                    handleError(error);
                }
            });
}

/**
 * The publish side of the pubsub
 */
private void publish() throws JSONException {

    /**
    * Publish:
    * A client publishes a user's location
    */

    //Create the user's location: they are inside the circular area
    Collection collection = kuzzle.collection("mycollection", "myindex");
    Document document = new Document(collection);
    JSONObject bigBen = new JSONObject().put("lat", 51.510357).put("lon", -0.116773);
    JSONObject currentLocation = new JSONObject().put("firstName", "Ada").put("lastName", "Lovelace").put("location", bigBen);
    document.setContent(currentLocation, true);
    collection.createDocument("326c8f08-63b0-429f-8917-b782d3093011", currentLocation, new ResponseListener<Document>() {
        @Override
        public void onSuccess(Document response) {
            //After the user's location is stored we can update it: now they are outside the circular area -> This will trigger the notification
            try {
                JSONObject hydePark = new JSONObject().put("lat", 51.507268).put("lon", -0.165730);
                JSONObject newLocation = new JSONObject().put("location", hydePark);
                kuzzle.collection("mycollection", "myindex")
                        .updateDocument("326c8f08-63b0-429f-8917-b782d3093011", newLocation);
            }
            catch(Exception e){
                handleError(e);
            }
        }

        @Override
        public void onError(JSONObject error) {
            handleError(error);
        }
    });
}