Config file

Configuration file

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

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

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
}

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.

Setting the icon by adding the property notificationSmallIcon to the plotconfig.json is now deprecated. In order to set it, please refer to Configuration Hook.

It is 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 2.1.0, you can pick your own notification channel for the notifications created by the plugin, instead of having the plugin create a channel for you. You have to create the channel yourself first. To accomplish this, set notificationChannelName followed the name of your channel. For more information about Notification Channels, read Create and Manage Notification Channels. A use-case for this is to create a channel with different settings than the default.

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 Ongoing 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 an ongoing notification when there's network activity, namely for loading/updating campaigns and sending statistics. In case you don't want the ongoing notification to be shown, set showOnGoingNotification to never. The option onGoingNotificationText allows you to define the text displayed in the ongoing notification. When not specified the default message that is used is "Updating app content…".

Plugin version 3.5.0 introduces an experimental combined monitoring mode. You enable this option by setting enableCombinedMonitoring to true. The default value is false.

Plugin version 3.6.0 introduces an improved way of determining when a user is nearby a targeted place. Using the most advanced technology in the market combined with our technology, we can now find out the movement of an user, if the user is walking, or stopped, or even driving by car.

By default this functionality is disabled, to enable it you need to set enableTransitionRecognition to true, and then decide which transitions you want to monitor.

In case you enabled this functionality, you should set in transitionRecognitionActivities the transitions you want to monitor in an array format. In case you don't set them, the default value is ["ENTER-STILL", "EXIT-STILL"].

The available options are:

Enter Exit
Vehicle ENTER-VEHICLE EXIT-VEHICLE
Bicycle ENTER-BICYCLE EXIT-BICYCLE
Still ENTER-STILL EXIT-STILL
Walking ENTER-WALKING EXIT-WALKING

To bring the best of this feature we recommend you to use either the two still options or all the exit options. In case you still have doubts, please contact your csm.

Plugin version 3.12.0 introduces a private mode setting, this setting disables us from storing any users data from your app. You enable this option by setting privateMode to true. The default value is false.

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…",
  "enableCombinedMonitoring": false,
  "enableTransitionRecognition": true,
  "transitionRecognitionActivities": ["EXIT-VEHICLE", "EXIT-BICYCLE", "EXIT-STILL", "EXIT-WALKING"],
  "notification_channel_name": "Location relevant notifications",
  "privateMode": true
}

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