GPS Track Server for TrackMe, OruxMaps and others
NOTE: Trackserver v5.0 contains backwards-incompatible changes and changes to client configurations are needed. Please read the release notes for more information.
Getting your GPS tracks into WordPress and publishing them has never been easier!
Trackserver is a plugin for storing and publishing GPS routes. It is a server companion to several mobile apps for location tracking, and it can display maps with your tracks on them by using a shortcode. It can also be used for live tracking, where your visitors can follow you or your users on a map.
Unlike other plugins that are about maps and tracks, Trackserver’s main focus is not the publishing, but rather the collection and storing of tracks and locations. It’s all about keeping your data to yourself. Several mobile apps and protocols are supported for getting tracks into trackserver:
A shortcode [tsmap] is provided for displaying your tracks on a map. Maps are displayed using the fantastic Leaflet library and some useful Leaflet plugins are included. Maps can be viewed in full-screen on modern browsers.
To publish a map with a track in a post or a page, just include the shortcode:
[tsmap track=<id>]
See the FAQ section for more information on the shortcode’s supported attributes.
Trackserver requires PHP 5.3 or newer and it needs both DOMDocument and SimpleXML extensions installed.
This plugin was written by Martijn Grendelman. Development is tracked on Github.
It includes some code and libraries written by other people:
/wp-content/plugins/
directory.For the [tsmap] shortcode:
The following attributes apply to tracks that are drawn on the map. Each of them can contain multiple values, separated by commas (or colons, in the case of ‘dash’), to be applied to different tracks in order. If there a are less values than tracks, the last value will be applied to the remaining tracks.
Example: [tsmap track=39,84 user=@ align=center class=mymap markers=n color=#ff0000]
When you specify multiple values, please be aware of the following. While track order will be preserved within each track type, different track types are evaluated in a specific order, and styling values are applied in that order too. The order is:
To prevent confusion, I suggest you specify tracks in this order in your shortcode too.
Example: [tsmap gpx=/url/for/file.gpx user=jim track=10,99 color=red,blue,green,yellow]
In this case, the GPX track will be yellow, Jim’s live track will be green and tracks 10 and 99 will be red and blue respectively.
In a feature request I was asked to make it possible to draw just a marker on the last known location, and not draw a track at all. Use ‘markers’ and ‘opacity’ to accomplish this:
Example: [tsmap user=@ markers=e opacity=0.0]
Attributes for the [tslink] shortcode:
Example: [tslink track=1,2,3,4 text=”Download the tracks of our 4-day hike in GPX format”]
Instead of using the ‘text’ attribute, you can also use shortcode to enclose the text:
Example: [tslink track=1,2,3,4]Download the tracks of our 4-day hike in GPX format[/tslink]
Trackserver tries to detect the usage of the [tsmap] shortcode to prevent unnecessary loading of the plugin’s JavaScript. In some circumstances, for example, if your page setup is complex and uses multiple loops, the detection could fail. In such a case, use this shortcode in the main post or page to force loading the JavaScript:
[tsscripts]
There is one caveat. Trackserver only works on ‘real’ posts and pages, in WordPress terms. For example, some WordPress themes (I have seen one) offer the possibility to specify a static homepage right in the theme settings, completely overriding WordPress’ internal post logic. In this case, the page lacks an author as well as other properties that a regular WordPress post or page has. Trackserver’s [tsmap] shortcode does not work on pages like that.
All that said, Trackserver’s shortcode detection should be reasonably fool-proof these days, because if the early detection mechanism fails, the shortcode itself is used to trigger the inclusion of Trackserver’s JavaScript and CSS. The only adverse side effect this may have, is that the CSS is loaded in the footer of the page, rather than in the head section. It’s hard to say whether this will actually be a problem, but just in case it is, the [tsscripts] shortcode is there.
Beware though: the [tsscripts] shortcode doesn’t actually do anything. At all. It is merely an extra shortcode that Trackserver tries to detect. Therefore, it is absolutely useless to include [tsscripts] in the same context as your [tsmap]. I appreciate that this can be hard to understand, so let me illustrate with an example. Take the ‘Posts in page’ plugin, that allows you to use a shortcode in a post (let’s call it A) to include other posts an pages inline (let’s call them B and C). If [tsmap] is used in B or C, but the page requested by the user is A, which does not have a [tsmap], Trackserver’s shortcode detection used to fail in earlier versions, and the Javascript and CSS would not be loaded. By using the [tsscripts] shortcode in page A, the loading of JS and CSS can be forced. The CSS will then be loaded in the head of the page, instead of in the footer.
This will happen when you try to load a file from a different domain than your site is running on, and the remote server doesn’t serve a ‘Access-Control-Allow-Origin’ header that allows acces to the file. Your webbrowser refuses to process the file. Check the console in your developer tools for an error message. Please read up on Cross-Origin Resource Sharing (CORS) for more information. This is not something that Trackserver can fix.
By using the shortcode with the ‘user=…’ or ‘track=live’ parameter, the most recently updated track belonging to the specified user(s) or the author of the current post/page is published on the map.
The track is updated with the latest trackpoints every 10 seconds and the map view is always centered to the most recent trackpoint. A marker is shown in that location. Live tracking can be stopped and restarted with a simple control button that is shown on the map.
To publish other users’ tracks, the author of the page needs the ‘trackserver_publish’ capability, which is by default only granted to administrators and editors.
Before v1.9, all of Trackserver’s settings were stored in a single, global place in WordPress, meaning they were shared among all users in the same WordPress install. This was also the case for the OsmAnd access key that allows OsmAnd users to use Trackserver for live tracking. Since Trackserver tries to be multi-user, things like access keys do not belong in the global configuration.
In version 1.9, user profile settings were introduced as a place for per-user settings, like access keys. There is a separate page in the WordPress admin for the Trackserver profile (called ‘Your profile’ in English), that is accessible by all users that have the right (capability) to use Trackerver.
In version 4.3, a feature called ‘Embedded maps’ was introduced. Embedded maps are a custom WordPress post type, which are intended to have no other content than a map, filling up the entire browser window, or the container they are loaded in. They bypass your active WordPress theme and use a custom template that displays only the content of your ‘Embedded map’ post, without any headers, sidebars or even styling. This allows you to embed the map with your tracks in another website using an iframe. Trackserver will tell you the HTML code to use for embedding the map. They also look great on mobile devices, if all you really care about is the map and what’s on it.
I’m not sure about the usefulness of this feature to everyone who uses Trackserver, but personally I use it for mixing interactive maps with photos and videos in my online photo album.
TrackMe, like OsmAnd, uses HTTP GET requests for communication with Trackserver. This means that all data from the app, including your password, becomes part of the URL. Because URLs are not generally considered secret, and may be logged in access logs and what not, this is quite insecure, even with HTTPS.
For OsmAnd, that has no built-in authentication, Trackserver has used an access key instead of your WordPress password from the very beginning. For TrackMe, this was implemented in v1.9. So from version 1.9 onward, every WordPress user that is allowed to use Trackserver has its own separate access key for OsmAnd and a separate password for TrackMe, settable in the Trackme user profile.
If you have been using Trackserver with TrackMe before v1.9, you should now set the password in TrackMe to this new password, instead of your WordPress password. Like your password, you should keep your access keys to yourself, but the idea is that the security impact of such a key is low, compared to your WordPress password, and that you can (and should!) change the keys regularly. No real effort is made to keep the keys secure (they are stored in the database unhashed, for example), so in any case, try not to use a sensitive password.
Slugs are generally defined as URL-friendly and unique versions of a name or title. In WordPress, they are short descriptions of posts and pages, to be used in URLs (permalinks). They are the part of the URL that makes WordPress serve a particular page. Trackserver uses slugs to ‘listen’ for tracking requests from mobile apps, and you can configure these slugs to be anything you want. Trackserver comes with default values for these slugs, that should work for most people. Changing them is usually not necessary nor recommended. Please
read the WARNING blow before changing them.
Please refer to the WordPress Codex for more information about slugs in general.
WARNING: please do not confuse the slugs that you configure in Trackserver with the URLs (permalinks) that you use to publish your maps and tracks. Above all, make sure there is no conflict between the permalink for a post or page and the slugs that Trackserver uses for location updates. The slugs in Trackerver’s configuration are for the location updates ONLY. If you try to open them in a browser, you will get errors like ‘Illegal request’. Trackserver operates on a low level within WordPress, so if there is a conflict between Trackserver and a post or a page, Trackserver will win and the page will be inaccessible.
To publish your tracks, simply create a page (with a non-conflicting permalink) and use the [tsmap] shortcode to add a map.
Trackserver, being a WordPress plugin, can only support HTTP-based protocols for tracking. Many tracking devices use TCP- but not HTTP-based protocols for online tracking, and as such, Trackserver cannot support them, at least not without some middleware that translates the device’s protocol to HTTP.
If a device or an app does use HTTP as a transport, adding support for it in Trackserver should be quite easy. For example, I have been thinking about support for the GpsGate Server Protocol. It could be added if there is any demand for it.
If a device or an app uses a different transport, support could be added by implementing some sort of middleware. For example, OwnTracks uses MQTT and ships with a script (m2s) for storing the data. Storage methods in m2s are pluggable, so one could write an m2s-plugin for shipping the data to Trackserver.
TrackMe has a feature called ‘Cloud Sharing’, that is meant to enable users to follow other users’ locations on a map. The TrackMe app uses a different method to send location updates than for regular tracking updates. Also, it sends Cloud Sharing requests without authentication credentials, which made it hard to implement in Trackserver. Given that TrackMe sends authentication credentials in an insecure way in any case, I decided to implement a workaround for the missing credentials, by embedding them in the server URL. So, in stead of sending a request like this:
https://example.com/trackme/requests.z?username=myuser&password=mypass
we configure TrackMe to send requests like this:
https://example.com/trackme/myuser/mypass/requests.z?username=&password=
This way, it also works for cloud sharing requests, and we can get the username and password from the URL.
If you have been using TrackMe with the old style Server URL, and you try to use the cloud sharing feature, you will see a message along the lines of ‘For cloud sharing you need to update your server URL, see Trackserver FAQ.’. This means you have to update the settings in the TrackMe app to contain your username and TrackMe password in the server URL. The complete server URL can be found in your Trackserver profile as always, and the old style URL is now deprecated. Switching to the new style URL also means, that the username and password that you set in the app will no longer be used, and you can leave those settings empty.
Please also read the FAQ above: ‘What changed for TrackMe authentication 1.9’. The new URL scheme is slightly more insecure in some cases, since with the new scheme it is even more certain that your TrackMe password will end up in the server’s access logs. Other than that, there is no difference. Remember to always use HTTPS, and change your TrackMe password often, since it will give full read/write access to your Trackserver tracks.
In Trackserver, Cloud Sharing behaves a little differently than in the official TrackMe server. The official server only remembers the latest location update for your device ID. It also has a notion of ‘public’ vs ‘non-public’ location sharing, where ‘non-public’ requires some permissions exchange over mobile text message. Trackserver does not do ‘public’ sharing. Also, location updates that arrive via the cloud sharing feature are treated the same as any other update: they are stored as a track. The only difference with normal tracking is, that the track name is generated by Trackserver. A new track is created when the date changes. The track name format is ‘TrackMe Cloud yyyy-mm-dd’. This is not configurable at this time, but that may change in the furture.
Using Trackserver
The plugin uses a few custom WordPress capabilities (‘use_trackserver’, ‘trackserver_publish’ and ‘trackserver_admin’) to manage the various levels of access within Trackserver:
If you remove one or more capabilities from the listed roles, they will be re-granted on (re)activation of the plugin.
Tracks can only be published in WordPress posts or pages, and cannot be downloaded from outside WordPress. Requests for downloading tracks need to have a cryptographic signature (called a ‘nonce’) that only WordPress can generate.
Regarding the use of apps for live tracking and uploading to WordPress, please read the considerations about authentication above.
External tracks proxy
Trackserver contains code that can proxy requests to- and serve content from remote 3rd-party servers. This allows authors to work around CORS restrictions. Instead of letting the visitor’s browser get the GPX or KML from the remote server (which only works if the server implements CORS headers to allow the request), the request is sent to WordPress, where Trackserver will fetch the track from the remote server and send it to the browser.
This opens all kinds of interesting possibilities, but it is also a security risk. Your authors can use the proxy function to invoke HTTP requests to remote servers, which now originate from your server, and the response of which will be processed by your WordPress installation. This could have different adverse effects, ranging from legal liability to denial-of-service on your server.
Therefore, the proxy function is disabled by default. It can be enabled in the ‘advanced’ section of Trackserver’s settings, but I recommend to only enable it if you need it, and if you trust your authors not to use it on harmful URLs.
The proxy code can be invoked via a ‘gettrack’ request, but like all requests for tracks, it has to be signed with a valid nonce, so it should be impossible to abuse the proxy from outside WordPress.
GPX 1.1 (http://www.topografix.com/GPX/1/1) and GPX 1.0 (http://www.topografix.com/GPX/1/0).
Yes. Donations are welcome. Please visit http://www.grendelman.net/wp/trackserver-wordpress-plugin/ for details.
Release date: 05 March 2023
Fixed:
* Regression with viewing tracks in WP backend via bulk action.
Release date: 06 February 2023
Fixed:
* JS localization warning in WP backend.
Release date: 06 February 2023
This release contains many changes. Please read these notes carefully.
BIG CHANGE: Trackserver URL change for all supported apps. Starting with v5.0, Trackserver uses a single URL slug for all supported apps. This means all users have to update the server URL in the mobile apps they use for tracking. App-specific URLs still work, but will be removed in a future version. After upgrading, visit the Trackserver Options page and look at the ‘Full URL’ lines at the top. There are two versions of the universal URL. Trackserver will tell you which URL to use in which app.
BIG CHANGE: App-specific passwords and access keys (used for TrackMe, OsmAnd and SendLocation) have been transformed into ‘App Passwords’, and are now app-independent. Existing access keys are automatically converted to App Passwords during the upgrade, and will all be valid for all supported apps, including the apps that worked with your WordPress password before (OruxMaps / MapMyTracks and OwnTracks). Your WordPress password will still work for those apps, but that may change in a future release. Switching to App Passwords is recommended, regardless of the app you use for Tracking. The main benefit is an increase in security, because your WordPress password will no longer be necessary for using Trackserver. Trackserver App Passwords can be changed often without impacting WordPress logins. As an added bonus, App Passwords also work in WordPress installs that use SSO mechanisms like OAuth2 for user logins.
Added:
* A search box on the tracks management page.
* Experimental uLogger support.
* Universal slug for all protocols that Trackserver supports.
* App passwords.
* Generic ‘GET request’ support for storing locations, used for OsmAnd and Sendlocation support.
* ‘Duplicate’ bulk action for copying tracks.
* Some useful links to Github and Trackserver home page from the Plugins page in WP admin.
Changed:
* Big code restructuring changes. The main Trackserver class has been split up in different utility classes. Each protocol that Trackserver supports now lives in its own PHP class, as do the different WP admin pages and the shortcode handling code. Abstractions for database fuctionss, and data like tracks and locations have been created.
* Rewrite parts of the MapMyTracks protocol handling, to make it more robust.
* Internalized the polyline encoder for performance improvement.
* Update Leaflet, first to v1.7.1. then via v1.8.0 to v1.9.3.
Fixed:
* Embedded maps. The previously shipped template was broken and embedded maps did not actually work.
* Include tracks without locations in the list of tracks.
* CSS improvements.
* Better TrackMe error handling.
* A bug in metadata generation for polyline output.
* A PHP error when there are no posts in the $wp_query. Thanks, @caveman99.
Removed:
* TrackMe support via the WP AJAX interface. It was never used.
Release date: 10 September 2019
Fixed:
* Database structure modifications that were missing on new installs of v4.3.
* The default trackformat was changed from polyline to geojson by mistake.
Release date: 10 September 2019
Changed:
* Some code restructuring.
Fixed:
* A JavaScript conflict with the ‘Leaflet Map’ WordPress plugin.
* Markers on maps in the WP admin were almost invisible due to undefined marker size.
Release date: 6 September 2019
This release requires WordPress v4.7 or higher.
Added:
* Custom post type ‘tsmap’ for creating embedded maps.
* Infobar template placeholder for track name: {trackname}.
* Experimental support for TrackMe Cloud Sharing. To use this, you have to change the ‘URL header’ setting in TrackMe. Please see the Trackserver FAQ for details.
* Support for PhoneTrack-Android via the OsmAnd protocol.
* Support for optional HTTP Basic Authentication on the OsmAnd protocol.
* Support for setting the ‘Source’ field of a track via a URL parameter in the OsmAnd protocol.
* Support for unicode characters in text fields through charset/collation changes in DB tables.
* Shortcode attribute ‘markersize’, for specifying the size (radius) of start/end markers on tracks.
Changed:
* Trackserver now only supports WP 4.7 or higher.
* Re-enstate GeoJSON support for the ‘gettrack’ method (not for ‘gettrack_query’)
* Updated Leaflet, first to version 1.4.0 and then to 1.5.1.
* Start restructuring the plugin code into multiple classes.
* The ‘Share with friend / Follow friends’ feature that was tied to OwnTracks now also applies to Trackme Cloud Sharing.
Fixed:
* Make the ‘Show x items’ selector in the ‘Manage tracks’ page actually do something.
* Escape HTML entities in the infobar.
* Escape HTML in track names when viewing maps in the WordPress backend.
* Translation of strings related to Embedded maps by loading the translation domain earlier.
* An issue where we tried to translate a piece of HTML code.
* Coding style updates, update WPCS to v2.1.1.
* Change the default value of timestamp fields in the database, for compatibility with MySQL 5.7+ / NO_ZERO_IN_DATE.
* Add a multicolumn index on the locations table, for better performance of certain database queries.
* Missing metadata on all but the last live track in a map. Thanks to @pisoni for reporting it and suggesting a fix. The fix does incur a performance penalty though.
Release date: 21 August 2019
Release date: 18 October 2018
Release date: 18 October 2018
Release date: 18 October 2018
Release data: 8 October 2018
Added:
* OwnTracks Friends and Cards responses to Location requests.
* WordPress user avatars to OwnTracks responses, if available.
* Input fields on the Trackserver user profile page for managing OwnTracks share/follow friends.
* Stub functions for responding more nicely to TrackMe cloud sharing requests.
* A mouseover-tooltip on end-markers of live tracks, showing the user’s displayname.
* The user’s display name in the title of the Trackserver profile page.
Fixed:
* Missing gettext domain on some localized strings.
* Added some missing inline documentation in the code.
Release date: 23 February 2018
Fixed:
* Properly escape user-supplied input that is used in printf() format strings
* Make the default tile server URL use https instead of http
Release date: 23 February 2018
IMPORTANT BUGFIX: If you did a fresh install of v4.0, a column was missing from a database table,
causing location updates and GPX file uploads to fail. This release adds the column if it is missing.
Upgrades from 3.0 to 4.0 are not affected by this bug (but should still update).
Fixed:
* Updated Lithuanian translation. Thanks, Dainius Kaupaitis.
* Add title to the overlay for viewing geofences.
* Add missing database column for new installations.
Release date: 22 February 2018
This is another big update. Read more about it here: http://www.grendelman.net/wp/trackserver-v4-0-released/.
Added:
* A track editor in the WP admin, based on Leaflet.Editable. It allows you to move track points and split tracks.
* Bulk action for viewing multiple tracks at once in the admin. Editing them also works.
* Geofencing support, allowing you to hide or drop location updates within certain areas.
* A proxy for external KML and GPX tracks, to work around CORS restrictions.
* ‘maxage’ shortcode parameter to impose time-based limit on live tracks.
* OwnTracks HTTP support, locations request handling only for now.
* Bulk action for downloading tracks as GPX.
* A {distance} tag for infobar template, for total track distance in meters.
* Information about live tracking URLs and howto’s for mobile apps on the user’s Trackserver profile.
* Information on how to use live tracking in OsmAnd.
* Lithuanian translation, thanks to Dainius Kaupaitis.
* PHP coding style checks and automated testing with TravisCI.
Changed:
* Make the ‘infobar’ shortcode attribute accept a string, to override the template set in the user profile.
* Show a popup on the map with an internationalized message when there are not tracks to display.
* When a (live) track that is currently shown on the map is no longer present in the server response, show a nice popup, suggesting a page reload.
* Limit the TrackMe ‘gettriplist’ command to the 25 latest tracks, serve them in reverse order.
* Increase WP-admin ‘View track’ modal window size to 1024×768.
* Updated Polyline encoder from Eric McConville to v1.3.
* Updated Leaflet to version 1.3.1.
* Updated Leaflet-fullscreen to version 1.0.2.
Fixed:
* In JavaScript, store track information from the server more reliably.
* Improve HTTP responses around authentication failure.
* Recalculate the total track distance after merging multiple tracks.
* Easier access to Leaflet map object from 3rd party JavaScript (issue #9).
* Handle localized decimal numbers from SendLocation (issue #12).
* Some minor JavaScript and PHP issues.
* Many many many PHP coding style fixes.
Release date: 28 February 2017
Release date: 27 February 2017
This is a BIG update. Please read https://www.grendelman.net/wp/trackserver-v3-0-released/ for the full story!
Release date: 23 December 2016
This release is long overdue; most of these changes were made months ago, and I apologize.
Release date: 19 July 2016
Release date: 6 June 2016
Release date: 23 December 2015
Release date: 23 December 2015
Release date: 22 December 2015
Release date: 1 September 2015
IMPORTANT: This release resets the OsmAnd access key and changes the TrackMe authentication! Please read the changelog and the FAQ, and review your new Trackserver profile for user-specific settings.
Release date: 29 July 2015
Release date: 15 June 2015
Release date: 29 April 2015
Release date: 15 April 2015
Release date: 8 March 2015
Release date: 28 February 2015
Release date: 20 February 2015
Release date: 12 February 2015
Release date: 10 February 2015
Release date: 2 January 2015