1. Overview

1.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.

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

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.

Back To Top

1.2 What is Plot

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 behavior 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.

Platforms:   iOS   Android


iOS

When enabled, 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.

The Plot plugin is optimized for users traveling 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 traveling 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), including multiple UUID support (from version 2.0 and up). This feature is not available if 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. Read all documentation regarding our iBeacon support in the iBeacons section.


Android

When enabled, 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 traveling at low speeds (walking, cycling). The geofences and notifications will be synchronized with our backend every couple hours. When traveling 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), including multiple UUID support (from version 3.0 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. 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 the iBeacons section.

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

Back To Top

1.3 Feature overview


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 React Native Appcelerator (Titanium) PhoneGap / Cordova / Ionic Xamarin
Basic features[1]
Enabling/Disabling
Beacons [2]
Multiple Beacon UUIDs
Geotriggers [3] [3]
Notification handler
Notification filter
Geotrigger handler
Segmentation
Retrieve cached notifications
Retrieve sent notifications
QuickSync [4] [4] [4]
Attribution events
Notification events
Advertising identifier
Contextual pages
[1] Basic features are geofencing, enter, exit and dwelling notifications, campaigns, resendability, timespans, opening hours and landing pages.
[2] This feature is currently not available for iOS.
[3] Geotriggers with dwelling minutes are not supported on iOS.
[4] For both iOS and Android additional integration steps are needed.

Back To Top

1.4 Selecting features

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.


Location Services Permission dialog

Both for iOS and for Android, it is required to ask the user permission first before getting access to the location of the device. By default, the Plot plugin will automatically ask this permission after the initialization method has been called. Starting from plugin version 2.0.0(iOS)/2.1.0(Android) it is possible to disable this functionality and ask the permission yourself. This allows to pick a more logical time to show the opt-in dialog to the user.

The best results are achieved when you first prime the user that the location services permission will be asked. During this process you tell the user that the app wants to make use of the location of the phone and what advantages it brings for the user. When the user agrees to share their location, then you can show the opt-in dialog.

In Android, it is required to ask permission for location services starting from Marshmallow. In older versions the permission will be asked straight away when installing the app. When your app requests permission for the second time, the "Never ask again" checkbox is added to the dialog. If the user checks this, it will no longer be possible to directly ask the user to opt-in for location services. Therefore, it is important to not ask too often for this permission when the user hasn't granted it the first time. When a user changes their mind, he can change their permission settings in the Settings screen.

Starting from iOS 8 there is a distinction between asking permission for location services that can be used when the app is in use and permission for always access to location services. To achieve best results with the plugin, the always permission is required. Starting from iOS 11 the user always has the option to give the When in use permission, not just the Always permission. When a user changes their mind, he can change their permission settings in the Settings app. It is possible to first ask for When in use permission, which then later can be upgraded to Always permission. To get best results, we recommend explaining to the user why the Always permission is needed and what it brings for the user.

Find more about enabling/disabling the opt-in dialog in the Configuration file section.


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. Rich notifications are also available on iOS. 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 and Android Geotrigger handling, Appcelerator Geotrigger handling. For Phonegap, read the blog post How to implement NotificationFilter and GeotriggerHandler for Phonegap/Cordova/Ionic.


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 be syncronized with all your users devices immediately.

In order to enable this feature some additional steps are required:

 Enable QuickSync for iOS

 Enable QuickSync for Android

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

This functionality is very unreliable on iOS 11 when the app is in the background due to platform limitations. Further information can be found at Some Notifications received, but not All


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.

Contextual Pages

The plot plugin makes it possible to show the most relevant app content to the app's users by implementing this feature.

The user opens the app and sees straight away a location relevant page.

More information about Contextual pages can be found in the Contextual Pages section.

Back To Top

1.5 Supported platforms

Apart from native Android and iOS, Plot is offering support for PhoneGap / Cordova / Ionic, Appcelerator (Titanium), Xamarin and React native.

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

A React Native integration is available at https://github.com/Plotprojects/plot-react-native. We have included documentation on how to integrate in the readme file. There is also a step-by-step integration guide.

A full overview of the supported features can be found here.

Back To Top

2. How-to guides

2.1 Demo app guide


Try Plot Projects For Yourself In Five Easy Steps

The Plot Projects Demo App enables you to:

  • Experience how easy it is to create and send geofencing notifications on your own device
  • Get acquainted with our simple and intuitive dashboard
  • Send yourself a notification without any coding!

 

1. Get your Account Or Log In

Don't have an account yet? Schedule a demo and we'll invite you to your account.

Directly after getting your account, you will be introduced to your "personal dashboard".

If you already have an account with Plot Projects, just go straight to your dashboard.

 

2. Download The Demo App

For iOS you can find the free Plot Projects Demo App in the Apple App Store.

For Android you can find the free Plot Projects Demo App in the Google Play Store.

 

3. Enter Your Token

To enable the Demo App to receive the push notification, enter the six digit token that appears on your screen.

Go to “Settings” in the Demo App, followed by "Connect To Account" and enter the six digit token.

At this point you will be prompted to allow Plot Projects to access you location information and to send you push notifications. Make sure to opt-in for both!

 

4. Create A Campaign

Click on the blue button on the bottom right corner. Choose "New Notification Campaign".

Enter a campaign name and notification message.

Scroll down the page to the section titled "select regions for this campaign". On the map, make sure to enter your current location. Once you have selected the location, you will notice a red circle appearing in the map. That's your geofence.

Then scroll to the bottom of the page and select "create" to set your geofence live.

 

5. Check Your Phone For a Notification

As soon as you enter the geofence, your phone will receive the notification message that you just created!

Back To Top

2.2 iOS integration guide

Update October 26th 2017: We have updated this guide after the release of version 2.0.2 of our iOS plugin.

We assume in this guide you already have an account for our dashboard. Don't have an account yet? Schedule a demo and we'll invite you to your account.

 

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.

 

This guide shows how to integrate iOS version of the Plot plugin. You can find all versions at our download page.

  1. Integration with Cocoapods, using Swift
  2. Integration with Cocoapods, using Objective C
  3. Integration without Cocoapods, using Swift
  4. Integration without Cocoapods, using Objective C

 

1. Integration with Cocoapods, using Swift

To use the library in an iOS application, a few steps must be performed. The first steps differ based on whether or not you're using Cocoapods. The Cocoapods integration is the easiest, but if you want to add the library yourself to the project that is fine too.

 

Step 1: Update your podfile

If you are using CocoaPods, just add the following line to your Podfile to integrate the library into your IOS application.

Add the following to your podfile:

use_frameworks!
pod 'PlotPlugin'

or if you want to use a specific version:

use_frameworks!
# You can replace '2.3.0' with the latest version specified at our download page
pod 'PlotPlugin', '2.3.0'

 

Step 2: Run pod install

Run

pod install --repo-update

to let Cocoapods download our library and setup the new project structure.

 

Step 3: Add usage description

Add in "Custom iOS Target Properties" under "Info" the keys from the table below. Each value must be a message for the user describing 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."

Required key Description shown in XCode
NSLocationAlwaysUsageDescription Privacy - Location Always Usage Description
NSLocationWhenInUseUsageDescription Privacy - Location When In Use Usage Description
NSLocationAlwaysAndWhenInUseUsageDescription* Privacy - Location Always and When In Use Usage Description
* this key is added in XCode 9. If you're using XCode 8, you can add the key yourself.

This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.

 

Step 4: Add configuration file

You can configure Plot through the configuration file. You can find an example config file and your public token on the Developer page on our dashboard.

Add this file as plotconfig.json in the root folder.

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

 

Step 5: Add PlotDelegate

Add PlotDelegate to the implemented protocols of your AppDelegate.

@UIApplicationMain
class AppDelegate: UIResponder,
                   UIApplicationDelegate,
                   PlotDelegate

 

Step 6: Implement AppDelegate
Warning: In the case that you need to register your own UNUserNotificationCenter delegate, you need to do that before initializing the plugin, so that Plot can forward notifications that aren't created by Plot. If you do it after initializing, then the notification handler/notification events will no longer work.

In your AppDelegate call PlotDebug.initialize(launchOptions: launchOptions, delegate: self) in func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool. The initialize method must be called before the end of that method.

Plot is enabled by default on the first run. If you don't want Plot enabled by default, you can set the enableOnFirstRun property in plotconfig.json to false if Plot shouldn't be enabled by default. If you don't want the permission dialogs to appear straight away when it initializes, then you can add the automaticallyAskLocationPermission property and the automaticallyAskNotificationPermission property in plotconfig.json to false. When setting those properties to false, you become responsible yourself for asking the user for location services and notification permissions.

import PlotProjects

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

  //Register your notification center delegate before initializing Plot:
  //let center = UNUserNotificationCenter.current()
  //center.delegate = ...

  //PlotDebug enables extra debug logging
  //which makes it easier to understand
  //what is going on
  //
  //Replace PlotDebug with PlotRelease
  //to disable debug logging
  PlotDebug.initialize(launchOptions: launchOptions, delegate: self)

  //This method must be called before the end of application(,didFinishLaunchingWithOptions)


  return true
}
...

Now the Plot Projects library should be ready for use! Create a notification in the dashboard at your current location and launch your app to verify it's working.

An example configuration file and your public token can be found on the Help page on our dashboard. You are now ready to receive your first notification. Need more help during testing, look at the test guide.

 

Step 7: Test

For more details, look at the testing section of the documentation.

 

2. Integration with Cocoapods, using Objective C

To use the library in an iOS application, a few steps must be performed. The first steps differ based on whether or not you're using Cocoapods. The Cocoapods integration is the easiest, but if you want to add the library yourself to the project that is fine too.

 

Step 1: Update your podfile

If you are using CocoaPods, just add the following line to your Podfile to integrate the library into your IOS application.

Add the following to your podfile:

use_frameworks!
pod 'PlotPlugin'

 

Step 2: Run pod install

Run

pod install --repo-update

to let Cocoapods download our library and setup the new project structure.

 

Step 3: Add usage description

Add in "Custom iOS Target Properties" under "Info" the keys from the table below. Each value must be a message for the user describing 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."

Required key Description shown in XCode
NSLocationAlwaysUsageDescription Privacy - Location Always Usage Description
NSLocationWhenInUseUsageDescription Privacy - Location When In Use Usage Description
NSLocationAlwaysAndWhenInUseUsageDescription* Privacy - Location Always and When In Use Usage Description
* this key is added in XCode 9. If you're using XCode 8, you can add the key yourself.

This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.

 

Step 4: Add configuration file

You can configure Plot through the configuration file. You can find an example config file and your public token on the Developer page on our dashboard.

Add this file as plotconfig.json in the root folder.

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

 

Step 5: Add PlotDelegate

Add PlotDelegate to the implemented protocols of your AppDelegate in the header (.h) file.

#import <PlotProjects/Plot.h>

@interface AppDelegate : UIResponder
  <UIApplicationDelegate, PlotDelegate>

 

Step 6: Implement AppDelegate
Warning: In the case that you need to register your own UNUserNotificationCenter delegate, you need to do that before initializing the plugin, so that Plot can forward notifications that aren't created by Plot. If you do it after initializing, then the notification handler/notification events will no longer work.

In the implementation file (.m) of your AppDelegate call [Plot initializeWithLaunchOptions:launchOptions delegate:self] in application:didFinishLaunchingWithOptions:. The initialize method must be called before the end of that method.

Plot is enabled by default on the first run. If you don't want Plot enabled by default, you can set the enableOnFirstRun property in plotconfig.json to false if Plot shouldn't be enabled by default. If you don't want the permission dialogs to appear straight away when it initializes, then you can add the automaticallyAskLocationPermission property and the automaticallyAskNotificationPermission property in plotconfig.json to false. When setting those properties to false, you become responsible yourself for asking the user for location services and notification permissions.

@implementation AppDelegate

-(BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  //Register your notification center delegate before initializing Plot:
  //[[UNUserNotificationCenter currentNotificationCenter].delegate = ...

  //initializes the Plot library:
  [Plot initializeWithLaunchOptions:launchOptions delegate:self];
  //This method must be called before the end of the application:didFinishLaunchingWithOptions: method

  return YES;
}
...

Now the Plot Projects library should be ready for use! Create a notification in the dashboard at your current location and launch your app to verify it's working.

An example configuration file and your public token can be found on the Help page on our dashboard. You are now ready to receive your first notification. Need more help during testing, look at the test guide.

 

Step 7: Test

For more details, look at the testing section of the documentation.

 

3. Integration without Cocoapods, using Swift

To use the library in an iOS application, a few steps must be performed. The first steps differ based on whether or not you're using Cocoapods. The Cocoapods integration is the easiest, but if you want to add the library yourself to the project that is fine too.

 

Step 1: Get The Library

Once you log in to our dashboard, download the library under the "Developer Tools" page.

 

Step 2: Add PlotProjects.framework and other dependencies to your project

Extract the zip file and copy the PlotProjects.framework file to your project.

In the target settings add the following libraries in "Link Binary with libraries" under "Build phases"

  • PlotProjects.framework
  • libsqlite3.tbd
  • CoreLocation.framework
  • MessageUI.framework
  • UserNotifications.framework

You also need to add PlotProjects.framework to Embedded Binaries as well

 

Step 3: Add usage description

Add in "Custom iOS Target Properties" under "Info" the keys from the table below. Each value must be a message for the user describing 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."

Required key Description shown in XCode
NSLocationAlwaysUsageDescription Privacy - Location Always Usage Description
NSLocationWhenInUseUsageDescription Privacy - Location When In Use Usage Description
NSLocationAlwaysAndWhenInUseUsageDescription* Privacy - Location Always and When In Use Usage Description
* this key is added in XCode 9. If you're using XCode 8, you can add the key yourself.

This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.

 

Step 4: Add configuration file

You can configure Plot through the configuration file. You can find an example config file and your public token on the Developer page on our dashboard.

Add this file as plotconfig.json in the root folder.

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

 

Step 5: Add PlotDelegate

Add PlotDelegate to the implemented protocols of your AppDelegate.

@UIApplicationMain
class AppDelegate: UIResponder,
                   UIApplicationDelegate,
                   PlotDelegate

 

Step 6: Implement AppDelegate
Warning: In the case that you need to register your own UNUserNotificationCenter delegate, you need to do that before initializing the plugin, so that Plot can forward notifications that aren't created by Plot. If you do it after initializing, then the notification handler/notification events will no longer work.

In your AppDelegate call PlotDebug.initialize(launchOptions: launchOptions, delegate: self) in func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool. The initialize method must be called before the end of that method.

Plot is enabled by default on the first run. If you don't want Plot enabled by default, you can set the enableOnFirstRun property in plotconfig.json to false if Plot shouldn't be enabled by default. If you don't want the permission dialogs to appear straight away when it initializes, then you can add the automaticallyAskLocationPermission property and the automaticallyAskNotificationPermission property in plotconfig.json to false. When setting those properties to false, you become responsible yourself for asking the user for location services and notification permissions.

import PlotProjects

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

  //Register your notification center delegate before initializing Plot:
  //let center = UNUserNotificationCenter.current()
  //center.delegate = ...

  //PlotDebug enables extra debug logging
  //which makes it easier to understand
  //what is going on
  //
  //Replace PlotDebug with PlotRelease
  //to disable debug logging
  PlotDebug.initialize(launchOptions: launchOptions, delegate: self)

  //This method must be called before the end of application(,didFinishLaunchingWithOptions)


  return true
}
...

Now the Plot Projects library should be ready for use! Create a notification in the dashboard at your current location and launch your app to verify it's working.

An example configuration file and your public token can be found on the Help page on our dashboard. You are now ready to receive your first notification. Need more help during testing, look at the test guide.

 

Step 7: Test

For more details, look at the testing section of the documentation.

 

4. Integration without Cocoapods, using Objective C

To use the library in an iOS application, a few steps must be performed. The first steps differ based on whether or not you're using Cocoapods. The Cocoapods integration is the easiest, but if you want to add the library yourself to the project that is fine too.

 

Step 1: Get The Library

Once you log in to our dashboard, download the library under the "Developer Tools" page.

 

Step 2: Add PlotProjects.framework and other dependencies to your project

Extract the zip file and copy the PlotProjects.framework file to your project.

In the target settings add the following libraries in "Link Binary with libraries" under "Build phases"

  • PlotProjects.framework
  • libsqlite3.tbd
  • CoreLocation.framework
  • MessageUI.framework
  • UserNotifications.framework

You also need to add PlotProjects.framework to Embedded Binaries as well

 

Step 3: Add usage description

Add in "Custom iOS Target Properties" under "Info" the keys from the table below. Each value must be a message for the user describing 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."

Required key Description shown in XCode
NSLocationAlwaysUsageDescription Privacy - Location Always Usage Description
NSLocationWhenInUseUsageDescription Privacy - Location When In Use Usage Description
NSLocationAlwaysAndWhenInUseUsageDescription* Privacy - Location Always and When In Use Usage Description
* this key is added in XCode 9. If you're using XCode 8, you can add the key yourself.

This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.

 

Step 4: Add configuration file

You can configure Plot through the configuration file. You can find an example config file and your public token on the Developer page on our dashboard.

Add this file as plotconfig.json in the root folder.

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

 

Step 5: Add PlotDelegate

Add PlotDelegate to the implemented protocols of your AppDelegate in the header (.h) file.

#import <PlotProjects/Plot.h>

@interface AppDelegate : UIResponder
  <UIApplicationDelegate, PlotDelegate>

 

Step 6: Implement AppDelegate
Warning: In the case that you need to register your own UNUserNotificationCenter delegate, you need to do that before initializing the plugin, so that Plot can forward notifications that aren't created by Plot. If you do it after initializing, then the notification handler/notification events will no longer work.

In the implementation file (.m) of your AppDelegate call [Plot initializeWithLaunchOptions:launchOptions delegate:self] in application:didFinishLaunchingWithOptions:. The initialize method must be called before the end of that method.

Plot is enabled by default on the first run. If you don't want Plot enabled by default, you can set the enableOnFirstRun property in plotconfig.json to false if Plot shouldn't be enabled by default. If you don't want the permission dialogs to appear straight away when it initializes, then you can add the automaticallyAskLocationPermission property and the automaticallyAskNotificationPermission property in plotconfig.json to false. When setting those properties to false, you become responsible yourself for asking the user for location services and notification permissions.

@implementation AppDelegate

-(BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  //Register your notification center delegate before initializing Plot:
  //[UNUserNotificationCenter currentNotificationCenter].delegate = ...

  //initializes the Plot library:
  [Plot initializeWithLaunchOptions:launchOptions delegate:self];
  //This method must be called before the end of the application:didFinishLaunchingWithOptions: method

  return YES;
}
...

Now the Plot Projects library should be ready for use! Create a notification in the dashboard at your current location and launch your app to verify it's working.

An example configuration file and your public token can be found on the Help page on our dashboard. You are now ready to receive your first notification. Need more help during testing, look at the test guide.

 

Step 7: Test

For more details, look at the testing section of the documentation.

Back To Top

2.3 Android integration guide

Notice: When updating from an older version of Plot, make sure no old references to the Plot Projects plugin are in the AndroidManifest. No need to define services of Plot Projects plugin yourself. You do need to register the notification filter and handler yourself when you have one.

To integrate Plot Projects Android Plugin, a few steps have to be performed. This guide starts from a blank activity (How to create a blank activity) and is designed for Android Studio 3.2.1 with Gradle 4.6. Existing projects can follow this but additional configuration may be required.

 

Step 1: Integrating the Plot Projects Maven repository

Previously, you had to download and add the plugin manually by going into the dashboard and downloading the plugin under the "Developer Tools" page, even though this is still possible, we automated this process by creating a Maven repository that allows you to include our plugin with ease. This guide only explains how to use the Maven repository.

To allow the Plot Projects Android plugin to be found, add the Plot Projects Maven repository to your build.gradle:

allprojects {
    repositories {
        google()
        jcenter()
        
        // allow gradle to find the Plot Projects Plugin
        maven {
            url 'https://maven-repo.plotprojects.com'
        }
    }
}

 

Step 2: Add Plot Projects Android plugin

Add the Plot Projects Android plugin as a dependency in your app/build.gradle:

Select plugin version:

dependencies {
    // other dependencies

    // use compile instead of implementation when using Android Studio 2.x
    implementation 'com.plotprojects:plot-android:3.0.2'
    implementation 'com.android.support:support-v4:27.1.1'
    implementation 'com.google.android.gms:play-services-gcm:15.0.1'
    implementation 'com.google.android.gms:play-services-location:15.0.1'
    implementation 'com.google.android.gms:play-services-nearby:15.0.1'
    implementation 'com.google.firebase:firebase-core:16.0.1'
    implementation 'com.google.firebase:firebase-messaging:17.0.0'
}

Note: The dependencies com.google.android.gms:play-services-gcm and com.firebase:firebase-jobdispatcher are incompatible with each other. If your app requires firebase-jobdispatcher, you have to use com.firebase:firebase-jobdispatcher-with-gcm-dep instead. It should be a drop-in replacement. For more information about build dependencies in Gradle, refer the official Android Developer documentation on build dependencies

You can find all versions of the Android Plugin at our download page.

 

Step 3: Set minimum supported Android version

The Plot Projects Android plugin supports only Android 4.0 (Ice Cream Sandwich) and up. Set the minSdkVersion version to at least 14 in your app/build.gradle

android {
    // other android specific gradle configuration

    defaultConfig {
        applicationId "com.myplotapplication"
        minSdkVersion 14
        targetSdkVersion 28
        versionCode 1
        versionName "1.0"
    }   
}

 

Step 4: Define configuration file

Plot uses a configuration file which you have to define as assets/plotconfig.json. When no assets folder is available, you can create one in Android Studio by right clicking on your project, in the Project tool window, and then selecting New > Folder > Assets Folder.

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

An example of such a config file can be found on our dashboard, as well as the public token you will have to use.

 

Step 5: Almost done!

Call Plot.init(context) to initialize the plugin from your main Activity.

When calling init from an activity, you can use the this keyword as the first parameter.

import com.plotprojects.retail.android.Plot;

public class MyActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // code of your activity

        Plot.init(this); // add this line initialize the Plot Plugin
    }
}
You are now ready to receive your first notification. Need more help during testing, look at the test guide.

 

Step 6: Test

For more details, look at the testing section of the documentation.

Back To Top

2.4 Phonegap integration guide

To install the Plot plugin into your PhoneGap/Cordova/Ionic app only a couple of small steps have to be performed. Note that this plugin requires PhoneGap 3.0.0 or higher. This plugin supports both iOS 6 or newer, and Android 2.3 or newer.

 

Step 1: Get The Plugin

There are two ways to get the plugin:

i) Use config.xml

Add the following line to config.xml to add our plugin.

<gap:plugin name="cordova-plotprojects" source="npm" version="2.x" />
ii) Command line

You can add the plugin to an existing project by executing the following command:

PhoneGap:

phonegap plugin add cordova-plotprojects

Cordova/Ionic:

cordova plugin add cordova-plotprojects

 

Step 2: Add Configuration File

Before you can use the plugin, you have to add a configuration file in the www/folder and name the file plotconfig.json. The snippet on the right shows an example of the file. You can find your public token in the dashboard.

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

 

Step 3: Almost done!

You can initialize the Plot library using the snippet on the right.

<script type="text/javascript">// <![CDATA[ document.addEventListener("deviceready", deviceReady, true); function deviceReady() { var plot = cordova.require("cordova/plugin/plot"); plot.init(); } // ]]></script>

You are now ready to receive your first notification. For more details, look at our Github page.

Need more help during testing, look at the testing section of the documentation.


In case you're using a version of our plugin prior to 2.1 and can't run your app on XCode due to the "framework not found Plotprojects" error, please take a look at Troubleshooting Phonegap/Cordova/Ionic integration on XCode to quickly fix it.

Back To Top

2.5 Appcelerator integration guide

To install the Plot plugin into your Appcelerator Titanium app only a couple of small steps have to be performed. Note that this module was developed for Titanium 6.2.2.GA or newer. This plugin supports both iOS and Android.

 

Step 1: Download The Zip

Log into our dashboard, go to the "Developer Tools" tab, by clicking on "Download Plot Projects SDK". There you find the latest version of Appcelerator module. The plugin can be obtained as a .zip file found under "Appcelerator Titanium Module" on that page. Don't have a Plot Projects account? Schedule a demo and we'll invite you to your account.

 

Step 2: Install in Appcelerator Studio

After you downloaded the .zip for the plugin, you install it in Appcelerator Studio by following the following steps:

  1. Open Appcelerator Studio.
  2. In the Help menu, select Install Mobile Module.
  3. Insert the .zip file obtained in the previous step.

 

Step 3: Add Configuration File

Before using the plugin, you add a configuration file in the assets folder and name the file plotconfig.json. The snippet on the right shows an example of the file. You look up your public token in the dashboard.

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

 

Step 4: Set permission rationale

Note that if your app also targets iOS, then it is required to specify why your app requires location services. You do that in your plist. Add the following lines to tiApp.xml at the ios/plist/dict element:

<key>NSLocationAlwaysUsageDescription</key>
<string>The app uses your location in order to inform you about special offers in nearby stores.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>The app uses your location in order to filter information shown based on what's near you.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>The app uses your location in order to inform you about special offers in nearby stores and customize its content based on what's near.</string>

 

Step 5: Almost done!

Add the snippet below to one of your scripts used to initialize your application. You usually do this in app.js or alloy.js:

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

You are now ready to receive your first notification. For more details, look at our Github page.

Need more help during testing, look at the testing section of the documentation.

Back To Top

2.6 Xamarin integration guide

We assume in this guide you already have an account for our dashboard. Don't have an account yet? Schedule a demo and we'll invite you to your account.

 

Step 1: Both iOS & Android

Our library supports both iOS and Android. We recommend installing our plugin through NuGet as it automatically ensures the right version of our library is included. You can find the plugin in the NuGet gallery under the name "PlotProjects.Plugin".

It is possible to make use of the IPlot interface in your own portable library projects, but then you still have to add the Plot Projects Xamarin Plugin to the platform specific projects as well.

 

Step 2: Android Step Only

You can skip this section when your app doesn't need Android support.

Place plotconfig.json in the Assets folder of your Android project. You can configure Plot through the configuration file. You can find an example config file and your public token on the Developer page on our dashboard.

 

Step 3: Android Step Only

You can skip this section when your app doesn't need Android support.

Call PlotProjects.Plugin.Plot.GetInstance(activity) from the OnCreate method of one of your activities.

Known issue for Android: When the Android Package name contains a dash or an underscore the mail debug log feature doesn't work. You can fix this by adding the following element to the application element of your AndroidManifest, with YOUR_PACKAGE_NAME replaced:

<provider
   android:authorities="YOUR_PACKAGE_NAME.plot.debuglogprovider"
   android:name="com.plotprojects.retail.android.DebugLogProvider"
   android:exported="true" />

When your android package name doesn't contain any special characters, no steps are required.

 

Step 4: iOS Step Only

You can skip this section when your app doesn't need iOS support.

Place plotconfig.json in the Resources folder of your project. You can configure Plot through the configuration file. You can find an example config file and your public token on the Developer page on our dashboard.

 

Step 5: iOS Step Only

Add the following line to your FinishedLaunching method in your AppDelegate:

PlotProjects.Plugin.Plot.GetInstance(launchOptions, true);

 

Step 6: iOS Step Only

Add in "Info.plist" under the Source tab the keys from the table below. Each value must be a message for the user describing 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."

Required key Description shown in Visual Studio
NSLocationAlwaysUsageDescription Privacy - Location Always Usage Description
NSLocationWhenInUseUsageDescription Privacy - Location When In Use Usage Description
NSLocationAlwaysAndWhenInUseUsageDescription Privacy - Location Always and When In Use Usage Description

This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.

 

You are now ready to receive your first notification. For more details, look at our Github page.

Need more help during testing, look at the testing section of the documentation.

Back To Top

2.7 React Native integration guide

We assume that you already have a React Native app. However, in case you're starting from scratch, you can follow the official "Getting Started" guide and pick the option"Building Projects with Native Code".

An example of a React Native project with the Plot Projects plugin already integrated can be found on our Github page.

 

iOS integration

Since we're working with the native variant of React, the necessary steps to integrate the Plot plugin are the same as in a native iOS app. This procedure can be found in the iOS integration guide.

 

Android integration

Since we're working with the native variant of React, the necessary steps to integrate the Plot plugin are the same as in a native Android app. This procedure can be found in the Android integration guide.

Back To Top

2.8 Segmentation - How to get started


Plot Projects offers 2 ways of segmentation: client side segmentation and server side segmentation.

In case you're not sure wich one suits your business the most please feel free to contact us so we can explain you a bit more the difference between these two.

The rest of this paragraph is about server side 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.

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


Segmentation Properties In Dashboard

You can specify in notifications and campaign notifications what segmentation properties must have been set on the device before the device can receive these notifications. When a property that is set on the notification isn't set on the device or the property on the device has a different value than on the notification, then the notification isn't sent. This is also the case for apps with an older version of the Plot Plugin that doesn't have support for segmentation. Segmentation properties set on the device, but not on the notification or campaign are ignored.

The segmentation settings for a notification are under the Advanced Settings. By default all devices can receive a notification.


Device Properties

Before users can receive segmented notifications you have to specify to what segment the user belongs. Both on iOS and on Android the Plot class has methods that allow setting the segments the user belongs to. When you specify a new value for a segmentation property that is already defined, the old value is overwritten with the new value.

All currently loaded notifications on the device will be removed when calling one of the segmentation property methods. The next data update will contain all appropriately segmented notifications.

There is a specific method for each property type. Currently the supported types are integer (numeric values), double (numeric decimal values), string (text values), date (UNIX timestamp) and boolean (true or false). Below is an example snippet for each platform on how to set the segment gender to male on the device.

Example iOS snippet:

[Plot setStringSegmentationProperty:@"M" forKey:@"gender"];

Example Android snippet:

Plot.setStringSegmentationProperty("gender", "M");

Example Appcelerator/Phonegap snippet:

plot.setStringSegmentationProperty("gender", "M");

The Segmenting notifications chapter further explains segmentation in a technical way and examples per type can be found for iOS, Android, Appcelerator and Phonegap.

It is currently not yet possible to specify segments in our test apps that are available through the Play Store or the App Store.


Segment On Campaign History

When you set the property type to “campaignhistory” you can segment on users who have, or haven’t, triggered a (geotrigger)campaign earlier. You can for example use this feature to send notifications to users that have been to your store earlier or to a store of a competitor.

You specify a Campaign Id segmentation property in the dashboard just like device properties. You have to specify the campaign id, the number of times the user has triggered that campaign and in what time frame these triggers must have occurred. You do not have to set any properties for this on the device.

The Segmenting notifications chapter further explains this in a technical way.


Custom Reporting

For customers with our Gold or Platinum plan it is possible to make the segments you define in your app part of your custom reports. Contact us for more information.

Back To Top

2.9 QuickSync - How to get started


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 awhile. 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 be syncronized with all your users devices immediately.


Platforms:   iOS   Android


iOS

On iOS Quicksync is very reliable when your app is in the foreground. Due to platform limitations of iOS 11.2 and up, Quicksync sometimes works less reliable when your app is in the background. Further information can be found at Some Notifications received, but not All.

We will keep track of new iOS releases and inform you in case Apple fixes this limitation.

When the app is in foreground the Quick Sync still works as expected.

Guide for Plot version 1.15.4 and newer:

Add QuickSync to receive your notifications immediately. Starting from 1.15.4 it uses Firebase Messaging. This guide assumes you’ve integrated Plot using Cocoapods. Make sure you already have integrated Plot using the iOS integration guide.

Step 1: Add the Firebase pod to your Podfile.
pod 'Firebase/Messaging', '4.5.0'
Step 2: Add didReceiveRemoteNotification method

Copy the following snippet into your AppDelegate:

-(void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [Plot didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
}

Note: When you use other Firebase functionality in your code, you have to call [FIRApp configure] before calling [Plot initialize…]

Setting up Firebase:
Step1: Setup a Firebase Project

Follow the steps at the Firebase Console to setup your project and make sure you enable cloud messaging for your project.

Step 2: Add Config File

To obtain the GoogleService-Info.plist config file, add your iOS app to Firebase by clicking on the "Add Firebase to your iOS app" and following the instructions.

 

In case your Firebase project already has the iOS app, go to the General tab in the Project Settings page and retrieve the config file, as shown in the image below.


Once the GoogleService-Info.plist config is downloaded, add it to your project root.

Step 3: Almost Done!

After performing the steps above, in order to get the server key, click the settings button, highlighted in red, followed by Project Settings.


Then look up the Legacy server key found in the Cloud Messaging tab, as presented below.


Add that key to the dashboard in the Developer Tools page.

You are now ready to receive your first notification through QuickSync!


Android

Add QuickSync to receive your notifications immediately. This uses Firebase Messaging and it dependents on Google Play Services. Make sure you already have integrated Plot using the Android integration guide.

Step 1: Add Firebase Messaging Dependency

Add a dependency on Firebase in your app-level gradle file. The download page shows with what version it has been tested. It is possible it won't work with newer major versions of Google Play Services.

dependencies {
  //ensure the version of the Firebase libraries are the same as of your Google Play Services dependency
  compile 'com.google.firebase:firebase-core:' + googlePlayVersion
  compile 'com.google.firebase:firebase-messaging:' + googlePlayVersion
}
Step 2: Add Services

Add a service registration to your manifest as shown in the snippet if you don't have Firebase Messaging integrated yet.

<service
		android:name="com.plotprojects.retail.android.QuickSyncFirebaseMessagingService">
		<intent-filter>
				<action android:name="com.google.firebase.MESSAGING_EVENT" />
		</intent-filter>
</service>

<service
		android:name="com.plotprojects.retail.android.QuickSyncFirebaseInstanceIdService">
		<intent-filter>
				<action android:name="com.google.firebase.INSTANCE_ID_EVENT" />
		</intent-filter>
</service>

When you have your own Firebase Messaging services inside your app, you can forward calls from these services to our library. The QuickSyncFirebaseInstanceIdService has the static method handleTokenRefresh(Context) for tokenRefresh events and the QuickSyncFirebaseMessagingService has the static method handleMessageReceived(Context, RemoteMessage) for messageReceived events.

Step 3: Setup a Firebase Project

Follow the steps at the Firebase Console to setup your project and make sure you enable cloud messaging for your project.

Step 4: Add Config File

To obtain the google-services.json config file, add your Android app to Firebase by clicking on the "Add Firebase to your Android app" and following the instructions.

In case your Firebase project already has the Android app, go to the General tab in the Project Settings page and retrieve the config file, as shown in the image below.

Once the google-services.json config is downloaded, add it into your project's module folder, typically app/.

Step 5: Almost done!

After performing the steps above, in order to get the server key, click the settings button, highlighted in red, followed by Project Settings.

Then look up the Legacy server key found in the Cloud Messaging tab of the Settings page, as presented below.

Add that code to the dashboard in the Developer Tools page.

You are now ready to receive your first notification through QuickSync!

Back To Top

2.10 Attribution - How to get started

Plot Projects already provides the possibility to analyze the location data of your users by using Geotrigger campaigns through the dashboard. Geotriggers are used for monitoring user behaviour in Geofence or Beacon regions e.g. time spent, number of visits, etc. With these campaigns we can effectively measure foot traffic at your locations.

In order to extend the possibilities provided by this type of campaigns and to further refine their usability, we have restructured the types of geotrigger campaigns we provide to Data campaigns which are distinguished in Listening campaigns and Attribution campaigns. Regular Notifications campaigns remain unchanged in terms of functionality.


Data Campaigns

Data campaigns is our new term to describe campaigns that are not used to show Notifications to the users' devices as opposed to Notification campaigns. They only gather insights concerning the user's location activity.

Data campaigns include two sub-types of campaigns. Those are Listening campaigns and Attribution campaigns.

Listening campaigns were called Geotrigger campaigns previously. Attribution campaigns are the new type of campaigns that will be described next in details.


Attribution campaigns in the Dashboard

Attribution campaigns can be used to measure the effectiveness of your online campaigns. This is done by linking actions done by the app's user to the actual user's location changes. For example, attributing a user's visit to a store to his action of seeing or opening a coupon in app.

In order to create an Attribution campaign in the dashboard, an attribution action need to be determined. This action can be the user reading a flyer or seeing a coupon inside the app, etc. This information is sent through our plugin so that it can be reported back to you. Please note that it is important to be consistent in naming the action in the dashboard and in your app so we advise you to do this in cooperation with your development team to make sure the correct user action is tracked.

In the "Create Attribution campaign" page in the dashboard, under "Attribution Campaign Options", you can set "Action name", "Item Identifier" and "Minimum dwell time to count as an Attribution". Action name and minimum dwell time are required fields while item identifier is optional. Item identifier refers to the exact item that is linked to the attribution, e.g. a flyer or coupon identifier.

An extra possibility offered by Attribution campaigns is that through these campaigns we can report based on the time the user spent in the geofence of interest. For instance, how long on average users stay in the store location.

Implementing Attribution Campaigns

We support attribution campaigns for geofences and beacons.

Both on iOS and on Android the Plot class has methods that allow sending attribution events. Below is an example snippet for each platform.

Example Android snippet:

Plot.sendAttributionEvent("read_flyer", "discounts_week_12");

Example iOS snippet:

[Plot sendAttributionEvent:"read_flyer" withItemId:"discounts_week_12"];

In the dashboard, in order to be able to report on the "discount_week_12" flyer, you will need to specify the same setting for action name and item identifier, as shown below.


Custom reporting

After creating Attribution campaigns, it is possible to set up the report deliveries in cooperation with your customer success manager. Reports can be delivered through the Custom Reports tab in the dashboard, Google Storage, Amazon S3 or to a BigQuery dataset.

Clients with a gold plan or higher have access to the Attribution campaigns feature through the dashboard. Contact your Customer Success Manager or Contact us via the contact form for more details.

Back To Top

3. Concepts

3.1 When to trigger notifications

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. 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. 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

3.2 Altering or canceling notifications on the device


Plot Projects offers 2 ways of segmentation: client side segmentation(with the Plot Projects NotificationFilter) and server side segmentation (with the Plot Projects Segmentation feature).

In case you're not sure wich one suits your business the most please feel free to contact us so we can explain you a bit more the difference between these two.

More information on server side segmentation can be found in paragraph 3.3 Segmenting notifications.

The rest of this paragraph is about client side segmentation.


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



Platforms:   iOS   Android  Appcelerator  PhoneGap


iOS

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 UNNotificationRequest.

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 (UNNotificationRequest* notification in notifications) {

        //alter notification
        //ensure the keys in the userInfo also present in the new object.
        NSString* customMessage = @"Custom message";
        UNMutableNotificationContent* customContent =  [[UNMutableNotificationContent alloc] init];
        customContent.body = customMessage;
        NSMutableDictionary* userInfo = [notification.content.userInfo mutableCopy];
        customContent.userInfo = userInfo;
        UNNotificationRequest* updatedNotification =  [UNNotificationRequest requestWithIdentifier:notification.identifier content:customContent trigger:notification.trigger];
        [updatedNotifications addObject: updatedNotification];
    }
    // Always call showNotifications at the end of the method
    [filterNotifications showNotifications:updatedNotifications];
}
//Example for plotFilterNotifications creating a rich notification:
    -(void)plotFilterNotifications:(PlotFilterNotifications*)filterNotifications {
    NSArray* notifications = filterNotifications.uiNotifications;
    for (UNNotificationRequest* notification in notifications) {

        NSURL *fileURL = ... //  your media item file url
        NSError *error;

        NSArray* attachments = [NSMutableArray array];
        UNNotificationAttachment *attachment = [UNNotificationAttachment attachmentWithIdentifier:@"attachment" URL:imageURL options:nil error:&error]

        // first create your custom content object as in the previous example...

        customContent.attachments = [attachments arrayByAddingObject:attachment];

        //...ensure you update the notification object with the new content as in the previous example
    }
    // Always call showNotifications at the end of the method
    [filterNotifications showNotifications:notifications];
}

You can change all fields of the PlotFilterNotifications 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. In order to implement rich notifications, you need to add each media item (UNNotificationAttachment) to the attachments array present in the UNMutableNotificationContent using the Notification Filter. Similarly to the rich content, to implement the Custom actions feature, you have to resort to the Notification Filter. This feature relies on two classes UNNotificationAction and UNNotificationCategory

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.


Android

Plot automatically detects whether a service is registered in AndroidManifest.xml that extends from the class NotificationFilterBroadcastReceiver. 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 NotificationFilterBroadcastReceiver {
    @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;
    }
}

And add this receiver to the manifest:

<receiver android:name=".MyNotificationFilterReceiver" android:exported="false">
            <intent-filter>
                <action android:name="${applicationId}.plot.FilterNotifications" />
            </intent-filter>
</receiver>

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.


Appcelerator

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);

Phonegap

You can see how to implement a notification filter for Phonegap/Cordova/Ionic at How to implement NotificationFilter and GeotriggerHandler for Phonegap/Cordova/Ionic .

Back To Top

3.3 Segmenting notifications


Plot Projects offers 2 ways of segmentation: client side segmentation(with the Plot Projects NotificationFilter) and server side segmentation (with the Plot Projects Segmentation feature).

In case you're not sure wich one suits your business the most please feel free to contact us so we can explain you a bit more the difference between these two.

More information on client side segmentation can be found in paragraph 3.2 Altering or canceling notifications on the device.

The rest of this paragraph is about client side 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.

The segmentation feature also allows you to distinguish the users in our custom reports, to set this you only need set the segmentation property inside your app.

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.

A segmentation property can only be set after Plot plugin starts.

Information on how to get started with segmentation is available in the Segmentation - How to get started.


Platforms:   iOS   Android  Appcelerator  PhoneGap


iOS


//    ---  After Plot.init has been executed  ---

// 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"];

A segmentation property can also be set to target specific users or to filter specific users data in our custom reports by providing the user id as a segmentation property.

//    ---  After Plot.init has been executed  ---

// Set the segment for an specific user id.
[Plot setStringSegmentationProperty:@"1234" forKey:@"user-id"];

Note: the segmentation key has a limit of 40 characters and the value of 40 characters


Android


//    ---  After Plot.init has been executed  ---

// 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);

A segmentation property can also be set to target specific users or to filter specific users data in our custom reports by providing the user id as a segmentation property.

//    ---  After Plot.init has been executed  ---

// Set the segment for an specific user id.
Plot.setStringSegmentationProperty("user-id", "1234")

Note: Any segmentation key has a limit of 40 characters and the value of 40 characters


Appcelerator

// 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());

Note: the segmentation key has a limit of 40 characters and the value of 40 characters. Calling Plot.init() is required before a segmentation property can be set.


Phonegap

// 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());

Note: the segmentation key has a limit of 40 characters and the value of 40 characters. Calling plot.init() is required before a segmentation property can be set.

Back To Top

3.4 Dealing with user tapping on notification


Platforms:   iOS   Android  Appcelerator  PhoneGap


iOS

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:(NSString*)data response:(UNNotificationResponse*)response is implemented, the default handler is replaced by this method which will then be called when a notification is opened.

Note: There is another method available which is: -(void)plotHandleNotification:(UNNotificationRequest*)notification data:(NSString*)action Which behaves the same as the previous one. You can use it in case you don't need access to UNNotificationResponse object.


Android

The default behavior when tapping a notification is opening a URI. If you want a different action, then you have to 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="com.example.MyNotificationOpenReceiver">
  <intent-filter>
    <action android:name="${applicationId}.plot.OpenNotification" />
  </intent-filter>
</receiver>

Appcelerator

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)

Phonegap

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

3.5 Notification analytics on the device

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).


Platforms:   iOS   Android


iOS

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
}

Android

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="${applicationId}.MyNotificationEventReceiver">
      <intent-filter>
          <action android:name="${applicationId}.plot.SentNotification" />
          <action android:name="${applicationId}.plot.OpenedNotification" />
      </intent-filter>
  </receiver>

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.6 Get loaded 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.

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


Platforms:   iOS   Android  Appcelerator  PhoneGap


iOS

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.


Android

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.


Appcelerator

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.

An example implementation would be:

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

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

Phonegap

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.

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

3.7 Get sent notifications

The library allows you to retrieve the sent notifications and 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.

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.


Platforms:   iOS   Android  Appcelerator  PhoneGap


iOS

The sent notifications and geotriggers can be retrieved using the method [Plot sentNotifications] for notifications and [Plot sentGeotriggers] for geotriggers.

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.


Android

The sent notifications and geotriggers can be retrieved using the method Plot.getSentNotifications() for notifications and Plot.getSentGeotriggers() for geotriggers.

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.


Appcelerator

The sent notifications and geotriggers can be retrieved using the method plot.getSentNotifications() for notifications and plot.getSentGeotriggers() for geotriggers.

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.


Phonegap

The sent notifications and geotriggers can be retrieved using the method plot.sentNotifications(resultCallback, errorCallback) for notifications and plot.sentGeotriggers(resultCallback, errorCallback) for geotriggers.

Back To Top

3.8 iBeacon


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.


Platforms:   iOS   Android  Appcelerator  PhoneGap


Characteristics

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

proximityUUID:This is the highest level identifier for beacons. You can specify up to 20 different identifiers per app in our Dashboard. We recommend setting this identifier to the same value for all beacons you own.
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 enter multiple proximityUUIDs in our dashboard, go to Locations and click on Beacon details. You can add new Beacon details there. 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 enter that by going to Locations and under Beacons tab. When creating a new beacon, you choose a proximityUUID from the ones created in the previous step, specify a majorId, radius and optionally a minorId.


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 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.


iOS

In iOS iBeacon support is enabled by default, no extra steps are needed


Android

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.


Appcelerator

Our Appcelerator Plugin supports iBeacons for both Android and iOS.


Phonegap

Our Phonegap Plugin supports iBeacons for both Android and iOS.

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.

Back To Top

3.9 Dealing with data campaigns

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.


Data Campaigns

Data campaigns is our new term to describe campaigns that are not used to show Notifications to the users’ devices as opposed to Notification campaigns. They only gather insights concerning the user’s location activity.

Data campaigns include two sub-types of campaigns. Those are Listening campaigns and Attribution campaigns.

Listening campaigns represent the previously called Geotrigger campaigns. More information about the Attribution campaigns can be found in the Attribution Campaign Guide.



Geotrigger handling


Platforms:   iOS   Android  Appcelerator  Phonegap

Note: It's important to keep in mind that on the device side all data campaigns notifications are called geotriggers.


iOS

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.


Android

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 GeotriggerHandlerBroadcastReceiver. 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 GeotriggerHandlerBroadcastReceiver {
    @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;
    }
}

And add this receiver to the manifest:

<receiver android:name=".MyGeotriggerHandlerReceiver" android:exported="false">
            <intent-filter>
                <action android:name="${applicationId}.plot.HandleGeotriggers" />
            </intent-filter>
</receiver>

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.


Appcelerator

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);

Phonegap

You can see how to implement a geotrigger handler for Phonegap/Cordova/Ionic at How to implement NotificationFilter and GeotriggerHandler for Phonegap/Cordova/Ionic .

Back To Top

3.10 Enabling/Disabling Plot

You have the possibility to control when to enable/disable the plot plugin. You can do this through the config file when the plot plugin is initialized or you can enable/disable it programmatically any time you want.


To do this through the config file you will use the property enableOnFirstRun. By default this option is set to true.

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

This way we do all the hard work for you, and all you have to do is start targeting your users. In case you set this to false, you can later enable it programmatically, but in this situation you will have to ask for location permissions yourself.


Regardless of setting enableOnFirstRun option, you can enable or disable the plot plugin programmatically any time you want. Keep in mind this setting is persistent between sessions.


Platforms:   iOS   Android  Appcelerator  PhoneGap


iOS

To enable plot:

[Plot enable]

To disable plot:

[Plot disable]

To check current status:

[Plot isEnabled]

Android

To enable plot:

Plot.enable()

To disable plot:

Plot.disable()

To check current status:

Plot.isEnabled()

Appcelerator

To enable plot:

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

To disable plot:

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

To check current status:

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

PhoneGap

To enable plot:

var plot = cordova.require("cordova/plugin/plot");
plot.enable()

To disable plot:

var plot = cordova.require("cordova/plugin/plot");
plot.disable()

To check current status:

var plot = cordova.require("cordova/plugin/plot");
plot.isEnabled()

Back To Top

3.11 Contextual Pages

Plot Projects offers the possibility to show location relevant content directly from your app. You can determine this content, which is specified by a string in the dashboard (could be an URL, Deeplink or any arbitrary string). You can define that string while setting up a Contextual Page campaign in the link field. You can retrieve this page at any time you find appropriate using a method provided in our SDK.

It's important to only use Contextual Pages in your app at logical times for the user. When the user opens the current screen via a deeplink, then changing the whole content of the current screen could lead to an unexpected user experience. A good example use case could be checking if there's a contextual page, at the user's location, every time the main page of your app is opened, in order to show a location relevant page, such as a nearby promotion or deal. Another possibility is to only update a part of the screen based on the user's location, for example to show the nearest store.

Platforms:   iOS   Android

iOS

After deciding when to show a Contextual Page, you invoke the method requestContextualPage. After calling the method and when his location matches one of the contextual pages defined in the dashboard, then the method's handler parameter value will be set to the string defined for that page in the link field of the campaign. Otherwise, the parameter is set to nil.

You should detect yourself whether this is a suitable time to show a contextual page. For example, you can pass context in the segue that you use for changing the view controller.

An example employment of the method used to request the current contextual page is:

[plot requestContextualPage:^(NSString *result) {
    if (result) {
        // Up to the developer to decide what to do with the result
        // It will be the same value defined in the dashboard in the link field of the campaign
    } else {
        // Up to the developer to decide what to do when there is no contextual page associated with the current location.
    }
}];

Android

After deciding when to show a Contextual Page, you invoke the method requestContextualPage. After calling the method and when his location matches one of the contextual pages defined in the dashboard, then the method's handler parameter value will be set to the string defined for that page in the link field of the campaign. Otherwise handleContextualPageNotFound() is invoked.

You should detect yourself whether this is a suitable time to show a contextual page. For example, you can pass context in the Intent that you use for changing the Activity.

An example employment of the method used to request the current contextual page is:

Plot.requestContextualPage(new RequestContextualPageCallback() {
    @Override
    public void handleContextualPageResponse(String contextualPageUrl) {
        // Up to the developer to decide what to do with the result
        // It will be the same value defined in the dashboard in the link field of the campaign
    }

    @Override
    public void handleContextualPageNotFound() {
        // Up to the developer to decide what to do when there is no contextual page associated with the current location.
    }
});

Back To Top

3.12 Sticky Notifications on Android

With each new Android version it becomes increasingly hard to get background execution time. This is specially noticeable in the latest versions of Android when requesting for network activity while the app is in the background. Considering the facts mentioned above and the nature of our SDK, at Plot Projects we research and devise solutions that help us minimize the effect of these restrictions on the overall performance of the product.

The latest Plot Projects 3.X SDK was developed to reduce the dependence to an internet connection, as it does not require constant network activity for the triggering or refreshing of campaigns. However to send newly created/edited campaigns to the device and to share statistics, a periodic update is required and those fail more often nowadays due to the Android's strict restrictions.

This situation can be countered by using a sticky notification, commonly known as Foreground Service. This notification is shown only when updating campaigns in the background, as Android recognizes it as foreground execution and doesn't block the network activity. This process takes a few seconds and will only occur 1-2 times a day. By default this notification shows the icon, the name of the app and a short description. The default description is "Updating app content…", but that text can be altered in the config file. The figure below portrays an example manifestation of this feature.

This feature is available and enabled by default from the SDK's 3.3.0 release. Note that disabling this feature can affect the performance and efficiency of the product.

You can read more about this feature in the chapter regarding the Config File. Where you'll find how to disable this feature or define the message displayed in the notification. Optionally, you can also use the Config Hook to set these properties.

Back To Top

4. Test guide

4.1 Receiving of notifications test


Platforms:   iOS   Android


After completing the basic integration of the Plot Projects SDK you need to test it. You verify whether the Plot plugin is integrated properly by receiving a location based notification. When you have receive a notification, you know the basic integration is successful.

How to test the basic integration of the Plot Projects iOS SDK in your app:


iOS

  1. Ensure your test app is connected to your sandbox environment in Plot Projects to prevent your end-users from receiving test notifications. If you don't have a Sandbox environment yet, you can create one by clicking on your app in the Plot Dashboard > Manage apps and plans > Create new app.
  2. Install your app on your phone. If it is already installed, then remove the app and reinstall it, so you can start from a clean slate.
  3. Log in into the Plot Projects dashboard
  4. When in your Sandbox app, go to the Notification Campaigns screen by clicking on the corresponding menu item. At the bottom right, you can create a new Notification Campaign.
  5. Give the campaign a name and a message. You can ignore the fields on the Advanced Settings screen.
  6. Select the action "Open app". If you don't have a geofence yet at your location, you can create one now on this screen. Place the geofence at the location where you're currently are. The geofence radius should be kept at 200 meters.
  7. Select in the "Users should receive notifications" section the option "More than once" and save your campaign.
  8. Note that you don't receive this notification on your device immediately. The Plot Projects SDK only connects to our backend periodically to update its cached campaigns. Every few hours or when the device has moved significantly. Opening or closing the app in this period doesn't influence this. hen a new notification has been added it takes a while before that notification is downloaded and can be received by you. If you don't want to wait this long you have the following options:
    • You can set up the Plot Projects feature Quicksync, which allows you to instantly send new campaigns to all your app users. See our Quicksync integration guide how to set this up.
    • Turn on and off flight mode. Note that, this workaround only works once per 10 minutes.
    • Reinstall the app
  9. If you did not receive your test notification please use this checklist.

Notice: When a notification has been received, it won't be resent until you properly leave the geofence and re-enter it. Reinstalling the app allows you to receive a notification again.


Android

  1. In your application's code, ensure the "debug" property is set to true, as it allows the plugin to show what is happening. The following code snippet shows an example of how to do that. All you need to add the second line to your plotconfig.json file:
    {
      "publicToken": "YOUR_TOKEN",
      "debug": true,
      "automaticallyAskLocationPermission": true,
      "enableOnFirstRun": true
    }
  2. Ensure your test app is connected to your sandbox environment in Plot Projects to prevent your end-users from receiving test notifications. If you don't have a Sandbox environment yet, you can create one by clicking on your app in the Plot Dashboard > Manage apps and plans > Create new app.
  3. Install your app on your phone. If it is already installed, then remove the app and reinstall it, so you can start from a clean slate.
  4. Log in to the Plot Projects dashboard
  5. When in your Sandbox app, go to the Notification Campaigns screen by clicking on the corresponding menu item. At the bottom right, you can create a new Notification Campaign.
  6. Give the campaign a name and a message. You can ignore the fields on the Advanced Settings screen.
  7. Select the action "Open app". If you don't have a geofence yet at your location, you can create one now on this screen. Place the geofence at the location where you're currently are. The geofence radius should be kept at 200 meters.
  8. Select in the "Users should receive notifications" section the option "More than once" and save your campaign.
  9. Note that you will NOT receive this notification on your device immediately. The Plot Projects SDK only connects to our backend periodically (every 2 hours or when the device has moved significantly) to update its cached campaigns. This isn't influenced by whether the app has been opened or closed in this period. Therefore, when a new notification has been added it may take a while before that notification is downloaded and may be received by you. If you don't want to wait this long you have a couple of options:
    1. You can trigger a backend call by clearing the local database of your app on your phone. To clear the local database you have to open the Apps section under settings on your phone/emulator and find your app. There you can stop the app and clear local data under storage section. When the app is then opened again it will directly start downloading the notifications and, when you are at the right location of course, show the notifications. The following screenshots illustrate how to achieve that:
    2. You can set up the Plot Projects feature Quicksync, allowing you to instantly send new campaigns to all your app users (see our Quicksync integration guide).
  10. If you didn't receive your test notification after a couple minutes you can use this checklist.

Notice: When a notification has been received, it won't be sent again until you leave the geofence. Cleaning the local database will make it possible to receive a notification again. This can make testing easier.

 

Back To Top

4.2 Debug mode and log messages


Platforms:   iOS   Android   Cordova/Phonegap


iOS

To aid you in debugging, Plot provides diagnostic messages in the console. These messages are only enabled when Plot is compiled with a debug configuration. The messages show which notifications were considered for showing and how far Plot thinks you are from these notifications. This makes it clearer why a notification has been or hasn't been shown.

XCode's console shows these debugging messages.

Example debug log output

When enabling Plot you see the following log message

2017-09-18 16:34:51.460 - Plot enabled

After the Plot plugin is enabled, it downloads the notifications from the server. It shows the total number of notifications and the notifications that have been loaded. You can use the following message to ensure the right notifications are loaded.

2017-09-18 16:34:54.349 - Loaded new notifications (1 total)
2017-09-18 16:34:54.349 - Notification: a9f242b4be384923896168dc2c134585 - Wiki Notificati...

Once the notifications are loaded, Plot matches these. It shows the loaded notifications and the distance to these notifications in meters. Where the distance is smaller than the match range, a notification "matches" and is sent to the notification filter or geotrigger handler (if you have one or both defined) so that it's processed by the logic that you defined.

2017-09-18 16:34:54.383 - Distance to a9f242b4be384923896168dc2c134585 - Wiki Notificati...: 4018 (range: 200)

When there is at least one notification or geotrigger sent to the notification filter/geotrigger handler, then you see the following line with the number of matching notifications. The example below uses a geotrigger handler. When you don't have a notification filter/geotrigger handler, this step is skipped.

2017-09-18 11:27:25.086 - Offered geotriggers to the geotrigger handler (1 total)

Once notification filter/geotrigger handler completes, then the following log message appears. It shows how many notifications passed through the notification filter and then shows these notifications. These notifications should then appear in the notification area.

2017-09-18 11:27:25.096 - Geotrigger handler completed (1 passed)
2017-09-18 11:27:25.187 - handled: 3fda60abc4fa4472986fb5e108989991;a01a770391134f55be0ce90b88dc13f2 - Plot..

The debug output also includes useful info about:

When the plugin detects a new updates

2017-09-18 17:54:55 - Acquired location: 52.344271,4.916536 (accuracy 65 meter)

Notifications loaded through QuickSync (Integration guide), denoted by the keywords "from push"

2017-09-18 18:00:08 - Loaded new notifications from push (6 total)

Shown notifications

2017-09-18 17:12:48 - Showing notification: da13094b56d0482298d5fba912ad8cbd - Welcome

Sent geotriggers

2017-09-18 17:12:48 - Geotrigger sent: 605ef54c3dd94a3bb87cee0c4d70df98;27d74b87987943d1b93d4dea3ad04081 - test geotrigger...

Region status, e.g "User first has to leave area", which means that to trigger the region the user has to leave and reenter the area, or "Dwell initiated", which means that the dwell timer has started

2017-09-18 17:54:55 - User first has to leave area of 9dee12a6151f4297b366fd82161e1f00;41b1ce9a9f2140ce9512f03b4fafc04b - test

 


Android

Notice: You need to turn off debug before submitting to app store by setting "debug": false in your plotconfig.json

The Plot plugin provides log messages to help you diagnose situations where no notification is shown. For example, it helps you distinguish between situations where either our library thinks it isn't close enough to a location or the notification filter dropped the notification.

Since version 2.x, in order for Plot plugin to log these messages, you have to enable debug mode. That is done by setting debug to true in plotconfig.json. Notice the last line of the following code snippet:

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

The messages are then sent to LogCat. Most IDEs show these messages directly from there.

When enabling Plot you see the following log message:

10-04 10:53:27.362 5834-6480/com.example D/Plot/SettingsService: Enabling Plot plugin.

After the Plot plugin is enabled, it downloads the notifications from the server. It shows the total number of notifications and the notifications that have been loaded. You can use the following message to ensure the right notifications are loaded.

10-04 10:53:34.673 5834-6480/com.example D/Plot/BasicNotificationService: Received 39 notifications.

10-04 10:53:36.411 5834-6480/com.example D/Plot/BasicNotificationService: Loaded Notification{id='9f82ae0ad3b94a498bdbfb9f163d75a4',
    location=Location{latitude=52.373150255778086, longitude=4.905467582617121}, message='...', timespans=[], data='...', matchRange='4520', triggerOnExit='false',
    dwellingMinutes='0', cooldownGroups=[Cooldown{cooldownSeconds=1, groupName='9f82ae0ad3b94a498bdbfb9f163d75a4'}], landingPageNotification='false', geotrigger='false',
    isAppLinkNotification='false', segmentationIds='[]', segmentationProperties='[]'}

Once the notifications are loaded, Plot matches these. It shows the loaded notifications that and the distance to these notifications in meters. Where the distance is smaller than the match range, a notification "matches" and is sent to the notification filter (if you have one defined).

10-04 10:53:36.590 5834-6480/com.example D/Plot/GeofenceMatching: Checking for geofence matches.

10-04 10:53:36.693 5834-6480/com.example D/Plot/GeofenceMatching: Distance to 37939d977fa744339bcfbb1de5833b37;cbf373cfa41248ee837799099f5c99c0: 43 (match range: 200)

When there is at least one notification sent to the notification filter, then you see the following two lines. First the number of matching notifications, followed by details about these notifications. When you don't have a notification filter, then this step is skipped.

10-04 10:53:37.569 5834-6643/com.example D/Plot/NotificationFilterUtil: Received 1 notifications for filtering

10-04 10:53:37.578 5834-6643/com.example D/Plot/NotificationFilterUtil: FilterableNotification(id = 471b01eb41af436f9cb38196936a727c;41b1ce9a9f2140ce9512f03b4fafc04b, matchId = 82086267-d4b1-4eea-972c-95a841ffb3a2, message = 15/9 13:55 test quicksync, data = , notification = null, trigger = enter)

Once the notification filter completes, the following log message appears. It shows how many notifications passed through the notification filter and then shows them. These notifications then appear in the notification area.

10-04 10:53:37.669 5834-6643/com.example D/Plot/NotificationFilterUtil: 1 notifications passed

10-04 10:53:37.674 5834-6643/com.example D/Plot/NotificationFilterUtil: FilterableNotification(id = 471b01eb41af436f9cb38196936a727c;41b1ce9a9f2140ce9512f03b4fafc04b, matchId = 82086267-d4b1-4eea-972c-95a841ffb3a2, message = Wednesday: 15/9 13:55 test quicksync, data = , notification = null, trigger = enter)

 


Cordova/Phonegap

To enable debug logging on the iOS platform, you have to add a parameter to your project settings on XCode. Add DEBUG=1 to your Build Settings -> Project Preprocessor Macros in XCode. The following screenshot demonstrates where this parameter should be added:

 

Back To Top

4.3 Retrieve notification status from plugin


Platforms:   Android


Android

As the plugin runs in the background, it is sometimes hard to see why the plugin doesn't send a notification. Starting from version 3.1 the Android plugin provides a screen that shows the nearest notifications and their current status. You can use this inside our demo app and you can add the functionality to your own app. At the moment this functionality is only available for Android.

Using the demo app

The easiest way to see this debug screen is to use our demo app. Then no developer has to integrate the screen into an existing app. To get started, download the Android Demo app. On the top of the screen, you open the tab "Status".

Integrating into your own app

Besides from using this from our demo app, you can integrate this overview into your app to aid debugging. You have the simple option to show an Activity and the more advanced option to integrate a fragment into an existing activity. The functionality only works when the debug property is set to true in plotconfig.json.

Showing the Activity is the simplest and is done like this:

Intent consoleActivityIntent = new Intent(context, ConsoleActivity.class);
context.startActivity(consoleActivityIntent)

If you want to integrate this into an existing screen, you can also use a fragment. It comes in two flavors:

  • com.plotprojects.retail.android.ConsoleFragment: Extends the Support Fragment class.
  • com.plotprojects.retail.android.ConsoleFragment.NativeFragment: Extends the native Fragment class.
Possible notification statuses

The screen shows the details of the last execution and a list of the nearest notifications sorted on distance.

For the details of the last execution it shows the following properties:

  • Last Geofence check: Last time the plugin searched for nearby geofences.
  • Last Beacon check: Last time the plugin searched for nearby beacons.
  • Last location: The coordinates of the last reported location.
  • Last location accuracy: The accuracy of the last reported location.
  • Last full update: Last time all geofences/beacon/campaigns inside a large area were updated.
  • Last quick update: Last time the geofences/beacon/campaigns inside a small area were updated.

For each notification it shows the following properties:

  • Distance to edge: The distance in meters the device thinks you currently are away from the edge of the geofence.
  • Region Type: Whether it is a geofence or beacon notification.
  • Trigger type: Whether the notification shows the user enters or exits the geofence.
  • Notification Message: The message of the notification.
  • Last received: The last time the notification was shown.
  • Notification status: When the notification isn't sent, then it shows the reason here.


If no notifications can be loaded, then it prints the reason why this happened. Possible reasons include: "No internet connection", "The location of the device cannot be determined" or "No campaigns are active".

Back To Top

4.4 Sending the debug log


Platforms:   iOS   Android   Cordova/Phonegap


iOS

You might need to mail the debug log to yourself. With Plot all you have to do is call Plot's provided method, e.g. after a button click event.

Objective-C:

(void)mailDebugLog:(UIViewController*)viewController

Swift:

func mailDebugLog(UIViewController:viewController)

The method will start your mail client so you can send the debug log (a log file generated by plot) to yourself or your nearest developer. Note: this method should only be used when compiling for DEBUG. An example of this can be seen in our demo apps, which you can download from our dashboard.

 


Android

To read the log, you can mail the debug log to yourself. With Plot all you have to do is call Plot.mailDebugLog() in your app, e.g. after a button click event. The method will start your mail client so you can send the debug log to yourself or your another developer. An example of this can be seen in our demo apps, which you can download from our dashboard.

 


Cordova/Phonegap

You might need to mail the debug log to yourself. With Plot all you have to do is call Plot's provided method, e.g. after a button click event.

The following snippet:

plot.mailDebugLog(function() {
    console.log("success");
}, function(e) {
    console.log("error: " + e);
});

 

Back To Top

4.5 Location testing using a simulator/emulator


Platforms:   iOS   Android


iOS

Location testing is essential when working with any location based technology and Plot is no exception, however moving to a physical location is not always possible or practical. To deal with this, XCode's device simulator (Getting Started in Simulator) provides a way to emulate a current location. To change a device's current location, click on the custom location option in the Simulator's debug menu as presented in the image below:

After clicking, a window will popup that allows you to input the coordinates of your testing location. The app now behaves as if you were at that specified location and the notifications that you set up previously triggers.

To ensure correct workings of the iOS plugin, if you travel for a distance of more than 10 km / 6 miles make sure the speed during the test is less than 130 km/h / 80 mph. Otherwise, the plugin may not load the notifications in time.

 


Android

Since version 2.4, Plot plugin supports two ways of location testing on an emulator. The first method is to enable the emulator testing mode and the second option is to use the Plot.testLocation() method to set an explicit location.

When enabling the emulator testing mode the plugin checks the location more frequent than it normally would and it starts using the GPS location provider. The reason for this is that the emulator forwards the virtual location as a GPS location. When setting emulatorTesting to true in the plotconfig.json, the plugin increases the battery usage significantly. Make sure you disable it before submitting to App Store.

In order to use an emulator, you need to set the following properties in plotconfig.json file:

"debug": true,
"emulatorTesting": true

Emulator testing is only enabled when debug is set to true. Otherwise, it is ignored.

After setting the previous properties, you use Android emulator location settings to change your location. To access the location screen, first you click on the three dots as shown in the following picture:

Then set the testing location as shown below. The part within the red rectangle is where you set the test location.

To ensure correct workings of the Android plugin, if you travel for a distance of more than 10 km / 6 miles make sure the speed during the test is less than 130 km/h / 80 mph. Otherwise, the plugin may not load the notifications in time.

 

Back To Top

4.6 Mocking your location


Platforms:   Android


Android

Another option is to change the location for testing purpose programmatically. For this, the plugin has the following method:

Plot.testLocation() takes either a combination of latitude and longitude, or a Location object.

Changing location using the testLocation method is only available in debug mode. You need to set

"debug": true

in plotconfig.json before you can use that method. You also need to call it, after Plot plugin is initialized.

To ensure correct workings of the Android plugin, if you travel for a distance of more than 10 km / 6 miles make sure the speed during the test is less than 130 km/h / 80 mph. Otherwise, the plugin may not load the notifications in time.

 

Back To Top

4.7 Test energy efficiency


Platforms:   iOS


iOS

Because Plot keeps receiving the location of your device in the background you must ensure that your application stops doing work in the background. Tasks you need to look out for are timers that are scheduled repeatedly and subscriptions on location services.

Before you start a task ensure that your application is in the foreground. Note, when your app starts it may stay in the background. Don't assume it directly moves to the foreground. To check that your app is in the foreground, or your app starts and will move to the foreground can be done with: application.applicationState != UIApplicationStateBackground. IOS provides notifications which inform you when the app moves to the background, so you can pause the tasks when the app transitions to the background. There's another notification that informs when the application moves back to the foreground.

[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(applicationWillResignActive)
                                             name:UIApplicationWillResignActiveNotification
                                           object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(applicationWillEnterForeground)
                                             name:UIApplicationWillEnterForegroundNotification
                                           object:nil];

When your app makes use of MKMapView in a view that is directly loaded when your app starts and has the option "Shows User Location" enabled, then your app starts using GPS when it starts. Even when it starts in the background. You need to enable that option programmatically after the view did appear instead of directly when the view loads.

XCode comes with a tool called Instruments that shows multiple metrics related to power usage. Instruments can be found in the XCode menu behind "Open Developer Tool". The tool you need here is "Energy Log".

It shows among other things how much of the CPU it utilizes and whether GPS is enabled. Keeping GPS enabled in the background really reduces battery life.

An important use case to test is what happens when your application starts in the background. The easiest way to trigger this is to start your app, allow location services and then restart your iPhone. Your app then starts with Plot in the background.

 

Back To Top

4.8 Most common issues


Here you can track the most common issues that our users encounter when integrating out plugin.


1. Did you receive a notification when using the demo app? If not, see the Demo App checklist.

2. Did you do all the steps in the Android integration guide or iOS integration guide correctly?

3. Did you use the most recent version of our plugin?

4. Is plotconfig.json correctly added? An example of this file can be seen at the Developer Tools in our dashboard.

5. Did you set the public token (not the demo token!) inside the plotconfig.json? The public token can also be found on the dashboard.

6. Does your app use its own notification filter? Are you sure the implementation is correct? You could try removing the filter to verify that the notification is not filtered out.

7. You can check the debug log, which can be sent from the demo app. This is also possible from the plugin, see this blog post.

8. In case you are still not receiving a notification, you could try to uninstall and reinstall the app.

Back To Top

4.9 Demo app


Here you can track the most common issues that our users encounter when testing with our demo app.

Platforms:   iOS   Android


iOS

Check these points when you are not receiving your notification on the iOS Demo App.

1. Did you create a geofence and a notification on your current location? This can be done in our dashboard. Make sure to set the range of the geofence large enough (> 200m for testing purposes).

2. It can take some time before the demo app on your device is synchronized with our server. To quickly sync your device you could reinstall the app as it will force a sync. After a reinstall the app has to be opened. If you are in the geofence and still want to receive a notification you have to bring the app to the background immediately after opting in to location services.

3. If you are already in the geofence and have the app in the foreground, you won't receive a notification, but it will show up in the notification tab of the demo app itself. If you want to see the notification in the iOS Notification Center, bring the app to the background straight after opting in.

4. Is the notification enabled? When the notification is set to paused it cannot be received.

5. Make sure it doesn't have opening hours or timespans. You can let the notification trigger anytime by setting "Notification can be triggered at the following times:" to "any time" in the advanced settings of your campaign.

6. Did you set the demo token correctly? It is the 6 digits number that was displayed to you after signing up. If you missed that, you can retrieve it from the developer tools tab of your dashboard. You can set the token in the Settings tab of the Plot Projects app and then click on Connect to account. Once you've entered the demo token the demo app will remember the token.

7. Do you have location services on for the demo app? This can be done in two ways; You will be prompted to enable this after filling in your token, or you can set it at Settings > Plot Projects > Location > Always

8. Are location services enabled on the device? You can set it at Settings > Privacy > Location Services. There you can set Location Services to On.

9. Do you allow our app to send you notifications? This can be done in two ways; You will be prompted to allow this after filling in your token, or you can set it at Settings > Plot Projects > Notifications > Allow

10. Do you have an internet connection? In order to load your notifications and geofences the demo app requires a working internet connection. A continuous internet connection also improves location accuracy.

11. Is WIFI enabled? Although no WIFI connection is required, it improves location detecting accuracy.

12. Did you already receive the notification before? Make sure the notification is set to be received more than once in the campaign settings in the dashboard.

13. Is there an app cooldown specified? When there is a cooldown specified in our dashboard for your app then the Plot plugin won't sent more than one message during the specified period. Set the minimum time to "upon re-entering" to remove any cooldown.

14. Have you stayed at the same location for a long time? The Plot plugin works best when moving at slower speeds. To optimize for battery efficiency it is possible you don't receive a notification when driving a vehicle or staying for a longer period on the same location.

15. Is the notification you are not receiving an beacon notification? Please make sure you have turned bluetooth on.

16. Still didn't receive your notification? You can find more detailed information in the log file. You can mail the log file by pressing "Mail log" in the Settings tab.


Android

Check these points when you are not receiving your notification on the Android Demo App.

1. Did you create a geofence and a notification on your current location? This can be done in our dashboard. Make sure to set the range of the geofence large enough (> 200m for testing purposes).

2. It can take some time before the demo app on your device is synchronized with our server. To quickly sync your device you could reinstall the app as it will force a sync. After a reinstall the app has to be opened. If you are in the geofence and still want to receive a notification you have to bring the app to the background immediately after opting in to location services.

3. Is the notification enabled? When the notification is set to paused it cannot be received.

4. Make sure it doesn't have opening hours or timespans. You can let the notification trigger anytime by setting "Notification can be triggered at the following times:" to "any time" in the advanced settings of your campaign.

5. Did you set the demo token correctly? It is the 6 digits number that was displayed to you after signing up. If you missed that, you can retrieve it from the developer tools tab of your dashboard.You can set the token in the Settings tab of the Plot Projects app and then click on Connect to account. Once you've entered the demo token the demo app will remember the token.

6. Have you turned on location services? You can usually set this at Settings > More > Location services. The mode should be High Accuracy or Battery saving.

7. Do you have an internet connection? In order to load your notifications and geofences the demo app requires a working internet connection. A continuous internet connection also improves location accuracy.

8. Is WIFI enabled? Although no WIFI connection is required, it improves location detecting accuracy.

9. Did you already receive the notification before? Make sure the notification is set to be received more than once in the campaign settings in the dashboard.

10. Is there an app cooldown specified? When there is a cooldown specified in our dashboard for your app then the Plot plugin won't sent more than one message during the specified period. Set the minimum time to "upon re-entering" to remove any cooldown.

11. Have you stayed at the same location for a long time? The Plot plugin works best when moving at slower speeds. To optimize for battery efficiency it is possible you don't receive a notification when driving a vehicle or staying for a longer period on the same location.

12. Is the notification you are not receiving a beacon notification? Please make sure you have turned bluetooth on.

13. Still didn't receive your notification? You can find more detailed information in the log file. You can mail the log file by pressing "Mail log" in the Settings tab.


Back To Top

4.10 Notifications troubleshooting


Here you can track the most common issues that our users encounter when testing with our demo app.

Check the following points when you are not receiving your notification on your own app with Plot integrated.

Platforms:   iOS   Android


iOS

Did you receive a notification when using the demo app? If not, see the iOS Demo App checklist.

Did you do all the steps in the iOS integration guide correctly?

Did you use the most recent version of our plugin?

Is plotconfig.json correctly added? An example of this file can be seen at the Developer Tools in our dashboard.

Did you set the public token (not the demo token!) inside the plotconfig.json? The public token can also be found on the dashboard.

When the app is in the foreground the notification doesn't appear in the notification center, but is directly opened by the app.

Does your app use its own notification filter? Are you sure the implementation is correct? You could try removing the filter to verify that the notification is not filtered out.

You can check the debug log, which can be sent from the demo app. This is also possible from the plugin, see this blog post.

In case you are still not receiving a notification, you could try to uninstall and reinstall the app.


Android

Did you receive a notification when using the demo app? If not, see the Android Demo App checklist.

Did you do all the steps in the Android integration guide correctly?

Did you use the most recent version of our plugin?

Is plotconfig.json correctly added? An example of this file can be seen at the Developer Tools in our dashboard.

Did you set the public token (not the demo token!) inside the plotconfig.json? The public token can also be found on the dashboard.

Does your app use its own notification filter? Are you sure the implementation is correct? You could try removing the filter to verify that the notification is not filtered out.

You can check the debug log, which can be sent from the demo app. This is also possible from the plugin, see this blog post.

In case you are still not receiving a notification, you could try to uninstall and reinstall the app.


If you are still not receiving any notifications, please check our documentation or contact us through the dashboard. Please have your log file ready.

Back To Top

5. Reference

5.1 Config 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
}

Platforms:   iOS   Android


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 maximum 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.

Since plugin version 2.0.0, it is possible to disable the automatic location services opt-in dialog that is shown. Set automaticallyAskLocationPermission to false to disable this opt-in dialog.

Since the plugin version 2.3.0 we support Provisional Authorization for notifications, a feature that was introduced with iOS 12. In order to enable this feature, the provisionalNotificationPermission setting needs to be paired with automaticallyAskLocationPermission also set to true

The option provisionalNotificationPermission requires automaticallyAskLocationPermission to also be set to true. When provisionalNotificationPermission is set to true and automaticallyAskLocationPermission is set to false (or not present), the plugin will default to the automatic location services opt-in dialog (as if automaticallyAskLocationPermission was set to true and provisionalNotificationPermission to false.

An example plotconfig.json could look like this:

{
  "publicToken": "REPLACE_ME",
  "enableOnFirstRun": true,
  "maxRegionsMonitored": 10,
  "automaticallyAskLocationPermission": true
  "provisionalNotificationPermission": 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 2.1.0, it is possible to disable the automatic location services opt-in dialog that is shown. Set automaticallyAskLocationPermission to false to disable this opt-in dialog.

Since plugin version 1.11.1 you can customize the behavior 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. When automaticallyAskLocationPermission is set to false, this option doesn't do anything.

Since plugin version 2.5.1, it is possible to add your main activity to the back stack when opening a notification with a deeplink (this is the default behaviour in previous versions). After being redirected to the deeplink activity, when the user presses the back button your app's main activity will be shown. To do this you need to set the addMainActivityToBackStack flag to true, by default this option is false.

Since plugin version 3.3.0, the SDK uses Sticky Notifications by default. You can configure these with the options showOnGoingNotification and onGoingNotificationText. By default the option showOnGoingNotification is set to during_network_request, which displays a sticky notification when there's network activity, namely for loading/updating campaigns and sending statistics. In case you don't want the sticky notification to be shown, set showOnGoingNotification to never. The option onGoingNotificationText allows you to define the text displayed in the sticky notification. When not specified the default message that is used is "Updating app content…".

An example plotconfig.json could look like this:

{
  "publicToken": "REPLACE_ME",
  "enableOnFirstRun": true,
  "notificationSmallIcon": "ic_mood_white_24dp",
  "notificationAccentColor": "#01579B",
  "automaticallyAskLocationPermission": true,
  "askPermissionAgainAfterDays": 3,
  "showOnGoingNotification": "during_network_request",
  "onGoingNotificationText": "Updating app content…"
}

Programmatic configuration

When you want to use another mechanism for specifying the configuration, then you can use the configuration hook. A use cases for this functionality is to load the config using your own configuration mechanism, for example when shipping the Plot Plugin as part of another library.

This feature is only available for the native plugin, not for Phonegap, Appcelerator Titanium or Xamarin. It requires at least version 2.1.0 for iOS or version 2.5.0 for Android. More information in Configuration Hook (iOS) or Configuration Hook (Android).

Back To Top

5.2 Configuration hook

It's possible to set or alter the Plot Plugin configuration programmatically by specifying a configuration hook. By default, the configuration for the Plot Plugin is set by adding a plotconfig.json to your project, as explained on the integration guides. A use cases for this functionality is to load the config using your own configuration mechanism, instead of specifying it in the plotconfig.json file.


Platforms:   iOS   Android


iOS

Plot calls the plotLoadConfig:originalConfig loadWithConfig:loadWithConfig method after your code calls [Plot initializeWithLaunchOptions:delegate:]. The values of originalConfig are loaded from the plotconfig.json file, if present. Otherwise, it uses the default values. This means when specifying a property in both the plotconfig.json file and the configuration hook, the configuration hook will override the configurations set in the plotconfig.json. The callback function must be called exactly once.

A configuration hook could like this:

//define the method as a member of PlotDelegate
-(void)plotLoadConfig:(PlotConfiguration *)originalConfig
       loadWithConfig:(void (^)(PlotConfiguration *))loadWithConfig {
    originalConfig.publicToken = @"newToken";
    loadWithConfig(originalConfig);
}

Android

Plot calls the loadConfig(PlotConfiguration originalConfig, LoadConfigCallback loadConfigCallback) method after your code calls Plot.init(). The values of originalConfig are loaded from the plotconfig.json file, if present. Otherwise, it uses the default values. This means when specifying a property in both the plotconfig.json file and the configuration hook, the configuration hook will override the configurations set in the plotconfig.json. The callback function must be called exactly once.

A configuration hook could like this:

public class MyConfigHook extends ConfigHookBroadcastReceiver {
    @Override
    public void loadConfig(PlotConfiguration originalConfig, LoadConfigCallback loadConfigCallback) {
            PlotConfiguration newConfig = originalConfig;
            newConfig.setPublicToken("NewToken");
            loadConfigCallback.loadWithConfig(newConfig);
    }
}

Back To Top

5.3 Download page


You can find our plugins available for download here.

Back To Top

5.4 Android - Upgrading from version 2.x to 3.x

In many cases just updating the library version from 2.x to 3.x is enough to upgrade your plugin. There are a few small breaking changes. Those are listed below.

Removed Geotrigger Handler and Notification Filter Services

Starting from Plot Projects Android SDK 2.4.0 we deprecated the following classes, due to the deprecation for background services in Android Oreo. In 3.x the deprecated classes are removed completely. We provide as replacement classes based on BroadcastReceivers.
  • NotificationFilterReceiver (replaced by NotificationFilterBroadcastReceiver)
  • GeotriggerHandlerReceiver (replaced by GeotriggerHandlerBroadcastReceiver)
For more information, see the migration guide for 2.4.

Removed deprecated configuration features

Support for setting the cooldown inside the plugin is removed. You can set the app-wide cooldown in the dashboard. Therefore the following methods are removed:
  • PlotConfiguration.getCooldownPeriod()
  • PlotConfiguration.setCooldownPeriod()
The method PlotConfiguration.getPublicKey() was deprecated in 2.x and is now completely removed. In 2.x it was an alias for PlotConfiguration.getPublicToken().

Split campaignId and regionId into separate fields

The constructors of the following class changed to be initialized with a campaignId and a regionId, instead of a combined notificationId. The method getId() is still available and supported.
  • FilterableNotification
  • Geotrigger

Other removed classes

The following classes were needed to provide QuickSync support via Google Cloud Messaging. This functionality is altered to use Firebase Cloud Messaging.
  • SyncGcmListenerService
  • SyncInstanceIDListenerService
The class MockedLocation was accidentally made public and is therefore removed. It doesn’t provide any functionality.

You can find all versions of the Android Plugin at our download page. The necessary steps to integrate the Plot plugin can be found in the Android integration guide.

Back To Top

5.5 iOS - Upgrading from version 1.x to 2.x

We have updated our plugin to follow the changes made in iOS. Apple deprecated UILocalNotification in favor of UNUserNotificationCenter. Plot Projects no longer makes use of the UILocalNotification.

A change of behaviour in the library is that notifications are now shown to the user when the app is already in the foreground. In version 1.x the notification would be opened straight away without showing it to the user.


Changes to Project settings

Our library now also depends on the UserNotifications.framework, provided by iOS. When using CocoaPods, this dependency is automatically added, so no extra steps are required. Otherwise, you have to add this dependency yourself in the Build Phases screen.

The minimum supported iOS of 2.x is iOS 10. When you want to target iOS 11 features, it is required to make use of this version of our library.

Ensure that all permission description info keys are defined. You can set those in your XCode project settings. You can find them in at the "Custom iOS Target Properties" under the "Info" tab of your build target. The required for iOS 10 and iOS 11 are:

Required Key Description shown in XCode
NSLocationAlwaysUsageDescription Privacy - Location Always Usage Description
NSLocationWhenInUsageUsageDescription Privacy - Location When In Usage Usage Description
NSLocationAlwaysAndWhenInUsageUsageDescription* Privacy - Location Always And When In Usage Usage Description

* this key is added in XCode 9. If you're using XCode 8, you can add the key yourself.


Changes to the AppDelegate

You must still call the initializeWithLaunchOptions: method of the Plot library in the didFinishLaunchingWithOptions method. When your app has its own NotificationCenterDelegate, you must register that one before initializing the Plot Projects plugin.

The method didReceiveLocalNotification: and the corresponding call to [Plot handleNotification:] is no longer required and should be removed.


Changes to Plot classes and the PlotDelegate

You can find the methods for the notification filter, notification handler and geotrigger handler in the PlotDelegate protocol.

The method names in the Plot class and the PlotDelegate stayed the same, but the return types and function parameters have changed from UILocalNotification to UNNotificationRequest. Refer to the reference documentation for the exact method signature. The keys/values in the userInfo fields of notifications and geotriggers remained unchanged.

Back To Top

5.6 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

5.7 Android BroadcastReceivers

When extended and declared in the manifest, custom Android BroadcastReceivers allow overriding the default behavior of some plugin actions.


Notification Filter BroadcastReceiver

The NotificationFilterBroadcastReceiver class when extended, allows modifying and filtering notifications before they are shown. This class provides access to the application context and to the list of notifications that are going to be shown.

Overrides action: ${applicationId}.plot.FilterNotifications


Geotrigger Handler BroadcastReceiver

The GeotriggerHandlerBroadcastReceiver class when extended, allows running custom code when handling geotriggers. This class provides access to the application context and to the list of geotriggers currently being handled.

Overrides action: ${applicationId}.plot.HandleGeotriggers"


Notification Handler BroadcastReceiver

The Notification Handler doesn't have a custom class, extending the BroadcastReceiver and overriding the open notification action, allows to define custom a custom behavior when a notification is clicked.

Overrides action: ${applicationId}.plot.OpenNotification


Notification Event BroadcastReceiver

The Notification Event doesn't have a custom class, extending the BroadcastReceiver and overriding the sent and/or opened notification action(s), allows listening to these events and act upon them accordingly.

Overrides actions: ${applicationId}.plot.SentNotification and ${applicationId}.plot.OpenedNotification


Configuration Hook BroadcastReceiver

The ConfigHookBroadcastReceiver class when extended, allows setting plot configurations via code. This class provides access to the application context and to the configurations that are currently set.

This custom BroadcastReceiver offers an alternative to using the Notification Filter to bypass the issue associated with flaky loading of the notification icon via the configuration file.

Overrides action: ${applicationId}.plot.ConfigHook

Back To Top

6. Partners and integrations

6.1 CleverTap


Platforms:   iOS   Android


Using Plot Projects and CleverTap together allows you to segment your users based on the places they visit and add a location-intelligence layer to your marketing campaigns. You can, for example, segment and send push notifications to users whom you have qualified as 'Train Commuters’ based on who visited a train station more than eight times in the last week or 'Regular Cinema Visitors' based on who visited the cinema more than two times in the last month.

Set up a Listening Campaign in the Plot Projects dashboard

Plot Projects offers a Geo SDK easily connects to the CleverTap SDK (see paragraphs below). Once this is done you can create Listening Campaigns in the Plot Projects dashboard that tracks visits of your users.

The first step is to create the locations you want to track. This can be a single location like a train station:

Or a large set of locations:

Once your locations are set up, you can create a Plot Projects Listening Campaign defining the Segment you’d like users to be added after visiting the designated location(s).

When creating the campaign, set the field ‘Listening campaign Data’ with the tag key value in json format

{"key": "visited_train_station"}

That’s it, you’ve finished setting up the location campaigns! Users can now be automatically added to the corresponding segments in your CleverTap dashboard.

Plot Projects Listening Campaigns have many options, including:

  • Trigger on geofences, polygons and/or beacons.
  • Trigger on enter, exit or dwell.
  • Define opening hours per location.
  • Define start and end dates of the campaign.

Integrating into your app

Now that your Listening Campaign is set up, your app can be location-aware and forward the events to CleverTap. This integration guide is designed for iOS and Android, but also works for other supported platforms of the Plot SDK. After completing the integration guide, when a user enters the Paddington Station Plot triggers a CleverTap event. That results in the CleverTap dashboard as below:

iOS integration

Start with the Plot Projects integration guide and the CleverTap integration guide. After integrating both libraries, you can forward geotrigger events from Plot Projects to CleverTap.

To receive geotrigger events from Plot Projects add the plotHandleGeotriggers method to your AppDelegate.m file. In that method you also call the CleverTap API in order to send the event.

Add to AppDelegate.m

- (void)plotHandleGeotriggers:(PlotHandleGeotriggers*) geotriggerHandler {
    for (PlotGeotrigger* geotrigger in geotriggerHandler.geotriggers) {
        NSString* data = [geotrigger.userInfo objectForKey:PlotGeotriggerDataKey];
        NSString *now = [NSString stringWithFormat:@"%.f",[[NSDate date] timeIntervalSince1970]];
        NSDictionary *props = [NSDictionary dictionaryWithObject:now forKey:@"Date"];
        [[CleverTap sharedInstance] recordEvent:data withProps:props];
        NSLog(@"Sending event with properties:(%@,%@)",data,props);
    }
    [geotriggerHandler markGeotriggersHandled:geotriggerHandler.geotriggers];
}

The plotHandleGeotriggers method, presented above, sends an event to CleverTap using the data field set in the dashboard as key and the current timestamp as value.

What's next

Users are now added automatically to the corresponding segments in the CleverTap dashboard. You can now target or create location-based marketing campaigns for these segments.

Android Integration

Start with the Plot Projects integration guide and the CleverTap integration guide. After integrating both libraries, you can forward geotrigger events from Plot Projects to CleverTap.

To receive geotrigger events from Plot Projects, create a class that extends GeotriggerHandlerBroadcastReceiver. In that class you call the CleverTap API in order to send the event.

public class MyGeotriggerHandlerBroadcastReceiver extends GeotriggerHandlerBroadcastReceiver {
   private static final String LOG_TAG = "MyGeotriggerHandler";
   @Override
   public List<Geotrigger> handleGeotriggers(List<Geotrigger> list) {
       for (Geotrigger geotrigger: list)
           try {
               JSONObject jsonObject = new JSONObject(geotrigger.getData());
               String key = jsonObject.getString("key");

               CleverTapAPI cleverTap = CleverTapAPI.getInstance(getContext());
               cleverTap.event.push(key);

               Log.d(LOG_TAG, "sent CleverTap event: " + key);
           } catch (CleverTapException e) {
               // handle CleverTap exception
           } catch (JSONException e) {
               // handle JSON exception
           }
       return list;
   }
}

The MyGeotriggerHandlerBroadcastReceiver, presented above, records an event for CleverTap using the data field set in the dashboard as key.

To let Android find the receiver, add it to AndroidManifest.xml

<receiver
    android:name=".MyGeotriggerHandlerBroadcastReceiver"
    android:permission="false">
    <intent-filter>
        <action android:name="${applicationId}.plot.HandleGeotriggers" />
    </intent-filter>
</receiver>
What's next

Users are now added automatically to the corresponding segments in the CleverTap dashboard. You can now target or create location-based marketing campaigns for these segments.

Back To Top

6.2 OneSignal


Platforms:   iOS   Android


Using Plot Projects and OneSignal together allows you to segment your users based on the places they visit. This allows you to for instance send a push notification to users that visited 'LAX' or 'a Walmart in the last 7 days':

Set up a Listening Campaign in the Plot Projects dashboard

Plot Projects offers a Geo SDK that easily connects to the OneSignal SDK (see paragraphs below). Once this is done you can create Listening Campaigns in the Plot Projects dashboard that track visits of your users.

The first step is to create the locations you want to track. This can be a single location:

Or a large set of locations:

Once your locations are set up, you can create a Plot Projects Listening Campaign defining the Segment the user should be added to after visiting the location. When creating the campaign, set the field 'Listening campaign Data' with the tag key value in json format (eg

{"key": "visited_walmart"}
or
{"key": "visited_LAX"}
):

Plot Projects Listening Campaigns have many options, including:

  • Trigger on geofences, polygons and/or beacons.
  • Trigger on enter, exit or dwell.
  • Define opening hours per location.
  • Define start and end dates of the campaign.

Integrating into your app

Now that your Listening Campaign is set up, your app can be location-aware and forward the events to OneSignal. This integration guide is designed for iOS and Android, but also works for other supported platforms of the Plot SDK. After completing the integration guide, if a user enters the LAX, Plot triggers a OneSignal event. You can see the result in the OneSignal dashboard.

iOS integration

Start with the Plot Projects integration guide and the OneSignal integration guide. After integrating both libraries, you can track geotrigger events from Plot Projects in OneSignal.

To receive geotrigger events from Plot Projects on your iOS app, add the plotHandleGeotriggers method to your AppDelegate.m file. In that method you will also call the OneSignal API in order to send the event:

- (void)plotHandleGeotriggers:(PlotHandleGeotriggers*) geotriggerHandler {
        for (PlotGeotrigger* geotrigger in geotriggerHandler.geotriggers) {
            NSString* data = [geotrigger.userInfo objectForKey:PlotGeotriggerDataKey];
            NSString *now = [NSString stringWithFormat:@"%.f",[[NSDate date] timeIntervalSince1970]];
            [OneSignal sendTag:data value:now];
            NSLog(@"Sending tag pair:(%@,%@)",data,now);
        }
        [geotriggerHandler markGeotriggersHandled:geotriggerHandler.geotriggers];
}

The plotHandleGeotriggers method, presented above, sends a tag to OneSignal using the data field set in the dashboard as key and the current timestamp as value.

What's next

Users are now added automatically to the corresponding segments in the OneSignal dashboard. You can now target or create location-based marketing campaigns for these segments.

Android integration

Start with the Plot Projects integration guide and the OneSignal integration guide. After integrating both libraries, you can track geotrigger events from Plot Projects in OneSignal.

To receive geotrigger events from Plot Projects on your Android app, create a class that extends from GeotriggerHandlerReceiver. In that class you call the OneSignal API in order to send the event.

public class SendTagGeotriggerHandlerReceiver extends GeotriggerHandlerReceiver {

   static final String LOG_TAG = "Send tag Handler";

   @Override
   public List<Geotrigger> handleGeotriggers(List<Geotrigger> geotriggers) {

       for (Geotrigger geotrigger : geotriggers) {
           String data = geotrigger.getData();
           String now = String.valueOf(System.currentTimeMillis()/1000);
           OneSignal.sendTag(data,now);
           Log.d(LOG_TAG, "Sent tag " + "(" + data + ", " + now + ")");
       }
       return geotriggers;
   }
}

The SendTagGeotriggerHandler, presented above, sends a tag to OneSignal using the data field set in the dashboard as key and the current timestamp as value.

To let Android find the service, add it to AndroidManifest.xml

<service android:name=".SendTagHandlerReceiver" android:exported="false" />

If you are having any dependency conflicts read about how to fix them here.

What's next

Users are now added automatically to the corresponding segments in the OneSignal dashboard. You can now target or create location-based marketing campaigns for these segments.

Back To Top

6.3 Swrve

There is no integration guide to connect Swrve and Plot Projects as Swrve offers a Swrve Geo-SDK in which the Plot Projects SDK is fully integrated. Swrve also offers a dashboard integration allowing you to manage your Plot Projects geofences and notification campaigns from the Swrve dashboard. Current Swrve customers can contact their Swrve CSM to enable Geo and non Swrve customers can contact sales@swrve.com

In the Swrve dashboard, you can create a Plot Projects geofence, as shown in the following screenshot.

You can also create a Location-Based campaign (see below).

Back To Top

6.4 Leanplum


Platforms:   iOS   Android


Using Plot Projects and Leanplum together allows you to segment your users based on the places they visit and add a location-intelligence layer to your marketing campaigns. You can, for example, send push notifications to and target users whom you have qualified as 'Train Commuters’ based on who visited a train station more than eight times in the last week.

Set up a Listening Campaign in the Plot Projects dashboard

Plot Projects offers a Geo SDK that easily connects to the Leanplum SDK (see paragraphs below). Once this is done you can create Listening Campaigns in the Plot Projects dashboard that track visits of your users.

The first step is to create the locations you want to track. This can be a single location like a train station:

Or a large set of locations:

Once your locations are set up, you can create a Plot Projects Listening Campaign defining the Segment you’d like users to be added after visiting the designated location(s).

When creating the campaign, set the field ‘Listening campaign Data’ with the tag value

visited_train_station

That’s it, you’ve finished setting up the location campaigns! Users can now be automatically added to the corresponding segments in your Leanplum dashboard.

Plot Projects Listening Campaigns have many options, including:

  • Trigger on geofences, polygons and/or beacons.
  • Trigger on enter, exit or dwell.
  • Define opening hours per location.
  • Define start and end dates of the campaign.

Integrating in your app

Now that your Listening Campaign is set up, your app can be location-aware and track the events in Leanplum. This integration guide is designed for iOS and Android, but also works for other supported platforms of the Plot SDK. After completing the integration guide, if a user enters the station, Plot triggers a Leanplum event that results in the Leanplum dashboard as below

Then, you create and save your segments in the Leanplum dashboard as follows:

As a result, you can use the segments created to target users that have the specified attributes:

iOS integration

Start with the Plot Projects integration guide and the Leanplum integration guide. After integrating both libraries, you can track geotrigger events from Plot Projects in Leanplum.

To receive geotrigger events from Plot Projects add the plotHandleGeotriggers method to your AppDelegate.m file. In that method you also call the Leanplum API in order to send the event.

Add to AppDelegate.m

- (void)plotHandleGeotriggers:(PlotHandleGeotriggers*) geotriggerHandler {
    for (PlotGeotrigger* geotrigger in geotriggerHandler.geotriggers) {
        NSString* data = [geotrigger.userInfo objectForKey:PlotGeotriggerDataKey];
        NSString *now = [NSString stringWithFormat:@"%.f",[[NSDate date] timeIntervalSince1970]];
        NSDictionary* info = [NSDictionary dictionaryWithObject:now forKey:@"Date"];
        [Leanplum track:data withParameters:info];
        NSLog(@"Tracking event with properties:(%@,%@)",data,info);
    }
    [geotriggerHandler markGeotriggersHandled:geotriggerHandler.geotriggers];
}

The plotHandleGeotriggers method, presented above, sends an event to Leanplum using the data field set in the dashboard as key and the current timestamp as value.

What's next

Users are now added automatically to the corresponding segments in the OneSignal dashboard. You can now target or create location-based marketing campaigns for these segments.

Android Integration

Start with the Plot Projects integration guide and the Leanplum integration guide. After integrating both libraries, you can track geotrigger events from Plot Projects in Leanplum.

To receive geotrigger events from Plot Projects, create a class that extends GeotriggerHandlerBroadcastReceiver. To track the geotrigger event you call the Leanplum API from that class.

public class MyGeotriggerHandlerBroadcastReceiver extends GeotriggerHandlerBroadcastReceiver {
    private static final String LOG_TAG = "MyGeotriggerHandler";
    @Override
    public List<Geotrigger> handleGeotriggers(List<Geotrigger> list) {
        for (Geotrigger geotrigger: list)
            try {
                String key = geotrigger.getData();

                Leanplum.track(key);

                Log.d(LOG_TAG, "track Leanplum event: " + key);
            } catch (LeanplumException e) {
                // handle Leanplum exception
            }
        return list;
    }
}

The MyGeotriggerHandlerBroadcastReceiver, presented above, records an event for Leanplum using the data field set in the dashboard as key.

To let Android find the receiver, add it to AndroidManifest.xml

<receiver
    android:name=".MyGeotriggerHandlerBroadcastReceiver"
    android:permission="false">
    <intent-filter>
        <action android:name="${applicationId}.plot.HandleGeotriggers" />
    </intent-filter>
</receiver>
What's next

Users are now added automatically to the corresponding segments in the Leanplum dashboard. You can now target or create location-based marketing campaigns for these segments.

Back To Top

6.5 mParticle


Platforms:   iOS   Android

Using Plot Projects and mParticle together allows you to segment your users based on the places they visit and add a location-intelligence layer to your marketing campaigns. You can, for example, segment and send push notifications to users whom you have qualified as 'Train Commuters’ based on who visited a train station more than eight times in the last week.

Set up a Listening Campaign in the Plot Projects dashboard

Plot Projects offers a Geo SDK easily connects to the mParticle SDK. Once this is done you can create Listening Campaigns in the Plot Projects dashboard that track visits of your users.

The first step is to create the locations you want to track. This can be a single location like a train station:

Or a large set of locations:

Once your locations are set up, you can create a Plot Projects Listening Campaign defining the Segment you’d like users to be added after visiting the designated location(s).

When creating the campaign, set the field ‘Listening campaign Data’ with the tag value

visited_train_station

That’s it, you’ve finished setting up the location campaigns! Users can now be automatically added to the corresponding segments in your mParticle dashboard.

Plot Projects Listening Campaigns have many options, including:

  • Trigger on geofences, polygons and/or beacons.
  • Trigger on enter, exit or dwell.
  • Define opening hours per location.
  • Define start and end dates of the campaign.

Integrating in your app

Now that your Listening Campaign is set up, your app can be location-aware and track the events in mParticle. This integration guide is designed for iOS and Android, but also works for other supported platforms of the Plot SDK. After completing the integration guide, if a user enters the station, Plot triggers a mParticle event that will show up in the mParticle dashboard.


iOS integration

Start with the Plot Projects integration guide and the mParticle integration guide. After integrating both libraries, you can track geotrigger events from Plot Projects in mParticle.

To receive geotrigger events from Plot Projects add the plotHandleGeotriggers method to your AppDelegate.m file. In that method you also call the mParticle API in order to send the event.

Add to AppDelegate.m

- (void)plotHandleGeotriggers:(PlotHandleGeotriggers*) geotriggerHandler {
    for (PlotGeotrigger* geotrigger in geotriggerHandler.geotriggers) {
        NSString* data = [geotrigger.userInfo objectForKey:PlotGeotriggerDataKey];
        MPEvent *event = [[MPEvent alloc] initWithName:data type:MPEventTypeLocation];
        NSLog(@"Tracking event with properties:(%@)",data);
    }
    [geotriggerHandler markGeotriggersHandled:geotriggerHandler.geotriggers];
}

The plotHandleGeotriggers method, presented above, sends an event to mParticle using the data field set in the dashboard as key and the current timestamp as value.

What's next

Users are now added automatically to the corresponding segments in the mParticle dashboard. You can now target or create location-based marketing campaigns for these segments.

Android integration

Start with the Plot Projects integration guide and the mParticle integration guide. After integrating both libraries, you can track geotrigger events from Plot Projects in mParticle.

To receive geotrigger events from Plot Projects, create a class that extends GeotriggerHandlerBroadcastReceiver. To track the geotrigger event you call the mParticle API from that class.

public class MyGeotriggerHandlerBroadcastReceiver extends GeotriggerHandlerBroadcastReceiver {
    private static final String LOG_TAG = "MyGeotriggerHandler";
    @Override
    public List<Geotrigger> handleGeotriggers(List<Geotrigger> list) {
        for (Geotrigger geotrigger: list)
            String data = geotrigger.getData();

            MPEvent event = new MPEvent.Builder(data, EventType.Location)
                                       .duration(100)
                                       .build();

            MParticle.getInstance().logEvent(event);

            Log.d(LOG_TAG, "track mParticle event: " + data);
        return list;
    }
}

The MyGeotriggerHandlerBroadcastReceiver, presented above, records an event for mParticle using the data field set in the dashboard as key.

To let Android find the receiver, add it to AndroidManifest.xml

<receiver
    android:name=".MyGeotriggerHandlerBroadcastReceiver"
    android:permission="false">
    <intent-filter>
        <action android:name="${applicationId}.plot.HandleGeotriggers" />
    </intent-filter>
</receiver>
What's next

Users are now added automatically to the corresponding segments in the mParticle dashboard. You can now target or create location-based marketing campaigns for these segments.

Back To Top

6.6 Shopgate

There is no integration guide to connect Shopgate and Plot Projects as Shopgate already fully integrated the Plot Projects SDK into their platform. Current Shopgate customers can contact their Shopgate CSM to enable Geo and non-Shopgate customers can contact sales@shopgate.com to inquire about getting started with a mobile app.

Back To Top

6.7 TargetEveryone

There is no integration guide to connect TargetEveryone and Plot Projects as TargetEveryone already fully integrated the Plot Projects SDK into their platform. TargetEveryone also offers a dashboard integration allowing you to manage your Plot Projects geofences and notification campaigns from the TargetEveryone dashboard. Current TargetEveryone customers can contact their TargetEveryone CSM to enable Geo and non TargetEveryone customers can contact sales@targeteveryone.com.

Back To Top

6.8 Urban Airship


Integrations:

Integration 1 - Location Based Push

Integration 2 - Segments based on Location History

 

To use Plot Projects and Urban Airship together, we present in this section two possible integrations: the first one is used for sending real-time location-based push messages, while the second one is used to create audiences based on the location history of devices.

Integration 1: Location Based Push

Platforms:   iOS   Android


Using Plot Projects and Urban Airship together allows you to add a location-intelligence layer to your marketing campaigns by targeting your users based on the places they visit. You can, for example, automatically send push notifications to users when they approach or enter a Walmart.

You create and save your automatic messages in the Urban Airship dashboard as described in the following sections.

Set up a Listening Campaign in the Plot Projects dashboard

Plot Projects offers a Geo SDK that easily connects to the Urban Airship SDK (see paragraphs below). Once this is done you can create Listening Campaigns in the Plot Projects dashboard that track when a user visits a location.

The first step is to create the locations you want to track. This can be a single location like a Walmart store:

Or a large set of locations:

Once your locations are set up, you can create a Plot Projects Listening Campaign defining the event to be tracked after visiting the designated location(s).

When creating the campaign, set the field ‘Listening campaign Data’ with the event name.

user_enters_walmart

That’s it, you’ve finished setting up the location campaigns! Users can now be automatically targeted with push notifications.

Plot Projects Listening Campaigns have many options, including:

  • Trigger on geofences, polygons and/or beacons.
  • Trigger on geofence enter, exit or dwell.
  • Define opening hours per location.
  • Define start and end dates of the campaign.
Integrating into your app

Now that your Listening Campaign is set up, your app can be location-aware and track the visit events in Urban Airship. This integration guide is designed for iOS and Android, but also works for other supported platforms of the Plot SDK. After completing the integration guide, if a user enters a Walmart store, Plot triggers an Urban Airship event that results in the Urban Airship dashboard as below:

As a result, you can use the events created to send real-time messages to users when they approach this location. Do this by creating an automated message in the Urban Airship dashboard, as shown below, and setting the event as the message's trigger:

iOS integration

Start with the Plot Projects integration guide and the Urban Airship integration guide. After integrating both libraries, you can track geotrigger events from Plot Projects in Urban Airship.

To receive geotrigger events from Plot Projects add the plotHandleGeotriggers method to your AppDelegate.m file. In that method you also call the Urban Airship API in order to track the event.

Add to AppDelegate.m

- (void)plotHandleGeotriggers:(PlotHandleGeotriggers*) geotriggerHandler {
    for (PlotGeotrigger* geotrigger in geotriggerHandler.geotriggers) {
        NSString* data = [geotrigger.userInfo objectForKey:PlotGeotriggerDataKey];

        // Create and name an event with a value
        UACustomEvent *event = [UACustomEvent eventWithName:data];

        NSLog(@"Sending event with properties:(%@,%@)",data,props);

        // Record the event
        [event track];

     [[UAirship push] updateRegistration];
    }
    [geotriggerHandler markGeotriggersHandled:geotriggerHandler.geotriggers];
}

The plotHandleGeotriggers method, presented above, sends an event to Urban Airship using the data field set in the dashboard as the event name.

What's next

Users are now targeted to receive a push message that was set based on the tracked event, in the Urban Airship dashboard. You can now create location-based marketing campaigns for these users.

Android Integration

Start with the Plot Projects integration guide and the Urban Airship integration guide. After integrating both libraries, you can track geotrigger events from Plot Projects in Urban Airship.

To receive geotrigger events from Plot Projects, create a class that extends GeotriggerHandlerBroadcastReceiver. To track the geotrigger event you call the Urban Airship API from that class.

public class MyGeotriggerHandlerBroadcastReceiver extends GeotriggerHandlerBroadcastReceiver {
    private static final String LOG_TAG = "MyGeotriggerHandler";
    @Override
    public List<Geotrigger> handleGeotriggers(List<Geotrigger> list) {
        for (Geotrigger geotrigger: list)
            try {
                String key = geotrigger.getData();

                CustomEvent.Builder builder = new CustomEvent.Builder(key);

                builder.create().track();

                Log.d(LOG_TAG, "sent event: " + key);

            } catch (Exception e) {
                // handle exception
            }
        return list;
    }
}

The MyGeotriggerHandlerBroadcastReceiver, presented above, records an event for Urban Airship using the data field set in the Plot Projects dashboard as event name. It also adds a tag with the event name.

To let Android find the receiver, add it to AndroidManifest.xml

<receiver
    android:name=".MyGeotriggerHandlerBroadcastReceiver"
    android:permission="false">
    <intent-filter>
        <action android:name="${applicationId}.plot.HandleGeotriggers" />
    </intent-filter>
</receiver>
What's next

Users are now targeted to receive a push message that was set based on the tracked event, in the Urban Airship dashboard. You can now create location-based marketing campaigns for these users.

Integration 2: Segments based on Location History

Platforms:   iOS   Android


Using Plot Projects and Urban Airship together allows you to add a location-intelligence layer to your marketing campaigns by segmenting your users based on the places they visit. You can, for example, create an audience of users who visited a Walmart.

You create and save your audiences in the Urban Airship dashboard as described in the following sections.

Set up a Listening Campaign in the Plot Projects dashboard

Plot Projects offers a Geo SDK that easily connects to the Urban Airship SDK (see paragraphs below). Once this is done you can create Listening Campaigns in the Plot Projects dashboard that track users' location history.

The first step is to create the locations you want to track. This can be a single location like a Walmart store:

Or a large set of locations:

Once your locations are set up, you can create a Plot Projects Listening Campaign defining the event to be tracked in the SDK and which will define the audience you’d like users to be added after visiting the designated location(s).

When creating the campaign, set the field ‘Listening campaign Data’ with the tag value

visited_walmart

That’s it, you’ve finished setting up the location campaigns! Users can now be automatically added to the corresponding audience in your Urban Airship dashboard.

Plot Projects Listening Campaigns have many options, including:

  • Trigger on geofences, polygons and/or beacons.
  • Trigger geofence on enter, exit or dwell.
  • Define opening hours per location.
  • Define start and end dates of the campaign.
Integrating into your app

Now that your Listening Campaign is set up, your app can be location-aware and use the events created in the Plot Projects dashboard to tag users as members of an audience in Urban Airship. This integration guide is designed for iOS and Android, but also works for other supported platforms of the Plot SDK. After completing the integration guide, if a user enters a Walmart store, Plot adds an Urban Airship tag to the user that results in the Urban Airship dashboard.

After setting a tag for the users that visited a location, you create and save an audience based on this tag, in the Urban Airship dashboard:

iOS integration

Start with the Plot Projects integration guide and the Urban Airship integration guide. After integrating both libraries, you can add tags based on geotrigger events from Plot Projects using the Urban Airship API.

To receive geotrigger events from Plot Projects add the plotHandleGeotriggers method to your AppDelegate.m file. In that method you also call the Urban Airship API in order to add the corresponding tag.

Add to AppDelegate.m

- (void)plotHandleGeotriggers:(PlotHandleGeotriggers*) geotriggerHandler {
    for (PlotGeotrigger* geotrigger in geotriggerHandler.geotriggers) {
        NSString* data = [geotrigger.userInfo objectForKey:PlotGeotriggerDataKey];

        // Add a tag
        [[UAirship push] addTag:data];

        // Update registration
        [[UAirship push] updateRegistration];

    }
    [geotriggerHandler markGeotriggersHandled:geotriggerHandler.geotriggers];
}

The plotHandleGeotriggers method, presented above, sets a tag in Urban Airship using the data field set in the Plot Projects dashboard as a tag name.

What's next

Users are now added automatically to the corresponding audiences in the Urban Airship dashboard. You can now create location-based marketing campaigns for these audiences. For instance, sending a push message to users who have visited a Walmart store at some point in the past.

Android Integration

Start with the Plot Projects integration guide and the Urban Airship integration guide. After integrating both libraries, you can add tags based on geotrigger events from Plot Projects using the Urban Airship API.

To receive geotrigger events from Plot Projects, create a class that extends GeotriggerHandlerBroadcastReceiver. To add the corresponding tag, you call the Urban Airship API from that class.

public class MyGeotriggerHandlerBroadcastReceiver extends GeotriggerHandlerBroadcastReceiver {
    private static final String LOG_TAG = "MyGeotriggerHandler";
    @Override
    public List<Geotrigger> handleGeotriggers(List<Geotrigger> list) {
        for (Geotrigger geotrigger: list)
            try {
                String key = geotrigger.getData();

                UAirship.shared().getPushManager().editTags().addTag(key).apply();

            } catch (Exception e) {
                // handle exception
            }
        return list;
    }
}

The MyGeotriggerHandlerBroadcastReceiver, presented above, sets a tag in Urban Airship using the data field set in the Plot Projects dashboard as a tag name.

To let Android find the receiver, add it to AndroidManifest.xml

<receiver
    android:name=".MyGeotriggerHandlerBroadcastReceiver"
    android:permission="false">
    <intent-filter>
        <action android:name="${applicationId}.plot.HandleGeotriggers" />
    </intent-filter>
</receiver>
What's next

Users are now added automatically to the corresponding audiences in the Urban Airship dashboard. You can now create location-based marketing campaigns for these audiences. For instance, sending a push message to users who have visited a Walmart store at some point in the past.

Combined Integration

Apart from the aforementioned integrations used separately, it is also possible to combine them. This allows you to send both real-time Location Based Push Notifications and push messages to an Urban Airship Audience created based on Location History Events. For instance, send a specific Push Notification to users that enter a Walmart and that have visited a Walgreens in the last 7 days.

Back To Top

6.9 Mixpanel


Platforms:   iOS   Android


Using Plot Projects and Mixpanel together allows you to segment your users based on the places they visit and add a location-intelligence layer to your marketing campaigns. You can, for example, segment and send push notifications to users whom you have qualified as 'Train Commuters’ based on who visited a train station more than eight times in the last week or 'Regular Cinema Visitors' based on who visited the cinema more than two times in the last month.

Set up a Listening Campaign in the Plot Projects dashboard

Plot Projects offers a Geo SDK that easily connects to the Mixpanel SDK (see paragraphs below). Once this is done you can create Listening Campaigns in the Plot Projects dashboard that track visits of your users.

The first step is to create the locations you want to track. This can be a single location like a train station:

Or a large set of locations:

Once your locations are set up, you can create a Plot Projects Listening Campaign defining the Segment you’d like users to be added after visiting the designated location(s).

When creating the campaign, set the field ‘Listening campaign Data’ with the tag key value in json format

{"key": "visited_train_station"}

That’s it, you’ve finished setting up the location campaigns! Users can now be automatically added to the corresponding segments in your Mixpanel dashboard.

Plot Projects Listening Campaigns have many options, including:

  • Trigger on geofences, polygons and/or beacons.
  • Trigger on enter, exit or dwell.
  • Define opening hours per location.
  • Define start and end dates of the campaign.

Integrating into your app

Now that your Listening Campaign is set up, your app can be location-aware and forward the events to Mixpanel. This integration guide is designed for iOS and Android, but also works for other supported platforms of the Plot SDK. After completing the integration guide, when a user enters the Paddington Station Plot triggers a Mixpanel event. That results in the Mixpanel dashboard as below:

iOS integration

Start with the Plot Projects integration guide and the Mixpanel integration guide. After integrating both libraries, you can forward geotrigger events from Plot Projects to Mixpanel.

To receive geotrigger events from Plot Projects add the plotHandleGeotriggers method to your AppDelegate.m file. In that method you also call the Mixpanel API in order to send the event.

Add to AppDelegate.m

- (void)plotHandleGeotriggers:(PlotHandleGeotriggers*) geotriggerHandler {
    for (PlotGeotrigger* geotrigger in geotriggerHandler.geotriggers) {
        NSString* data = [geotrigger.userInfo objectForKey:PlotGeotriggerDataKey];
        NSString *now = [NSString stringWithFormat:@"%.f",[[NSDate date] timeIntervalSince1970]];
        NSDictionary *props = [NSDictionary dictionaryWithObject:now forKey:@"Date"];
        [[Mixpanel sharedInstance] track:data properties:props];
        NSLog(@"Sending event with properties:(%@,%@)",data,props);
    }
    [geotriggerHandler markGeotriggersHandled:geotriggerHandler.geotriggers];
}

The plotHandleGeotriggers method, presented above, sends an event to Mixpanel using the data field set in the dashboard as key and the current timestamp as value.

What's next

Users are now added automatically to the corresponding segments in the Mixpanel dashboard. You can now target or create location-based marketing campaigns for these segments.

Android Integration

Start with the Plot Projects integration guide and the Mixpanel integration guide. After integrating both libraries, you can forward geotrigger events from Plot Projects to Mixpanel.

To receive geotrigger events from Plot Projects, create a class that extends GeotriggerHandlerBroadcastReceiver. In that class you call the Mixpanel API in order to send the event.

public class MyGeotriggerHandlerBroadcastReceiver extends GeotriggerHandlerBroadcastReceiver {
   private static final String LOG_TAG = "MyGeotriggerHandler";
   private static final String PROJECT_TOKEN = "YOUR_PROJECT_TOKEN";

   @Override
   public List<Geotrigger> handleGeotriggers(List<Geotrigger> list) {
       MixpanelAPI mixpanel = MixpanelAPI.getInstance(getContext(), PROJECT_TOKEN);
       mixpanel.identify("1234"); // Identify the device, if haven't already done so
       for (Geotrigger geotrigger: list)
           try {
               JSONObject jsonObject = new JSONObject(geotrigger.getData());
               String key = jsonObject.getString("key");

               mixpanel.track(key);

               Log.d(LOG_TAG, "sent Mixpanel event: " + key);
           } catch (JSONException e) {
               // handle JSON exception
           }
       return list;
   }
}

The MyGeotriggerHandlerBroadcastReceiver, presented above, records an event for Mixpanel using the data field set in the dashboard as key.

To let Android find the receiver, add it to AndroidManifest.xml

<receiver
    android:name=".MyGeotriggerHandlerBroadcastReceiver"
    android:permission="false">
    <intent-filter>
        <action android:name="${applicationId}.plot.HandleGeotriggers" />
    </intent-filter>
</receiver>
What's next

Users are now added automatically to the corresponding segments in the Mixpanel dashboard. You can now target or create location-based marketing campaigns for these segments.

Back To Top