This guide shows how to verify the Android integration of the Plot plugin.
1. Receiving Of Notifications Test

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

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

  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.
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.
2. Debug mode and log messages
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)
3. Sending the Debug Log via mail

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.

4. Location testing using emulator

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.

5. Location testing using testLocation() method

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.

6. Wrap up

Testing your Android integration isn’t hard. We have shown you how you can verify that your app successfully receives notifications and how to understand the log messages Plot may print. Don’t forget to disable the debug log messages when releasing your application.

We hope that this blogpost clarifies how to properly integrate the Plot plugin into your Android application. If you have problems during one of these steps, you can post your on Stackoverflow. Or contact your customer success manager with questions. We’ll help you.