1. Introduction

Thank you for your interest in the Plot plugin. This document gives an overview of the functionality provided, a convenient manual for easy integration within your app and a detailed list of all provided API calls. We hope you will enjoy the benefits provided by our product.

If you are still in need of assistance after reading this documentation please turn to Stack Overflow and post your question mentioning 'Plot Projects', we monitor new incoming questions and try to answer them as soon as possible.

This document contains a high level description of how the plugin works for iOS and Android. Furthermore this document describes how the plugin can be integrated into your project. It also describes how you can manage your location based notifications through our Dashboard API. We also provide a graphical interface to manage your notifications.

Back To Top

1.1 Overview

The Plot systems works with geofences and notifications. Geofences represent physical locations. They have, amongst other properties, a name, coordinate and a radius. Geofences can have zero or more notifications. Notifications can have time spans associated with them. If this is the case the notification is only presented when the current time falls within one of the time spans provided. If a time span consists of only a start time it will be active from this date. If only an end time is provided it will be active before this time. Notifications have a message that is presented to the user when they are within the Geofence. By default the radius is 200m or 220 yards. Notifications can optionally be intercepted by the app to either alter or filter them with the Notification Filter. This can be used for segmentation or personalization purposes. If the user opens the notification, meta data associated with it is passed to your app so that it can react appropriately. Each notification will be presented to the user only once.

Notifications entered into the Plot system will take some time to propagate to devices. The Plot client library will utilize its resources as efficiently as possible. This means that it will increase or decrease it’s location update frequency according to a user’s behaviour and other circumstances. Plot will remain active as long as possible while maintaining a very low energy consumption footprint. Expected location accuracy in urban areas will be approximately 60m (65 yards) without making use of GPS.

The plugin is optimized for use on foot. However it is also very likely to work when cycling or slowly driving in a car. When the device is plugged in for charging it will be more likely to work in scenarios like driving on the highway and such because power consumption is then no longer an issue.

Back To Top

1.2 Feature overview

As described in this chapter, Plot offers a vast amount of features. Below is a table in which you can see what features are supported per platform or framework.

Features Android iOS Appcelerator (Titanium) PhoneGap / Cordova / Ionic Xamarin
Basic features[1]
Beacons
Geotriggers [2]
Notification handler
Notification filter [3]
Geotrigger handler
Segmentation
Retrieve cached notifications
Retrieve sent notifications
QuickSync [4] [4]
Notification events
Advertising identifier
[1] Basic features are geofencing, enter, exit and dwelling notifications, campaigns, resendability, timespans, opening hours and landing pages.
[2] Geotriggers with dwelling minutes are not supported on iOS.
[3] iOS only, Android can be done natively.
[4] For both iOS and Android additional integration steps are needed.

Back To Top

1.3 Implementation considerations

The following optional features can be considered when implementing the Plot plugin. An overview of the support for these and other features can be seen here.

Cooldown period

To prevent sending too many notifications to a user, the Plot plugin provides a cooldown period. When the cooldown period is set on the plugin, Plot will make sure that at least this amount of time has elapsed between two notifications. This is useful when your application has a lot of location based notifications, but you want to prevent overwhelming your users with notifications. The default is to use no cooldown period.

Find more information about implementing the cooldown period please see the sections iOS reference and Android reference.

You can also set a cooldown period on a single notification, instead of for the entire plugin. This allows notifications to be received multiple times by a user, but not before the cooldown for that specific notification has passed.

Notification filter

Use a notification filter if you want to prevent notifications from being shown or modify notifications before they are shown. A notification filter is a method that is called before the notifications are shown to the user. This can be used to only show notifications that match with the interests of the user or to personalize the notification. On Android it is possible to send rich notifications, for example notifications with a large image. The notification filter feature isn't available on the Phonegap plugin and Appcelerator Titanium module.

If a notification is set to landing page, it will bypass the notification filter and just open the attached URI in full view as HTML page.

Find more information about implementing the notification filter please see the sections iOS Notification filtering, Android Notification filtering, Appcelerator Notification filtering and Phonegap Notification filtering.

Notification handler

A notification handler makes it possible to specify what should happen when the user taps on a notification sent by Plot. This for example allows directly opening a view in your app that shows more information about the subject that was shown in the notification.

When no notification handler is specified, it will treat the data attached to the notification as URI and that URI will be opened. If a notification is set to landing page, it will bypass the notification handler and just open the attached URI in full view as HTML page.

Find more information about custom notification handling please see the sections iOS Notification handling, Android Notification handling, Appcelerator Notification handling and Phonegap Notification handling.

Geotrigger handler

A geotrigger handler makes it possible to define your own custom trigger when the device enters a geofence or gets in range of a iBeacon. You can filter geotriggers depending on your own logic, as you would in the notification filter. You can also use the geotrigger handler as a trigger for your own custom events in your app, for example to smoketest your notification filter.

When no geotrigger handler is specified, all geotriggers will be seen as handled by your app.

Find more information about custom geotrigger handling and implementation in the sections iOS Geotrigger handling, Android Geotrigger handling and Appcelerator Geotrigger handling. We have also blogged about it here.

Retrieve cached notification and geotriggers

It is possible to retrieve the list of notifications and geotriggers the Plot library is currently listening to. You can use this to show the user what is near him. This can also be used to see what Plot has loaded for debugging purposes.

For more information about this feature and its implementation, see section iOS Retrieve cached notifications, Android Retrieve cached notifications, Appcelerator Retrieve cached notifications and Phonegap Retrieve cached notifications.

Retrieve sent notifications and geotriggers

The plugin keeps a list of all the notifications and geotriggers that have been sent. You can retrieve these separately from the plugin to use in your app, for example to show a list of all the interesting the locations the user has passed since the last time he opened the app.

For more information about this feature and its implementation, see section iOS List sent notifications and geotriggers, Android List sent notifications and geotriggers, Appcelerator List sent notifications and geotriggers and PhoneGap List sent notifications and geotriggers.

QuickSync

Our QuickSync feature is an improved way to synchronise your app users' devices with our server. Our default synchronisation lets a device poll for new notifications or geofence every once in a while. This means that after create a notification it can take some time until you receive the notification when testing.

With Quicksync, this issue is resolved because after creating a notification it will get sent to all your users' devices immediately. In order to enable this feature some additional steps are needed, we have written an integration guide for iOS and one for Android.

More information about QuickSync can be found in our seperate blog post about this feature.

Notification events

You can use the notification events to connect the plugin with your own analytics. Our plugin provides notification events for every notification shown to the user, and for every time a notification is tapped.

For more information about this feature and its implementation, see section iOS notification events and Android notification events.

Advertising identifier for custom reporting

The Plot Plugin makes it possible to offer better targeted advertisements and improved segmentation by using the user’s advertising identifier. This identifier can be used in custom reports, which we offer for Gold plans and up.

The advertising identifier can be set in the Plot Plugin from version 1.10.0 and up. In Android this functionality is shipped as part of Google Play Services since version 4.0 and in iOS this is available since version 6.

It is possible for end-users, both on Android and iOS, to opt-out from the advertising identifier. In Android the user this is done in the Google Settings app. In iOS this setting is available through the device settings.

Contact us for the possibilities and how to set the custom reporting up. For technical information about this feature's implementation, see iOS library reference and Android library reference.

Back To Top

1.4 Configuration File

Plot allows configuration of your plugin through a plotconfig.json file placed in your project. The folder for this file depends on your platform (see integration guides).

The configuration file should contain a json object, which may contain the the properties as described below.

All platforms

The configuration file should contain your public token of your app, you can set it by adding the property publicToken and setting its value to it. You can find this token in the Plot Projects Dashboard. This property is required inside the configuration file.

You can also define whether or not Plot should automatically enable when an init method is called for the first time. It will remember calls to enable() or disable(). This property is not required, default is true.

An example plotconfig.json could look like this:

{
  "publicToken": "REPLACE_ME",
  "enableOnFirstRun": true
}

Android plugin configuration

The configuration file can be extended with some additional properties for Android. It is possible to change the icon of the notification. When no icon is provided it will fallback to the app icon. When your app targets Lollipop, it will only use the alpha channel of the image.

You can set the icon by adding the property notificationSmallIcon to the plotconfig.json. The value of the property should be a drawable resource of 24x24dp.

It is also possible to set the accent color of the icon with the property notificationAccentColor. The value of the property should be a color resource (e.g. red) or a color in hexadecimal format (e.g. #01579B). The accent color is only shown on Android Lollipop or newer.

Starting from API level 23 it is required to first request permission from the user before location services can be used. Plot will automatically request this permission when it is enabled for the first time. When declined it will ask again after the specified number of days.

Since plugin version 1.11.1 you can customize the behaviour by adding the property askPermissionAgainAfterDays and setting its value to the number of days you want to ask again for permission. Set it to -1 to disable follow up attempts after the user declines. The property is optional and defaults to 1.

An example plotconfig.json could look like this:

{
  "publicToken": "REPLACE_ME",
  "enableOnFirstRun": true,
  "notificationSmallIcon": "ic_mood_white_24dp",
  "notificationAccentColor": "#01579B",
  "askPermissionAgainAfterDays": 3
}

iOS plugin configuration

Since version 1.10.3 of our plugin we allow limiting the number of regions that can be monitored at once (iOS has a maximum of 20), so that another library using beacon or geofence regions can be used together with us. The other library would also have to use a similar setup by limiting their usage of the monitored regions.

You can set the maxmimum regions monitored by Plot by adding the property maxRegionsMonitored to the plotconfig.json. The value of the property should be an integer between 5 and 20.

An example plotconfig.json could look like this:

{
  "publicToken": "REPLACE_ME",
  "enableOnFirstRun": true,
  "maxRegionsMonitored": 10
}

Back To Top

1.5 Frameworks

Plot is offering support for using Plot in PhoneGap / Cordova / Ionic, Appcelerator (Titanium) and Xamarin.

The PhoneGap / Cordova / Ionic plugin is available from: https://github.com/Plotprojects/plot-phonegap-plugin We have included an integration guide and we have blogged about the development of this plugin for iOS and for Android.

The Appcelerator module is available from the Marketplace: Plot: Location Based Notifications Module and the source code is available on GitHub. We have blogged about how to use this here.

The Xamarin plugin is available at https://github.com/Plotprojects/plot-xamarin-plugin We have included documentation about the plugin in the readme file. There is also a step-by-step integration guide on our website.

All frameworks are also described in detail in this documentation. See the navigation menu to go to PhoneGap, Appcelerator or Xamarin. A full overview of the supported features can be found here.

Back To Top

1.6 Testing integration of Plot

Because Plot is optimized for energy efficiency, testing your integration of Plot sometimes yields unexpected results even though the integration has been done correctly. Normal use cases aren't strongly affected by these problems. When you update the notifications in our dashboard or using our API then these changes aren't directly in affect on devices. Plot caches the notifications in the device, so it doesn't have to make contact with our servers often. It can take a couple of hours before the devices can start sending out these notifications to your users. Also when the location of the device cannot be accurately determined, no notifications can be sent.

Plot yields the best result when moving, not when staying stationary on one place. A way to test it is working correctly and stays working correctly is to create a new notification at your office that will become active the next day, so you will receive the notification the next day when you arrive at your office.

When notifications don't have a cooldown period, each notification can only be received once. If you want to receive a notification again for testing, you can remove the app data so it becomes a new installation again and all notifications can be received again. This can be done by removing the app and installing it again.

We have a more extensive guide written on how to test Plot written in a blogpost for both Android and iOS.

Back To Top

1.7 iBeacon support

iBeacon notifications are supported for both our iOS plugin (from version 1.5.5 and up) and our Android plugin (from version 1.7.0 and up). A full overview of the supported features can be found here.

iBeacons allow you to send location based notifications to users within smaller ranges than geofences allow, for instance inside a store or other kind of buildings.

Read all documentation regarding our iBeacon support here.

Back To Top

1.8 Dwelling and exit notifications

Since version 1.6.0 we support dwelling notifications and exit notifications. This allows you to send a notification when a user has been in the geofence for a specified amount of time or when the user exits the geofence. By default the notification is sent when a user enters the geofence, but this can be changed in our Dashboard under the "Advanced settings" of a notification. For dwelling notifications an amount of time must be specified that a user must remain in the geofence before receiving the notification. This must be between 5 minutes and 12 hours.

Dwelling and exit notifications are also available for iBeacons and are supported on all platforms and frameworks. Due to restrictions in iOS, dwelling geotriggers are not available for that platform. A full overview of the supported features can be found here.

Back To Top

1.9 Segmentation

Location based notifications are already more relevant than push notifications, but to further improve the relevancy of your notifications you can segment your users. This feature is introduced in version 1.10.0 of our plugin. The segmentation feature allows you to limit specific notifications to specific groups of users. This prevents your end users from receiving notifications that aren't relevant for them.

Segementation is currently supported for Android, iOS, Appcelerator (Titanium) and Phonegap/Cordova/Ionic, a full overview of the supported features can be found here.

More information about segmentation is available in the segmentation guide.

Back To Top

1.10 Geotriggers

Since version 1.10.0 we support geotriggers. A geotrigger is used to see if users enter or exit a geofence. It works the same as a geofence notification, but does not display anything on the device of the user. You can use the geotrigger handler to call custom code inside your app, which allows you to create events depending on your app users location. Geotriggers are also available for iBeacons.

Please note that due to restrictions in iOS dwelling time is not supported for geotriggers, we do support it for Android. A full overview of the supported features can be found here.

We have blogged about how to use the geotrigger handler here.

Back To Top

2. iOS Plugin

iOS is the mobile operating system used by Apple for both iPhone and iPad. This chapter will elaborate on the way our plugin can be used when creating an app for iOS.

Back To Top

2.2 Functionality

The plugin targets iOS 6.0 and up. It is binary compatible with iOS 4.3 and 5.x, but the service will not be enabled. When the Plot plugin is initialized by the [Plot initializeWithLaunchOptions:delegate:] call, it checks if it was previously enabled. If the location monitoring service is not running and it was previously enabled by the [Plot enable] call it will (re)enable the location monitoring service. The location monitoring service is also restarted automatically after the device reboots.

The plugin makes use of the region monitoring capabilities provided by iOS and some improvements we have added ourselves. The location of the user will be determined in a way that minimizes battery usage; GPS is almost never used as the service uses Wifi-triangulation. When the user is within the radius of a geofence with a published notification it will present a Local Notification to the user (Local Notifications are faster than Push Notifications and don't require an internet connection). The default distance is 200m (220 yards). Due to hardware restrictions the minimum distance on the iPhone 4 and earlier iPhone models is 400m.

When the app is already running (in the background or in the foreground), the application:didReceiveLocalNotification method of your app is called when the user taps on a notification. When the application is not running, then the app is started and the notification is passed through application:didFinishLaunchingWithOptions:. We provide a default implementation to open a browser with the URL enclosed in the data field of the notification. If the app is running in the foreground our default implementation shows a confirmation dialog first. If you don't want to make use of the default implementation, but want to deal with notifications yourself you'll have to implement plotHandleNotification: of the delegate passed to [Plot initializeWithLaunchOptions:delegate:].

The Plot plugin is optimized for users travelling at low speeds (walking, biking). The geofences and notifications will be synchronized with our back end periodically. Therefore it may take a while before a notification you have added is available on the phone. When travelling at higher speeds or when a phone temporarily cannot determine its location, it is possible that a Location Based Notification is not sent even when a user is inside a geofence. You can however increase the radius of the geofence to increase the chances of the user receiving the notification in this use case.

When the application is compiled in Debug mode, Plot will print extra information about the loaded notifications on the console to aid in debugging.

iBeacon notifications are supported for our iOS plugin (from version 1.5.5 and up). iBeacons allow you to target users within smaller ranges, for instance inside a store or other kind of buildings. You can add iBeacons just like normal geofences in our dashboard. Instead of a latitude and longitude, iBeacons are identified by a proximity UUID, a majorId and a minorId. iBeacon notifications are also passed through the Notification Filter and the Notification Handler as normal notifications from the Plot plugin would. Read all documentation regarding our iBeacon support in Chapter 2: iBeacons.

Back To Top

2.3 Notification handling

When you don't specify a callback for handling notifications, Plot will handle the notifications in the following manner: When a notification is opened, it will treat the data field of the notification as URI and tries to open it.

If you don’t want Plot to handle the notifications, you can handle the notifications yourself. The delegate passed to initializeWithLaunchOptions:delegate: determines what is done after a notification is opened. The delegate has to implement the PlotDelegate protocol. When the method -(void)plotHandleNotification:(UILocalNotification*)notification data:(NSString*)action is implemented, the default handler is replaced by this method which will then be called when a notification is opened.

Back To Top

2.4 Notification filtering

When you want to segment your users or want to personalize the notifications, you can use the notification filter. The delegate passed to initializeWithLaunchOptions:delegate: may implement the optional method -(void)plotFilterNotifications:(PlotFilterNotifications*)filterNotifications. When the method is implemented, Plot will send the notifications to this method before showing them on the mobile device. This allows you to prevent notifications from being shown or change the notifications. Please note that due to restrictions in iOS the notification filter for dwelling notifications is called when the user enters the geofence or beacon region and that the returned notifications are only shown when the user remains in the region for the specified amount of time.

The “data” field of a notification allows you to add custom information to a notification in our dashboard that you can access in the plotFilterNotifications: method. Plot doesn’t prescribe a format for this data. You can use plain text, or for example use JSON. You can access it by reading the PlotNotificationDataKey (constant defined in plot.h) from the userInfo dictionary of the UILocalNotification.

Make sure to always call showNotifications: at the end of your filtering, even when you have no notifications left. This way our plugin knows you have finished filtering.

//Example for plotFilterNotifications:
-(void)plotFilterNotifications:(PlotFilterNotifications*)filterNotifications {
    NSArray* notifications = filterNotifications.uiNotifications;
    for (UILocalNotification* localNotification in notifications) {
        // makes the notification body string personalized
        localNotification.alertBody = [NSString stringWithFormat:@"Hello Paul! %@", localNotification.alertBody];
    }
    // Always call showNotifications at the end of the method
    [filterNotifications showNotifications:notifications];
}

You can change all fields of the UILocalNotification object, except the fields that are related to scheduling. That functionality is not supported. For a reference of all fields you can change, you can check the Apple iOS Documentation.

When you have enabled the data protection feature of iOS, you have to ensure that the files you read in the filter 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.

We have written a more extensive blog post about this: Using The Notification Filter To Increase Relevance.

Back To Top

2.5 Geotrigger handling

When you want to handle your geotriggers, or use them as trigger events for your own code, you can use the geotrigger handler. The delegate passed to initializeWithPublicKey:launchOptions:delegate: may implement the optional method -(void)plotHandleGeotriggers:(PlotHandleGeotriggers*)geotriggerHandler. When the method is implemented, Plot will send the geotriggers to this method before considering them as handled. This allows you to add custom code that is triggered by entering (or exiting) a geofence or beacon region. Please note that due to restrictions in iOS dwelling time is not supported for geotriggers in iOS.

Make sure to always call markGeotriggersHandled: at the end of your handling, even when you have no geotriggers left. This way our plugin knows you have finished.

//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];
        }
    }
    // Always call markGeotriggersHandled at the end of the method
    [geotriggerHandler markGeotriggersHandled:toPass];
}

You can read all fields from a geotrigger just as you would do that for a notification in the notification filter, most of them can be found in the userInfo. Full reference of keys for this can be found in the library reference.

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.

Back To Top

2.6 Retrieve cached notifications

It is possible to retrieve the list of notifications and geotriggers the Plot library is currently listening to. You can, for example, use this to show the user what is near him. This can also be used to see what Plot has loaded for debugging purposes.

The plugin exposes two method: [Plot loadedNotifications] and [Plot loadedGeotriggers]. Fields like notification message, latitude, longitude, data are available.

When no notifications are loaded an empty list is returned. This could for example be the case when the location of the device is unknown.

Back To Top

2.7 List sent notifications and geotriggers

The library allows you to retrieve the sent notifications and geotriggers using the method [Plot sentNotifications] for notifications and [Plot sentGeotriggers] for geotriggers. The library will retain up to 100 notifications and geotriggers, before the oldest notifications/geotriggers get deleted. When you alter the notification message or the data property, this alteration will also be applied to the notification in the history. The objects returned contain the time the notification or geotrigger was sent and when, if it has, been opened or handled.

It is possible to remove the history of sent notifications and geotriggers yourself by using the [Plot clearSentNotifications] method for notifications and the [Plot clearSentGeotriggers] method for geotriggers.

An use case where this functionality may be useful for is to show a list of the notifications that were sent since the app was last opened. This allows users to see the notifications again, even though they may have dismissed them earlier.

Back To Top

2.8 Notification events

Since plugin version 1.15.0 it is possible to listen to notification events. This feature is especially useful when you want to tie the plugin to your own analytics.

Currently we offer notification events upon showing a notification to the user (sent notification event) and whenever a user taps on a notification (opened notification event).

Whenever such an event happens our plugin will call the appropriate method. The delegate passed to initializeWithLaunchOptions:delegate: may implement the optional methods -(void)plotNotificationSentEvent:(PlotSentNotification*)notification and -(void)plotNotificationOpenedEvent:(PlotSentNotification*)notification to make use of this feature.

See an example implementation below for the notification sent event:

-(void)plotNotificationSentEvent:(PlotSentNotification*)notification {
  NSString* message = [notification.userInfo objectForKey:PlotNotificationMessage];
  NSLog(@"Notification Sent Event: message: %@", message);
  // Make a call to Google Analytics
}

And an example for when a notification is opened:

-(void)plotNotificationOpenedEvent:(PlotSentNotification*)notification {
  NSString* data = [notification.userInfo objectForKey:PlotNotificationDataKey];
  NSLog(@"Notification Opened Event: data: %@", data);
  // Make a call to Google Analytics
}

Back To Top

2.9 App Store description

From the description in the App Store it must be clear for the end user why location services are required. This is something Apple often checks during the review of your app. It is possible to change the description to ensure that it is clear for the end user why location services are required. You can find more information about this in the integration guide.

Back To Top

2.10 Migrating from previous versions

When replacing the Plot library with a new version, you have to perform a clean build. You can start such a build from XCode by choosing Clean from the Product-menu.

When upgrading your project to support iOS 8, you have to add an entry to your Info.Plist with the key NSLocationAlwaysUsageDescription. The value must describe why your app uses the location of the device. For example: “Your location is used to instantly inform you when you are near a location that is interesting to you.” This text is shown when permission to use the location of the device is requested.

When upgrading from version 1.4.x or earlier, you have to remove the background mode for location services. The background mode is no longer needed for Plot to function. Plot now makes use of new energy efficient APIs from iOS.

When using initializeWithPublicKey:launchOptions:delegate: or initializeWithPublicKey:launchOptions: or initializeWithConfiguration:launchOptions:, we suggest to change to initializeWithLaunchOptions:delegate: and use plotconfig.json for your configuration. You can find the contents for plotconfig.json at Developer Tools in our dashboard.

Don't handle notifications from Plot directly in application:didFinishLaunchingWithOptions: or application:didReceiveLocalNotification:, but provide your custom handling in plotHandleNotification: in the delegate. When notifications are handled directly instead of through Plot, the usage statistics will become inaccurate.

Back To Top

2.11 Example implementation

This is a minimal example which shows how to integrate Plot. It doesn't have a Notification Filter and uses the default notification handler.

plotconfig.json (you can get one specificly for your app in our dashboard)
{
  "publicToken": "REPLACE_ME",
  "enableOnFirstRun": true
}
AppDelegate.h
#import <UIKit/UIKit.h>
#import <Plot/Plot.h>

@interface AppDelegate : UIResponder <UIApplicationDelegate, PlotDelegate>

@property (strong, nonatomic) UIWindow *window;

@end
AppDelegate.m
#import "AppDelegate.h"
#import <Plot/Plot.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    //Initializes the Plot library:
    [Plot initializeWithLaunchOptions:launchOptions delegate:self];
    return YES;
}

-(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
    //Pass the notification to the Plot library to pre process the notification.
    //Don't handle the notifications yourself in this method, because this method isn't always called when a notification is opened.
    [Plot handleNotification:notification];
}

-(void)plotHandleNotification:(UILocalNotification*)notification data:(NSString*)action {
    //Custom handler for notifications. (optional)
    //When you don't want to do a custom action when a notification is opened, then don't implement this method.
    [[UIApplication sharedApplication] openURL:[NSURL URLWithString:action]];
}

-(void)plotFilterNotifications:(PlotFilterNotifications*)filterNotifications {
    //Filter for notifications. (optional)
    //When you want to change notifications or prevent sending notifications, then implement this method.

    [filterNotifications showNotifications:filterNotifications.uiNotifications];
}

@end

Back To Top

2.13 iBeacons

What is an iBeacon

An iBeacon is a small wireless device that broadcasts its presence over Bluetooth Low Energy. Apps can register for updates on when the user gets in range of these devices. The phone doesn’t have to pair or set up a connection to detect it’s there.

This allows you to send a notification when a user is near an iBeacon (instead of when a user enters a geofence for geofencing messages). iBeacons allow you to target users within smaller ranges, for instance inside a store or another kind of building. The smaller targeting radius further increases the relevance of the notification.

Starting from version 1.5.5 of our iOS plugin and version 1.7.0 of our Android plugin, iBeacon notifications are supported. Android support for iBeacons in our plugin isn't enabled by default. You have to add an extra library to enable iBeacon support. Instead of when a user enters a geofence you can send a notification when a user comes near an iBeacon. This allows targeting users inside a store, stadium or another kind of building with a smaller match range to increase the relevance of the notification.

When iBeacons are entered in the dashboard then the plugin also monitors the distance to beacon devices to determine whether a notification should be sent to the user. This feature is available on iPhone 4S and newer and for Android devices with Android 4.3 or higher.

Several companies started with selling iBeacons. iBeacons provide the possibility to send location based notifications when the user is inside in a building with a small range instead of a larger region outside. This allows to target your users more precisely.

Characteristics

Each iBeacon has three characteristics that allows to distinguish between multiple iBeacons. The three characteristics are:

proximityUUID:This identifier is the same for all devices you own. You specify the identifier per app in our Dashboard.
majorId:A number that identifies a group of related beacons. For example you could give all the beacons in the same store the same majorId. It is required to specify this field when you add an iBeacon.
minorId:Another number to distinguish between your iBeacons. For example you could use this to distinguish between multiple beacons in the same store. You can specify this field when you add an iBeacon to differentiate between beacons with the same majorId. When this field isn't specified then all beacons that have the specified majorId will trigger a notification.

Some vendors allow to order an iBeacon with these values specified by you, others give iBeacons with default values that you can reprogram using an app they provide. Consult the documentation of the vendor to obtain the characteristics of your iBeacons.

Start sending iBeacon notifications

Before you can receive location based beacon notifications you have to enter the proximityUUID that is shared between all your iBeacons. You can the enter the proximityUUID in our dashboard, go to Manage iBeacons and click on Configure iBeacon details. You only have to enter these details once.

After that, iBeacons can be added just like geofences, except that you specify a majorId and optionally a minorId. You can choose between three distances: immediate (less than 1 meter/3 feet), near (around 2 meters/6 feet) or far (around 30 meter/100 feet). Choosing for near or far yields the best result, since immediate is a very short range for the use case of sending notifications.

Using iBeacons on Android

In order to use iBeacons on Android you have to perform some additional steps. We have written an integration guide about this here.

Testing with iBeacons

You can order iBeacons from various companies or you can turn an iPhone (4S and up) or an iPad into an iBeacon. How to turn your device into an iBeacon you can read here: How to test with an iPhone/iPad. You cannot test the receiving of notifications on an iPhone/iPad that is used as a beacon. So if you want to test with an iPhone/iPad as iBeacon, you need at least two devices.

Note that you can only receive notifications a single time and it may take some time before a notification entered in our dashboard is sent to the device.

A quick way to trigger notifications on your iPhone is to go to your lock screen. iOS will then perform an extra check to determine whether an iBeacon is in range.

Back To Top

2.14 Segmentation

The segmentation feature is introduced in version 1.10.0 of our plugin and further improved by segmentation on campaign history in version 1.12.0. Segmentation allows you to limit specific notifications to specific groups of users. This prevents your end users from receiving notifications that aren't relevant for them.

Two steps are needed when using segmentation, first the segment property and the appropriate value have to be set in the campaign (or notification) in the dashboard. Next to that they have to be set inside your app. When these match the device will receive the notification.

For each type we expose methods to conveniently set a segment. An example for each type is shown below. When setting a value for an existing property the previous value gets overwritten. Set value to nil to clear the property.

// Set the segment for being a premium member to true.
[Plot setBooleanSegmentationProperty:YES forKey:@"premiumMember"];

// Set the segment for gender to male.
[Plot setStringSegmentationProperty:@"M" forKey:@"gender"];

// Set the segment for year of birth to 1980.
[Plot setIntegerSegmentationProperty:1980 forKey:@"yearOfBirth"];

// Set the segment for money spent to $10.35.
[Plot setDoubleSegmentationProperty:10.35 forKey:@"moneySpent"];

// Set the signup date segment to now.
[Plot setDateSegmentationProperty:[NSDate now] forKey:@"signUp"];

More general information about segmentation is available in the segmentation guide.

Back To Top

3. Android Plugin

Android is the mobile operating system developed by Google. This chapter will elaborate on the way our plugin can be used when creating an app for Android.

Back To Top

3.2 Functionality

The plugin targets Android 2.3 (Froyo, API level 9) and up. When the Plot plugin is initialized by the Plot.init() call, it checks if it was previously enabled. If the location monitoring service is not running and it was previously enabled it will (re)enable the location monitoring service. The location monitoring service will then also be restarted automatically after the device reboots.

The plugin will start a background service which will periodically poll the location of the user. The location of the user will be determined in a way that minimizes battery usage; instead of GPS the service uses Wifi-triangulation. When the user is within the radius of a geofence (default: 200 meters or 220 yards) with a published notification it will present a notification to the user. This notification can optionally be modified or filtered.

We provide a default implementation to open a browser with the URL enclosed in the notification. It is possible to replace this implementation with your own. An example of such an implementation is given later. The location polling frequency is determined automatically and is at least once every 10 minutes, but can be more frequent depending on a number of factors. The Plot plugin is optimized for users travelling at low speeds (walking, cycling). The geofences and notifications will be synchronized with our backend every couple hours. When travelling at higher speeds or when a phone can temporarily not determine its location, it is possible that a Location Based Notification is not sent even when a user is near a geofence.

iBeacon notifications are supported for our Android plugin (from version 1.7.0 and up) as well, unless you're using Appcelerator.

iBeacons allow you to target users within smaller ranges, for instance inside a store or other kind of buildings. You can add iBeacons just like normal geofences in our dashboard. Instead of a latitude and longitude, iBeacons are identified by a proximity UUID, a majorId and a minorId. iBeacon notifications are also passed through the Notification Filter and the Notification Handler as normal notifications from the Plot plugin would. Please note that iBeacons require an Android verion of at least 4.3 and Bluetooth low-energy. Read all documentation regarding our iBeacon support in Chapter 2: iBeacons.

It is possible to enable debug logging on Plot. Use this to receive more feedback when developing with Plot.

Back To Top

3.3 Notification handling

When you want the default behaviour when opening a notification, which is opening a URI, you have to follow the description in step three of the previous section. If you want a different action, then you have write your own BroadcastReceiver.

An example of a custom receiver which starts the NotificationOpenActivity (see our example project):

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import com.plotprojects.retail.android.FilterableNotification;

public class MyNotificationOpenReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        FilterableNotification notification = intent.getParcelableExtra("notification");
        if (notification.getData() == null)
            return;

        Intent openIntent = new Intent(context, NotificationOpenActivity.class);
        openIntent.setAction(NotificationOpenActivity.ACTION);
        openIntent.putExtras(intent.getExtras());
        openIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_REORDER_TO_FRONT);

        context.startActivity(openIntent);
    }
}

And to add this receiver to the manifest instead of the default one:

<receiver android:exported="false" android:name="[[Application Package]].MyNotificationOpenReceiver">
  <intent-filter>
    <action android:name="[[Application Package]].plot.OpenNotification" />
  </intent-filter>
</receiver>

Be sure to replace [[Application Package]] with the package name of your application (e.g. com.example.app).

Back To Top

3.4 Notification filtering

When you want to segment your users or want to personalize the notifications, you can use the notification filter. Plot automatically detects whether a service is registered in AndroidManifest.xml that extends from the class NotificationFilterReceiver. Implementations of NotificationFilterReceiver must implement the method public List<FilterableNotification> filterNotifications(List<FilterableNotification> notifications). When the service is defined Plot will send the notifications to this method before showing them on the mobile device. This allows you to prevent notifications from being shown or change the notifications.

The “data” field of a notification allows you to add custom information to a notification in our dashboard that you can access in the filterNotifications() method. Plot doesn’t prescribe a format for this data. You can use plain text, or for example use JSON.

//Example implementation for filterNotifications:
public class MyNotificationFilterReceiver extends NotificationFilterReceiver {
    @Override
    public List<FilterableNotification> filterNotifications(List<FilterableNotification> notifications) {
        String format = "Hello Paul: %s";
        for (FilterableNotification notification : notifications) {
            String newMessage = String.format(format, notification.getMessage());
            notification.setMessage(newMessage);
        }
        return notifications;
    }
}

It is possible to change the message with the setMessage() method or it is even possible to provide a custom Notification with the setNotification() method on FilterableNotification. By providing a custom notification object it is possible to send rich notifications, for example notifications with an image, to your users. When no custom Notification is specified, Plot will generate a Notification based on the message field and show that one.

We have written a more extensive blog post about this: Using The Notification Filter To Increase Relevance. A larger example is given in another blog post: Using Plot To Create Context-Aware Coupons, Offers And Promotions.

Back To Top

3.5 Geotrigger handler

When you want to handle your geotriggers, or use them as trigger events for your own code, you can use the geotrigger handler. Plot automatically detects whether a service is registered in AndroidManifest.xml that extends from the class GeotriggerHandlerReceiver. Implementations of GeotriggerHandlerReceiver must implement the method public List<Geotrigger> handleGeotriggers(List<Geotrigger> geotriggers). When the service is defined Plot will send the geotriggers to this method before considering them as handled. This allows you to add custom code that is triggered by entering (or exiting) a geofence or beacon region.

//Example implementation for handleGeotriggers:
public class MyGeotriggerHandlerReceiver extends GeotriggerHandlerReceiver {
    @Override
    public List<Geotrigger> handleGeotriggers(List<Geotrigger> geotriggers) {
        List<Geotrigger> passedGeotriggers = new ArrayList<Geotrigger>();
        for (Geotrigger geotrigger : geotriggers) {
            String data = geotrigger.getData();
            if (data.equals("pass")) {
                passedGeotriggers.add(geotrigger);
            }
        }
        return passedGeotriggers;
    }
}

You can read all fields from a geotrigger just as you would do that for a notification in the notification filter. Full reference for this can be found in the library reference.

Back To Top

3.6 Retrieve cached notifications

It is possible to retrieve the list of notifications and geotriggers the Plot library is currently listening to. You can, for example, use this to show the user what is near him. This can also be used to see what Plot has loaded for debugging purposes.

The plugin exposes two method: Plot.getLoadedNotifications() and Plot.getLoadedGeotriggers(). Fields like notification message, latitude, longitude, data are available.

When no notifications are loaded an empty list is returned. This could for example be the case when the location of the device is unknown.

Back To Top

3.7 List sent notifications and geotriggers

The library allows you to retrieve the sent notifications and geotriggers using the method Plot.getSentNotifications() for notifications and Plot.getSentGeotriggers() for geotriggers. The library will retain up to 100 notifications and geotriggers, before the oldest notifications/geotriggers get deleted. When you alter the notification message or the data property, this alteration will also be applied to the notification in the history. The objects returned contain the time the notification or geotrigger was sent and when, if it has, been opened or handled.

Because this method uses blocking I/O, this method cannot be run on the main thread. Instead it should be run on a worker thread or in an AsyncTask.

It is possible to remove the history of sent notifications and geotriggers yourself by using the Plot.clearSentNotifications() method for notifications and the Plot.clearSentGeotriggers() method for geotriggers.

An use case where this functionality may be useful for is to show a list of the notifications that were sent since the app was last opened. This allows users to see the notifications again, even though they may have dismissed them earlier.

Back To Top

3.8 Notification events

Since plugin version 1.15.0 it is possible to listen to notification events. This feature is especially useful when you want to tie the plugin to your own analytics.

Currently we offer notification events upon showing a notification to the user (sent notification event) and whenever a user taps on a notification (opened notification event).

Whenever such an event happens our plugin will send out an intent to which you can listen with a broadcast receiver. When implementing make sure to include it in the manifest, for example like this:

  <receiver android:exported="false" android:name="[[Application Package]].MyNotificationEventReceiver">
      <intent-filter>
          <action android:name="[[Application Package]].plot.SentNotification" />
          <action android:name="[[Application Package]].plot.OpenedNotification" />
      </intent-filter>
  </receiver>

Be sure to replace [[Application Package]] with the package name of your application (e.g. com.example.app).

See an example implementation below for the notification sent and opened event:

public class MyNotificationEventReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        SentNotification notification = intent.getParcelableExtra("notification");
        if ((packageName + ".plot.SentNotification").equals(intent.getAction())) {
          String format = "Message of the sent notification: %s";
          Log.i(TAG, String.format(format, notification.getMessage()));
        } else if ((packageName + ".plot.OpenedNotification").equals(intent.getAction())) {
          String format = "Message of the opened notification: %s";
          Log.i(TAG, String.format(format, notification.getMessage()));
          // Make a call to your Google Analytics
        }
    }
}

Back To Top

3.9 Migrating from previous versions

File based configuration

Since plot version 1.10.0 the Android plugin is initialized and configured through a configuration file located at assets/plotconfig.json. You should create this file yourself with your configuration and your public token. You can find the contents for plotconfig.json at Developer Tools in our dashboard. An example of such a file can be seen at the Example implementation.

Debug logging

Debug logging can be enabled in the configuration file.

AndroidManifest.xml

It is no longer required to specify any of the classes Plot provides in your manifest file. Plot will add its required permissions and broadcast handlers by itself. Your own classes that extend the functionality of the Plot plugin, such as a notification filter, still have to be registered in the AndroidManifest.xml file.

Back To Top

3.10 Example implementation

This is a minimal example which shows how to integrate Plot. It doesn't have a Notification Filter and uses the default notification handler.

Example content for your assets/plotconfig.json file: (you can get one specificly for your app in our dashboard)

{
  "publicToken": "REPLACE_ME",
  "enableOnFirstRun": true,
  "debug": true
}

Example code for in your activity:

public class PlotExample extends Activity
{
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        Plot.init(this);
    }
}

Back To Top

3.12 iBeacons

Starting from version 2.0 of our library, it is no longer required to follow extra steps to have beacon support. Beacon support is enabled by default.

Please note that in order to receive iBeacon notifications, Android devices have to run on Android 4.3 or higher and have Bluetooth low-energy support. For further information about iBeacons in general, see Chapter 2: iBeacons.

Back To Top

3.13 Segmentation

The segmentation feature is introduced in version 1.10.0 of our plugin and further improved by segmentation on campaign history in version 1.12.0. Segmentation allows you to limit specific notifications to specific groups of users. This prevents your end users from receiving notifications that aren't relevant for them.

Two steps are needed when using segmentation, first the segment property and the appropriate value have to be set in the campaign (or notification) in the dashboard. Next to that they have to be set inside your app. When these match the device will receive the notification.

For each type we expose methods to conveniently set a segment. An example for each type is shown below. When setting a value for an existing property the previous value gets overwritten.

// Set the segment for being a premium member to true.
Plot.setBooleanSegmentationProperty("premiumMember", true);

// Set the segment for gender to male.
Plot.setStringSegmentationProperty("gender", "M");

// Set the segment for year of birth to 1980.
Plot.setLongSegmentationProperty("yearOfBirth", 1980);

// Set the segment for money spent to $10.35.
Plot.setDoubleSegmentationProperty("moneySpent", 10.35);

// Set the signup date segment (the value is in seconds since the UNIX Epoch, just as System.currentTimeMillis()/1000).
Plot.setDateSegmentationProperty("signUp", 1426503567);

More general information about segmentation is available in the segmentation guide.

Back To Top

4. Appcelerator Plugin

The Appcelerator module is available from the Marketplace: Plot: Location Based Notifications Module and the source code is available on GitHub. In addition, our module can be downloaded and installed in your project using gitTio: $ gittio install com.plotprojects.ti (also available here).

We have blogged about how to integrate Plot into your Appcelerator project here and have an integration guide here.

Back To Top

4.1 Notification handling

When you don't specify a callback for handling notifications, Plot will handle the notifications depending on the action setting in the dashboard. You can for instance set the field to a URI and whenver the notification is opened the URI will be loaded with the phone's browser.

If you don’t want Plot to handle the notifications, you can handle the notifications yourself. To change the action when a notification has been received you can add a listener as shown in the snippet below. The function is passed a notification object, which has the fields "message", "data" and "identifier". When no listener is added, then the "data" field will be treated as set in the dashboard.

plot.addEventListener("plotNotificationReceived", func)

Back To Top

4.2 Notification filtering

When you want to segment your users or want to personalize the notifications, you can use the notification filter. The notification filter allows you to filter out or edit notifications before they are shown. To enable the notification filter, you add the property notificationFilterEnabled with the value true to object passed to initPlot. When the notification filter is disabled the notification filter script won't be executed and all notifications will shown.

You define the filter in assets/plotfilter.js. When Plot detects that a notification could be shown, it executes the script. The script runs in a different context than the normal scripts are executed. Therefore you cannot reference views or global variables from the notification filter.

The message and the data property of the notification can be modified. You can remove notifications from the array you don't want to show. Always call plot.popFilterableNotifications() and plot.sendNotifications(filterableNotifications), even when no notifications will be shown.

An example for assets/plotfilter.js:

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

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

var filterableNotifications = plot.popFilterableNotifications();

for (var i = 0; i < filterableNotifications.notifications.length; i++) {
var n = filterableNotifications.notifications[i];
n.message = "TestMessage: " + n.message;
n.data = "Test123: " + n.data;
}

//always call plot.sendNotifications function, even if filterableNotifications.notifications becomes empty
plot.sendNotifications(filterableNotifications);

Back To Top

4.3 Geotrigger handling

When you want to handle your geotriggers, or use them as trigger events for your own code, you can use the geotrigger handler. To enable the geotrigger handler, you add the property geotriggerHandlerEnabled with the value true to object passed to initPlot. When the geotrigger handler is disabled all geotriggers will be counted as handled.

You define the handler in assets/plotgeotriggerhandler.js. When Plot detects that a geotrigger has triggered, it executes the script. The script runs in a different context than the normal scripts are executed. Therefore you cannot reference views or global variables from the geotrigger handler.

You can remove geotriggers from the array you don't want to mark as handled. Always call plot.popGeotriggers() and plot.markGeotriggersHandled(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));
}

geotriggersHandler.geotriggers = geotriggersPassed;

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

Back To Top

4.4 Retrieve cached notifications

It is possible to retrieve the list of notifications and geotriggers the Plot library is currently listening to. You can, for example, use this to show the user what is near him. This can also be used to see what Plot has loaded for debugging purposes.

The plugin exposes two method: getLoadedNotifications() and getLoadedGeotriggers(). Fields like notification message, latitude, longitude, data are available.

When no notifications are loaded an empty list is returned. This could for example be the case when the location of the device is unknown.

Please note that this is an optional feature and not needed in order for the Plot library to work.

An example implementation would be:

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

var cachedNotifications = plot.getLoadedNotifications();
var cachedGeotriggers = plot.getLoadedGeotriggers();

Back To Top

4.5 List sent notifications and geotriggers

The library allows you to retrieve the sent notifications and geotriggers using the method plot.getSentNotifications() for notifications and plot.getSentGeotriggers() for geotriggers. The library will retain up to 100 notifications and geotriggers, before the oldest notifications/geotriggers get deleted. When you alter the notification message or the data property, this alteration will also be applied to the notification in the history. The objects returned contain the time the notification or geotrigger was sent and when, if it has, been opened or handled.

It is possible to remove the history of sent notifications and geotriggers yourself by using the plot.clearSentNotifications() method for notifications and the plot.clearSentGeotriggers() method for geotriggers.

An use case where this functionality may be useful for is to show a list of the notifications that were sent since the app was last opened. This allows users to see the notifications again, even though they may have dismissed them earlier.

Back To Top

4.6 iBeacons

Our Appcelerator Plugin supports iBeacons only for iOS.

Back To Top

4.7 Segmentation

The segmentation feature is introduced in version 1.10.0 of our plugin and further improved by segmentation on campaign history in version 1.12.0. Segmentation allows you to limit specific notifications to specific groups of users. This prevents your end users from receiving notifications that aren't relevant for them.

Two steps are needed when using segmentation, first the segment property and the appropriate value have to be set in the campaign (or notification) in the dashboard. Next to that they have to be set inside your app. When these match the device will receive the notification.

For each type we expose methods to conveniently set a segment. An example for each type is shown below. When setting a value for an existing property the previous value gets overwritten.

// Set the segment for being a premium member to true.
plot.setBooleanSegmentationProperty("premiumMember", true);

// Set the segment for gender to male.
plot.setStringSegmentationProperty("gender", "M");

// Set the segment for year of birth to 1980.
plot.setIntegerSegmentationProperty("yearOfBirth", 1980);

// Set the segment for money spent to $10.35.
plot.setDoubleSegmentationProperty("moneySpent", 10.35);

// Set the sign-up date segment to now.
plot.setDateSegmentationProperty("signUp", new Date());

More general information about segmentation is available in the segmentation guide.

Back To Top

5.1 Notification handling

When you don't specify a callback for handling notifications, Plot will handle the notifications depending on the action setting in the dashboard. You can for instance set the field to a URI and whenever the notification is opened the URI will be loaded with the phone's browser.

If you don’t want Plot to handle the notifications, you can handle the notifications yourself. To change the action when a notification has been received you can use the notificationHandler. This feature is available both on IOS and Android.

An example of such an implementation:

//Optional, by default the data is treated as set in the dashboard.
plot.notificationHandler = function(notification, data) {
alert(data);
}

Back To Top

5.2 Notification filtering

When you want to segment your users or want to personalize the notifications, you can use the notification filter. The notification filter allows you to filter out or edit notifications before they are shown.

To do this, you can intercept notifications before they are shown by using the filterCallback. Keep in mind this feature is only available on IOS.

An example of such an implementation:

//Optional, by default all notifications are sent.
plot.filterCallback = function(notifications) {
  for (var i = 0; i < notifications.length; i++) {
    notifications[i].message = "NewMessage";
    notifications[i].data = "http://www.example.com";
  }
    return notifications;
};

Back To Top

5.3 Retrieving cached notifications

It is possible to retrieve the list of notifications and geotriggers the Plot library is currently listening to. You can, for example, use this to show the user what is near him. This can also be used to see what Plot has loaded for debugging purposes.

The plugin exposes two method: loadedNotifications(callback) and loadedGeotriggers(callback). Fields like notification message, latitude, longitude, data are available.

When no notifications are loaded an empty list is returned. This could for example be the case when the location of the device is unknown.

Please note that this is an optional feature and not needed in order for the Plot library to work.

An example implementation would be:

plot.loadedNotifications(function(notifications) {
  // Do something with the notifications
});
plot.loadedGeotriggers(function(geotriggers) {
  // Do something with the geotriggers
});

Back To Top

5.4 List sent notifications and geotriggers

The library allows you to retrieve the sent notifications and geotriggers using the method plot.sentNotifications(resultCallback, errorCallback) for notifications and plot.sentGeotriggers(resultCallback, errorCallback) for geotriggers. The library will retain up to 100 notifications and geotriggers, before the oldest notifications/geotriggers get deleted. When you alter the notification message or the data property, this alteration will also be applied to the notification in the history. The objects returned contain the time the notification or geotrigger was sent and when, if it has, been opened or handled.

It is possible to remove those notifications yourself as well using the plot.clearSentNotifications() method for notifications and the plot.clearSentGeotriggers() method for geotriggers.

An use case where this functionality may be useful for is to show a list of the notifications that were sent since the app was last opened. This allows users to see the notifications again, even though they may have dismissed them earlier.

Back To Top

5.5 iBeacons

Our Phonegap Plugin supports iBeacons for both Android and iOS, however, you need to perform some additional steps for Android. To keep our normal Android library small and to prevent always having to add Bluetooth permissions we ship Android iBeacon support in a separate plugin.

You can find this module at: https://github.com/Plotprojects/plot-phonegap-plugin-androidibeacons The module adds functionality to the existing module, so you still have to add the core Plot Plugin in your project.

Please note that in order to receive iBeacon notifications, Android devices have to run on Android 4.3 or higher and have Bluetooth low-energy support. For further information about iBeacons in general, see Chapter 2: iBeacons.

Back To Top

5.6 Segmentation

The segmentation feature is introduced in version 1.10.0 of our plugin and further improved by segmentation on campaign history in version 1.12.0. Segmentation allows you to limit specific notifications to specific groups of users. This prevents your end users from receiving notifications that aren't relevant for them.

Two steps are needed when using segmentation, first the segment property and the appropriate value have to be set in the campaign (or notification) in the dashboard. Next to that they have to be set inside your app. When these match the device will receive the notification.

For each type we expose methods to conveniently set a segment. An example for each type is shown below. When setting a value for an existing property the previous value gets overwritten.

// Set the segment for being a premium member to true.
plot.setBooleanSegmentationProperty("premiumMember", true);

// Set the segment for gender to male.
plot.setStringSegmentationProperty("gender", "M");

// Set the segment for year of birth to 1980.
plot.setIntegerSegmentationProperty("yearOfBirth", 1980);

// Set the segment for money spent to $10.35.
plot.setDoubleSegmentationProperty("moneySpent", 10.35);

// Set the sign-up date segment to now.
plot.setDateSegmentationProperty("signUp", new Date());

More general information about segmentation is available in the segmentation guide.

Back To Top

6. Xamarin Plugin

The Plot Projects Xamarin plugin is available for both iOS and Android. The plugin isn't available for the Xamarin Starter Edition, since it uses native bindings. We recommend installing the plugin via NuGet. We also have it available on github: https://github.com/Plotprojects/plot-xamarin-plugin

You can find all the steps needed for a simple integration at the integration guide.

Back To Top

7. Dashboard API

We offer an API to add and modify geofences (locations) and notifications (campaigns) for the Plot plugin. When you want to manage the notifications using a visual interface then you can use our Dashboard.

Documentation about the API and the specific calls can be found at the full API documentation.

The API is located at the following URL: https://admin.plotprojects.com

All requests have a Basic Authentication header with the appId as username and the private key as password. You can find these under "Integrate Plugin" in our Dashboard.

All requests return content of type application/json in UTF-8 encoding. All PATCH and POST requests consume a body of type application/json in UTF-8 encoding.

Currently our API has a limit to the amount of request you can do of 10 per second. Exceeding this limit will result in an unsuccessful API call and an 429 Too Many Requests response.

Back To Top

8. Glossary

This page provides a list of terms that are specific to our platform:

Appcelerator
Appcelerator is the company behind Titanium. For more information see their homepage.
AppDelegate
An object in iOS responsible for handling state transitions within your app. The delegate is responsible for initialization of the app and receiving of notifications. For more information see the iOS Programming Guide.
A link to another app, this can be triggered when tapping on a notification. Settings for this have to be put into the data field and the handlerType has to be set to applink.
App Store
A platform provided by Apple to distribute your app on iPhones and iPads.
Background mode
A marker that your app wants to continue running in the background (iOS only). A distinction is made between various background modes. Plot doesn't require a background mode to function. Get more information from the iOS Programming Guide.
Background services
Get more information from the Android documentation.
Broadcast receiver
For more information see Android Reference.
Campaign
A campaign is a notification attached to a set of geofences. The notification message might be different per geofence by using the geofence label. A campaign makes maintaining notifications easier by not having to define a notification for each geofence.
Cellular Triangulation
A battery efficient technique to determine the location of the device based on the cellular networks the device uses. This technique is available for all iPhones, and for iPads and Android devices that can make use of cellular networks.
Cooldown period
The minimum time between two notifications. This period is to prevent users to get a flood of notifications.
Cordova
Apache Cordova is a platform to build platform independent apps. Plot has provided a module for this platform to make integration trivial. Get more information from their website.
Country field
You can attach a campaign to a country. The field has to be set with a three-letter country code, a list of available codes can be found here.
Custom region field
A custom region field should be defined inside your app settings. Specify custom region fields for a geofence or beacon which can be used later as placeholders in the campaign message. For instance, you can create a field shopname that will contain the shop name for each geofence. Using it inside the campaign message allows you to mention the shop name depending on which geofence gets triggered. The field names are case insensitive and cannot contain duplicates.
Data field
Contains your own custom data which you could use inside a notification/geotrigger handler or notification filter. You can get this data inside your app by getting the data attribute from the notification or geotrigger. If the data field contains an URI starting with http or https and no handler is created by the user the data field will be opened in the app browser as URI. The data field can also be used to set a landing page or an applink.
Data update
An update of the notifications cached in the device. Notifications that can be sent by a device are cached locally to prevent network usage at every location update.
Datetime
A combination of a date and time.
Dwelling notifications
A notification that is sent when the user remains within the geofence or beacon region for a specified amount of time. The time is adjustable per notification and must be between 5 minutes and 12 hours.
Exit notifications
A notification that is sent when the user leaves the geofence or beacon region.
Framework
A framework allows you to build platform independent apps. You write code once and compile both Android and iOS. Currently we support three frameworks; Appcelerator (Titanium), Cordova / Phonegap and Xamarin.
Geofence
A location with a radius that you can send notifications for.
Geotrigger
A geotrigger is used to see if users enter or exit a geofence or gets into or leaves the range of an iBeacon. It works similarly as a notification, but it does not display anything on the device of the user.
Geotrigger campaign
Similar to a campaign for notifications, this is a campaign for geotriggers on multiple geofences. This makes it easier to maintain and evaluate your sets of geofences.
GPS
A technique to determine the location of the device. This technique is accurate, but isn't very battery efficient. Because it isn't very battery efficient, Plot doesn't make use of this technique.
iBeacon
A device that broadcasts using Bluetooth 4.0 to allow indoor positioning.
Intent
A technique for Android to perform inter-process communication. An Intent is a message from one app to another. For more information see the Android Development Guide.
Ionic
Ionic is a platform to build platform independent apps. It is built on top of Apache Cordova and AngularJS. Plot has provided a module for Cordova, thus we also support Ionic. More information on Ionic can be found on their website.
iOS
The operating system that runs on iPhones and iPads.
Landing page
An HTML page shown when a notification is triggered. The link to the landing page should be set inside the data field and the handlerType to landingPage. In-app landing pages bypass the notification filter and the notification handler.
Local notification
A notification sent directly from an app. This notification doesn't require a remote server, therefore can be viewed instantly on the device.
Location based notification
A notification sent to a user based on their current location.
Location services
The service offered by Android and iOS that provides the current location of the device to apps.
Notification center
The area in the user interface of iOS where the notifications are shown.
Notification events
Events sent by our plugin each time a notification is shown to the user (sent) or tapped on by the user (opened).
Notification filter
An optional callback in Plot that can be used to prevent notifications from being shown or modify the notifications before they are viewed to the user.
Notification handler
An optional callback in Plot that can be used to change the action when a notification is tapped.
PhoneGap
A platform, based on Cordova, to build platform independent apps. Plot has provided a module for this platform to make integration trivial. Get more information from their website.
Play Store
A platform provided by Google to distribute your app on Android devices.
Private token
A token provided by Plot that provides authorization to maintain geofences and notifications. You must not use this token inside your app.
Proguard
Proguard is a tool for Android to obfuscate and optimize your Java classes. This tool makes it harder to decompile your code.
Public token
A token provided by Plot that is used inside your app to obtain notifications.
Push notification
A notification sent from a remote server. Plot doesn't make use of this technique, because it could take minutes before a notification that has been sent is received by a device. The notification may then be no longer relevant.
QuickSync
An improved way to synchronise your app users' devices with our server. Instead of letting your users' devices poll for changes, new or updated notifications get actively pushed upon change. More information can be found here.
Sent notification
When Plot detects that a user is in a Geofence and no constraints prevent the notifications from being sent, then the notification is sent. A Sent notification may or may not have been viewed by the user.
Significant location change
A technique available in iOS to determine when the device has moved significantly. This technique is very energy efficient, but very inaccurate and unpredictable. Plot doesn't make extensive use of this technology.
Titanium
A platform by Appcelerator to build platform independent apps. Plot has provided a module for this platform to make integration trivial. Get more information at their website.
Trigger times
Which time mechanic is used for the notification, this can be inherit, where the notification will use its Geofence or iBeacon time settings, it can be anytime, being active at any time, timespans, where it uses custom defined time spans, and openinghours, which are repeated time spans defined for a week.
Viewed notification
After a notification is sent, a user may tap on a notification. When a user has tapped on a notification, the corresponding action is executed and the notification is marked viewed.
Wifi triangulation
A battery efficient technique to determine the location of the device based on Wifi. The device detects what Wifi access points are available in the current area and compares those with the database maintained by Google (in case of Android) or Apple (in case of iOS). For this technique to work, the device needs to have internet access, but the device doesn't require access the these Wifi access points.
Xamarin
With Xamarin it is possible to do Android and iOS in C# with either Visual Studio or Xamarin Studio. This allows you to re-use existing C# code, and share code across device platforms.

Back To Top