Update October 26th 2017: We have updated this post after the release of version 2.0.2 of our iOS plugin.
This guide shows how to verify the iOS integration of the Plot plugin.
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:
- 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.
- 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.
- Log in into the Plot Projects dashboard
- 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.
- Give the campaign a name and a message. You can ignore the fields on the Advanced Settings screen.
- 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.
- Select in the “Users should receive notifications“ section the option “More than once” and save your campaign.
- Note that you don’treceive 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
- If you did not receive your test notification please use this checklist.
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)
2017-09-18 17:12:48 - Showing notification: da13094b56d0482298d5fba912ad8cbd - Welcome
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
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 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.
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.
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.
We have shown you how you can verify that your app can successfully receive notifications regardless of your physical location and how you can verify that your app doesn’t consume too much energy when in the background.
We hope that this blogpost clarifies how to properly integrate Plot. If you have problems during one of these steps, you can post your question to StackOverflow. We’ll help you there.