Blog

Using the Geotrigger Handler inside your app

With the release of our new geotrigger feature we also implemented a custom geotrigger handler for these. This allows you to handle a trigger event in your own way, for instance, by calling your own code inside your app. Thus, you can now use our plugin just for triggering, letting you know your app users have entered or exited your geofences. All without showing a notification.

In this blog post we will explain how to implement a custom geotrigger handler for your platform(s). The idea in all of these implementations is that your handler is called upon receiving a geotrigger, which you can then use in whatever way you please. If you then mark these geotriggers as handled they will use available cooldowns (such as resendability or app cooldown).

geofences

iOS

For iOS you will have to implement the following method in your AppDelegate:
-(void)plotHandleGeotriggers:(PlotHandleGeotriggers*)geotriggerHandler.

This method will be called every time Plot detects that the user is at a location you have defined a geotrigger for in our dashboard. Thus, you can use this handler to detect geotriggers.

The object PlotHandleGeotriggers has the property geotriggers, which contains all geotriggers that are at the current location of the device. You can access their data just like you would inside the Notification Filter by reading the values of the userInfo. The keys for this dictionary are defined in plot.h. For instance, to retrieve the Data field you can set in the dashboard, you can use the PlotGeotriggerDataKey key.

When you are done handling these geotriggers, you can tell Plot you want these geotriggers set as handled by calling markGeoTriggersHandled:(NSArray*)geotriggers on PlotHandleGeotriggers.

An example implementation of the geotrigger handler:

//Example for plotHandleGeotriggers:
-(void)plotHandleGeotriggers:(PlotHandleGeotriggers*)geotriggerHandler {
    NSMutableArray* toPass = [[NSMutableArray alloc] init];
    for (PlotGeotrigger* geotrigger in geotriggerHandler.geotriggers) {
        if ([@"pass" isEqualToString:[geotrigger.userInfo objectForKey:PlotGeotriggerDataKey]]) {
            [toPass addObject:geotrigger];
        }
    }
    [geotriggerHandler markGeoTriggersHandled:toPass];
}

Doing network I/O from the plotHandleGeotriggers method may cause problems, because iOS won’t guarantee a continuous time window to execute your code, which may cause your connection to timeout. Therefore it is recommended to store the data you want to use locally.

When you have enabled the data protection feature of iOS, you have to ensure that the files you read in the handler are readable when the phone is locked. This can for example be done by setting the protection level of these files to None or CompleteUntilFirstUserAuthentication.

Android

To get a Geotrigger Handler in Android you have to create a service which extends from the abstract class com.plotprojects.retail.android.GeoTriggerHandlerReceiver. That class defines one abstract method you have to implement yourself.

public class MyGeoTriggerHandlerReceiver extends GeoTriggerHandlerReceiver {
    @Override
    public List handleGeoTriggers(List geoTriggers) {
        // Your implementation...
    }
}

And you have to add it to your AndroidManifest.xml in the application element:

This method is called every time Plot detects that the user is at a location you have defined a geotrigger for in our dashboard. You get a List with all the geotriggers that have a geofence you are currently in.

In Android you can read the Data field that you can specify in the dashboard. This allows you to add custom information to a geotrigger that you can access in the Geotrigger Handler. Plot doesn’t prescribe a format for this data. You could use plain text as in this example, or for example use JSON. The data is available using the getData() method on GeoTrigger.

An example implementation of the geotrigger handler:

//Example implementation for handleGeoTriggers:
@Override
public List handleGeoTriggers(List geoTriggers) {
    List passedGeotriggers = new ArrayList();
    for (GeoTrigger geotrigger : geoTriggers) {
          String data = geotrigger.getData();
          if (data.equals("pass")) {
            passedGeotriggers.add(geotrigger);
          }
    }
    return passedGeotriggers;
}

Appcelerator

We also support the Geotrigger Handler in Appcelerator. To enable it, you will have to set the geotriggerHandlerEnabled parameter in the configuration to true.

var plot = require('com.plotprojects.ti');
plot.initPlot({ geotriggerHandlerEnabled: true });

You can define the Geotrigger Handler in assets/plotgeotriggerhandler.js. When the Plot library detects that a geotrigger is triggered, it executes the script. The script runs in a different context than the other scripts which are executed. Therefore you cannot reference views or global variables from the geotrigger handler. This is done to allow the script to run independently from the rest of the app, making the background execution much more efficient.

Always call plot.popGeotriggers() and plot.markGeoTriggersHandled(geotriggers). Inside the handler you can call custom code or use the data from geotriggers.

An example for assets/plotgeotriggerhandler.js:

var plot = require('com.plotprojects.ti');

Ti.API.info('Plot version: ' + plot.version);

var geotriggersHandler = plot.popGeotriggers();
var geotriggersPassed = [];

for (var i = 0; i < geotriggersHandler.geotriggers.length; i++) {
	var geotrigger = geotriggersHandler.geotriggers[i];
	if (geotrigger.data == "pass") {
		geotriggersPassed.push(geotrigger);
	}

	Ti.API.info(JSON.stringify(geotrigger));
}

//always call plot.markGeoTriggersHandled function, even if geotriggersHandler.geotriggers becomes empty
plot.markGeoTriggersHandled(geotriggersPassed);

As in Android and iOS you can retrieve properties of geotriggers in the handler. For instance, the data field can be obtained by accessing (in the above example) geotriggersHandler.geotriggers[i].data.

Further information

If you want to start creating geofences and geotriggers, get started at our dashboard. For more information check out our documentation.

If you have any questions, please let us know.

Spread the love