Skyost / AdSky

Monetize your Minecraft server 💰

---

Table of contents

1. Introduction
2. Features
3. Installation
4. Contributing
5. API
6. Support

Introduction

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.

Server part

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.

Plugin part

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.

Features

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 !}

Installation

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.

API

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).

Ads

Here are the available ad operations :

List all ads

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
   }
}

Get an ad

* /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
   }
}

Delete an ad

* /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
}

Pay for an ad

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"
}

Renew an ad

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"
}

Updates an ad

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
}

Plugin

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) :

Delete expired ads

POST /api/v1/plugin/delete-expired : Allows you to delete expired ads.

• "key" (string) : Plugin key.

Sample output :

{
   "error":null,
   "message":"Success.",
   "object":null
}

Get today's ads

POST /api/v1/plugin/today : Allows you to get today's ads.

• "key" (string) : Plugin key.

Sample output :

{
   "error":null,
   "message":"Success.",
   "object":null
}

Update

Below are the available AdSky update operations. These operations are accessible for administrators only :

Check for updates

* /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"
   }
}

Update

* /api/v1/update/update : Allows you to update AdSky.

No additional parameters needed.

Sample output :

{
   "error":null,
   "message":"Success.",
   "object":null
}

Users

Here are the available user operations :

List all users

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":"[e-mail]",
            "type":0,
            "verified":"1",
            "last_login":1526144440,
            "registered":1526136318
         },
         {
            "username":"SimpleUser",
            "email":"[e-mail]",
            "type":1,
            "verified":"1",
            "last_login":1526144710,
            "registered":1524926401
         }
      ],
      "page":1,
      "minPage":1,
      "maxPage":1,
      "hasPrevious":false,
      "hasNext":false
   }
}

Get a user

* /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":"[e-mail]",
      "type":0
   }
}

List a user's ads

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
   }
}

Delete a user

* /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
}

Update a user

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
}

Register a user

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":"[e-mail]",
      "type":0
   }
}

Login a user

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.

Logout the current user

* /api/v1/users/logout : Allows you to logout the current user.

No additional parameters needed.

Sample output :

{
   "error":null,
   "message":"Success.",
   "object":null
}

Contributing

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 !

Support

If you want to report a bug / suggest an improvement / anything else, do not hesitate to open an issue.