SimpleHTTPListener

Overview

SimpleHTTPListener is a simple plugin that I created to bridge Votifier and my website. It relays vote information from your server to a PHP API that you specify in the config. When a player votes on a voting site, like mcserverstatus or Minestatus, Votifier will then pass information to this plugin, which will report the vote information to your own API via a JSON-encoded HTTP POST request. SimpleHTTPListener was not designed to be an all-in-one solution - Votifier allows an infinite amount of listeners/listener plugins, and this plugin satisfied my need. However, the plugin still has an option to broadcast a message to the server upon a vote.

Requirements

• a CraftBukkit-enabled server with Votifier
• web-hosting space with PHP (and optionally MySQL) support

How It Works

SimpleHTTPListener reports vote information to a PHP API via HTTP POST. For example, if you decided to setup an API on http://example.com/doVote.php, you would enter that URI into the config.

SHTTPL encodes an array of information from Votifier into JSON and forwards it via HTTP POST as "request" to the configured URI. As a rudimentary security measure, the plugin includes a tokenKey (password) in the request that could be verified by the API.

Here is what a sample "request" looks like:

{"timestamp":"2013-06-21 02:29:12 -0700","username":"Test Notification","service":"Minestatus","key":"pleaseChangeMe","ip":"127.0.0.1"}

The JSON array

• key => "tokenKey" from config
• username => the username that the user entered on the voting website
• service => the name of my voting service
• ip => IP address of the user that voted
• timestamp => date/time of the vote

Note: timestamp is supplied by the voting website, so it could be a Unix epoch or a normal time depending on the website.

Installation/Config

SHTTPL does NOT get placed in the vote listeners folder despite its name. It is its own plugin, so you should place it in your plugins folder. It is NOT a substitute for Votifier - Votifier is still needed.

The configuration, as suggested by the plugin name, is moderately simple.

The request: section has to do with the HTTP request that the plugin will make.

• url: This is the location of your API. It must be a http: path, not /a/local/path. This location is where the "request" variable with the JSON-encoded data set will be sent. In PHP, it is simple to turn this into an array.
• tokenKey: This is the key that is forwarded to the API. There are no restrictions (length or charset) on the key, but in most circumstances a longer tokenKey increases the security of the system. If someone happens to discover your API URI, they will still need the tokenKey in order to abuse it. Make sure to change it from the default value.

The config: section has to do with miscellaneous settings.

• broadcast: boolean, if true, will enable broadcasting. If broadcasting is enabled and a vote is cast, the server will announce it to all players using the messageBroadcast message from below.
• messageBroadcast: this is the message that all players will see when a vote is cast if broadcast is enabled. The variable %n can be used for the username of the voter, and %s can be used for the name of the service.

Usage Scenarios

This plugin is very useful if you would like to create a voting highscores list on your website. Since it passes the vote information over to any external script, the possibilities are endless - it basically extends the onVote event to any medium that you have access to. PHP is a very powerful language and is recommended for writing your API.

APIs

In the near future, I will post my own API here. However, it is very easy to parse the data into a PHP array:

$vote = json_decode($_POST['request'], true);

The individual array elements can then be accessed by using standard array syntax. For example, this would open the 'ip' element:

$vote['ip']

Using PHP, you could send vote information to a database in any way that you like. This would then allow you to parse data in any way that you please, like creating a list of users that have voted for your server within the past month. It could also be used for analytic purposes - you could write a script that uses GeoIP to figure out where most of your votes come from geographically, or sort by the service name to see which service your server is the most popular on.