AdSky is a way for you, as a Minecraft server owner, to monetize your server. Currently, there are two kinds of ads : Title ads and Chat ads. Advertisers choose the type of ad they want to broadcast on your server, customize it (Title / subtitle, duration, display per day, ...), pay it according to the price you set up and voilà !
There are two parts : Server and Plugin.
The server part is a PHP + MySQL application that you install on your own web server, it is where advertisers will register and broadcast their ads. To see how to install it and the requirements, please check the Installation section.
Here is a screenshot of the administration panel.
The plugin part is a simple Bukkit / Sponge plugin that is going to link up with the server part. To see how to install it and the requirements, please check the Installation section of the plugin branch's README.
AdSky is built to be lightweight, but it still has a lot of features :
- Free and open-source.
- Can be run on almost any server that as PHP + MySQL installed.
- Everything is configurable.
- Lightweight.
- Android application. Coming soon !
To install the plugin part, please check the Installation section of the plugin branch's README.
To install the server part, you have to download the latest adsky-server.zip and unzip it on your web server. Once uncompressed, go to http://yourwebsite.com/adsky/install/ and follow the steps.
Please make sure that your web server meets the following requirements :
- PHP 5.6.0+ with the following extensions : PDO (
pdo), MySQL Native Driver (mysqlnd) and OpenSSL (openssl). - MySQL 5.5.3+.
- mail() and URL Rewriting support.
If you want to edit messages and the global look of AdSky, do not hesitate to edit .twig and .css files (located in core/views/ and assets/css/, respectively).
Oh, and I forgot one thing : everything is configurable. Just go to core/settings/ and open the PHP file you want.
AdSky server is provided with a little API. Below are the available methods.
Each of these will return you a JSON response containing : an error, a message and an object (all values can be null).
Here are the available ad operations :
POST /api/v1/ads : Allows you to list all ads on the server.
- "page" (int) : The page you want to see (optional).
Sample output :
{
"error":null,
"message":"Success.",
"object":{
"data":[
{
"id":16,
"username":"Skyost",
"type":1,
"title":"&lChat Ad",
"message":"&4Hi, this is a Chat Ad.",
"interval":2,
"expiration":1528156800,
"duration":-1
},
{
"id":12,
"username":"SimpleUser",
"type":0,
"title":"Wonderful Ad",
"message":"This is wonderful.",
"interval":4,
"expiration":1528761600,
"duration":6
}
],
"page":1,
"minPage":1,
"maxPage":1,
"hasPrevious":false,
"hasNext":false
}
}* /api/v1/ads/:id : Allows you to get an ad by its ID. You must be an admin to execute this on someone else's ad.
No additional parameters needed.
Sample output :
{
"error":null,
"message":"Success.",
"object":{
"title":"Wonderful Ad",
"message":"This is wonderful.",
"username":"SimpleUser",
"interval":4,
"expiration":1528761600,
"type":0,
"duration":6
}
}* /api/v1/ads/:id/delete : Allows you to delete an ad. You must either be an admin or the owner of the specified ad.
No additional parameters needed.
Sample output :
{
"error":null,
"message":"Success.",
"object":null
}POST /api/v1/ads/:id/pay : Sends a payment request to the PayPal REST API. An admin will see its ad immediately registered (if valid).
- "title" (string) : Ad's title.
- "type" (int) : Ad's type (0 for Title Ad, 1 for Chat Ad).
- "message" (string) : Ad's message (optional).
- "interval" (int) : Times to display ad per day.
- "expiration" (long) : Expiration date (in timestamp).
- "duration" (int) : Time to stay on screen (for Title ads), optional if you want a Chat ad.
Sample output :
{
"error":null,
"message":"Success.",
"object":"https:\/\/www.sandbox.paypal.com\/cgi-bin\/webscr?cmd=_express-checkout&token=XX-XXXXXXXXXXXXXXXXX"
}POST /api/v1/ads/:id/renew : Sends a renew request to the PayPal REST API. An admin will see its ad immediately renewed (if valid).
- "days" (int) : Number of days you want to add to the current expiration date.
Sample output :
{
"error":null,
"message":"Success.",
"object":"https:\/\/www.sandbox.paypal.com\/cgi-bin\/webscr?cmd=_express-checkout&token=XX-XXXXXXXXXXXXXXXXX"
}POST /api/v1/ads/:id/update : Allows you to update an ad (for administrators only).
- "title" (string) : New ad's title (optional).
- "type" (int) : New ad's type (0 for Title Ad, 1 for Chat Ad), optional.
- "message" (string) : New ad's message (optional).
- "interval" (int) : New times to display ad per day (optional).
- "expiration" (long) : New expiration date (in timestamp, optional).
- "duration" (int) : New time to stay on screen (for Title ads), optional.
Sample output :
{
"error":null,
"message":"Success.",
"object":null
}Here are the available plugin operations. These are special, because you do not have to be authenticated or anything,
but for each request you have to send the plugin key (see core/settings/PluginSettings.php) :
POST /api/v1/plugin/delete-expired : Allows you to delete expired ads.
- "key" (string) : Plugin key.
Sample output :
{
"error":null,
"message":"Success.",
"object":null
}POST /api/v1/plugin/today : Allows you to get today's ads.
- "key" (string) : Plugin key.
Sample output :
{
"error":null,
"message":"Success.",
"object":null
}Below are the available AdSky update operations. These operations are accessible for administrators only :
* /api/v1/update/check : Allows you to check for AdSky updates.
No additional parameters needed.
Sample output :
{
"error":null,
"message":"Success.",
"object":{
"version":"v0.1",
"download":"https:\/\/github.com\/Skyost\/AdSky\/releases\/download\/v0.1\/adsky-server.zip"
}
}* /api/v1/update/update : Allows you to update AdSky.
No additional parameters needed.
Sample output :
{
"error":null,
"message":"Success.",
"object":null
}Here are the available user operations :
POST /api/v1/users* : Allows you to list all users (for administrators only).
- "page" (int) : The page you want to see (optional).
Sample output :
{
"error":null,
"message":"Success.",
"object":{
"data":[
{
"username":"Skyost",
"email":"my@mail.com",
"type":0,
"verified":"1",
"last_login":1526144440,
"registered":1526136318
},
{
"username":"SimpleUser",
"email":"another@mail.com",
"type":1,
"verified":"1",
"last_login":1526144710,
"registered":1524926401
}
],
"page":1,
"minPage":1,
"maxPage":1,
"hasPrevious":false,
"hasNext":false
}
}* /api/v1/users/:email : Allows you to get a user. Put current in email to target current user.
You must be an admin to get another user.
No additional parameters needed.
Sample output :
{
"error":null,
"message":"Success.",
"object":{
"username":"Skyost",
"email":"my@mail.com",
"type":0
}
}POST /api/v1/users/:email/ads* : Lists all user's ads. Put current in email to target current user.
You must be an admin to list another user's ads.
- "page" (int) : The page you want to see (optional).
{
"error":null,
"message":"Success.",
"object":{
"data":[
{
"id":16,
"username":"Skyost",
"type":1,
"title":"&lChat Ad",
"message":"&4Hi, this is a Chat Ad.",
"interval":2,
"expiration":1528156800,
"duration":-1
}
],
"page":1,
"minPage":1,
"maxPage":1,
"hasPrevious":false,
"hasNext":false
}
}* /api/v1/users/:email/delete : Allows you to delete someone's account. Put current in email to target current user.
You must be an admin to delete someone else's account.
No additional parameters needed.
Sample output :
{
"error":null,
"message":"Success.",
"object":null
}POST /api/v1/users/:email/update : Updates someone's account. Put current in email to target current user.
You must be an admin to update someone else's account.
- "email" (string) : The new email (optional).
- "password" (string) : The new password (optional).
- "force" (boolean) : Allows to not enter "oldpassword" parameter, to edit the type and to not confirm the new email (for admins only, optional).
- "type" (int) : The new type (0 for admin, 1 for publisher), optional.
- "oldpassword" (string) : Password confirmation.
Sample output :
{
"error":null,
"message":"Success.",
"object":null
}POST /api/v1/users/register : Registers an account.
- "username" (string) : The username.
- "email" (string) : The email.
- "password" (string) : The password.
Sample output :
{
"error":null,
"message":"Success.",
"object":{
"username":"Skyost",
"email":"my@mail.com",
"type":0
}
}POST /api/v1/users/login : Allows you to login a user.
- "email" (string) : The email.
- "password" (string) : The password.
- "rememberduration" (long) : Remember duration in seconds (optional).
Sample output :
{
"error":null,
"message":"Success.",
"object":null
}Above is the JSON output. A cookie named PHPSESSID will also be returned and you must send it back at each request you want to send with a logged-in user.
If you have sent a rememberduration parameter, a cookie named remember_x[...]xx will be returned. You must also send it with the other one to keep the user logged-in.
* /api/v1/users/logout : Allows you to logout the current user.
No additional parameters needed.
Sample output :
{
"error":null,
"message":"Success.",
"object":null
}It's easy to contribute to AdSky ! If you are a developer, first, you have to create a fork and make your changes. Then make a pull request describing what are the improvements.
If you are not a developer, well, you can contribute as well ! Report bugs, problems and improvements in the Issues section. You can also contribute by making a donation.
Anyway, help is greatly appreciated under any form !
If you want to report a bug / suggest an improvement / anything else, do not hesitate to open an issue.