AdAdmin

Your easy adv server system.

Documentation

ver 3.73

Software available on CodeCanyon:

https://codecanyon.net/item/adadmin-easy-adv-server/12710605


INDEX

INTRODUCTION

1 INSTALLATION

Requirements:

File installation and permission

Config the database connection

Config the date format

Database installation

First login

2 HOW IT WORKS

3 Menu commands

4 Banners and positions

The banner dashboard (banner list)

Creating a banner

Creating a simple banner with a JPG / GIF / PNG image

Creating an HTML5 banner (also responsive)

Creating a banner with an external script (such as Google Adsense)

Show data collected and reports

Creating a position

5 Clients and campaigns

Create a client

Add guest user to a client

Creating a campaign

6 Users

Profiles

Create a user

7 Next features

8 HOW TO UPDATE THE SOFTWARE TO LAST VERSION


INTRODUCTION

Do you have a growing website and you’re going to sell banners? Are you already selling adv positions on your site? Do you need to track impressions and clicks on banners in an easy way?

This software is and adv-server, a software that manages advertising on sites, you can manage banners made with GIF, JPG, PNG, or HTML5, or external scripts (such as Google Adsense). You can create different positions and manage multiple banners on each positions, which are automatically rotated.

Here is a full list of the features:

This software has been tested on server with over 1 Million users each month! It’s optimized!

You can download the AdAdmin software from CodeCanyon:

https://codecanyon.net/item/adadmin-easy-adv-server/12710605


1 INSTALLATION

Requirements:

Linux server with php (not tested on windows server, it should work too).

From version 3.7 AdAdmin is compatible with php 7.x.

You must be able to chmod some directories to set write permissions.

File installation and permission

You can unzip the adadmin.zip file on the root of your server (like in the image below) or you can unzip it in a subfolder, this should be the result and the adadmin dir content:

Since version 3.73 the assets directories have changed and now all the files are inside the “adadmin” folder and doesn’t need mandatory to be placed in the root.

This way it’s cleaner with other software on the same server.

Remember to CHMOD 777 or 755 (it depends on your server configurations) these directories (they should be writeable):

/adadmin/data/logs

/adadmin/data/dbimg/7banner

If you’re upgrading an installation please read the section: HOW TO UPDATE THE SOFTWARE TO LAST VERSION.

Config the database connection

Open the pons-settings.php file and config the database settings with your specific mysql configuration. You have to change only these lines:

define("WEBDOMAIN",    "localhost");

define("DEFDBNAME",    "testadadmin");

define("DEFUSERNAME",  "testadadminuser");

define("DEFDBPWD",     "testpassword");

Config the date format

Open the pons-settings.php file and config how to show date formats inside the AdAdmin software:

define("DATEFORMAT",    "mm/dd/yyyy");

At this moment formats allowed are "mm/dd/yyyy"  and  "dd/mm/yyyy"

Database installation

Once you have configured the database connection in pons-settings.php file you can run the install.php, to run it simply load it in the browser (if you have installed it on http://mydomain.com/ the url for install is http://mydomain.com/install.php), this is the correct output:

Click on “here” and go to the login page.

The install.php script creates the tables in the configured database, and creates default data for client, banner position and banner campaign (read more to understand these terms).

The install.php creates also two users, an admin and a guest user.

After the first login, change the predefined passwords for the admin user. For security reasons it’s also recommended to delete the install.php file.

First login

To make the first login and create banners use this account:

user: admin

pwd: admin


2 HOW IT WORKS

An adv server works by serving ads, this job is done with a group of javascripts (one for each banner position) to be placed in your site. The javascript calls the AdAdmin server and shows the banner, tracks the impressions and the clicks.

The AdAdmin software lets you serve banners to many sites or just one if you want.

You can place AdAdmin on a server and deliver banners to sites on other servers, or put the AdAdmin on the same web site where your site is (it can coexist with CMS like Wordpress):

Or on a different server and deliver banners to many sites:

The AdAdmin software works by defining “Positions”. Each “Position” is a banner position on a site and when you create a “Banner” you have to specify which position it will use. If you add two banners with the same position the software delivers both banners, by rotating them on that position: one time it will show Banner 1, next time Banner 2, then again Banner 1, then Banner 2, then Banner 1… and so on.

To deliver banners on a site you will place a javascript script on your site where you want the banner to appear. Lets see again the example with 2 banners on a position.

Suppose that the position is “300x250” placed on the top right your pages:

This means that in that site in the right sidebar there is this code:

<script src="http://www.mydomain.com/adserve.php?f=1">/*300x250*/</script>

This code calls the AdAdmin server software (adserve.php) which searches for the specific banner position (f=1) that is a 300x250 position and print out the first banner (which shows only a “click here” stupid jpg).

If you create two banners with 300x250 position they will be rotated on that position. Each time the page is loaded a rotation is made. To see the two banners you have to refresh the page.

Banners are delivered until the ending date is reached or the maximum number of impressions are delivered.

This is the core of the software.

Lets see more details in the next chapters.


3 Menu commands

This is the menu, which is placed in the top right corner of the window and is normally collapsed.

        


4 Banners and positions

The banner dashboard (banner list)

When you log in in the AdAdmin software you will see the list of your banners (when you have just installed the software this list is empty):

For each banner are shown Banner title and belonging Campaign, From - To dates, the total  number of days between the 2 dates, the daily average impressions delivered for the banner,

the number of clicks and the CTR (Click Through Rate). The “Position” of the banner and the Status which can be Serving or Ended. There is also a “Serving*” with an asterisk * which means that the banner is the last one delivered for that “Position”.

The commands are Edit, Chart, Duplicate record, Delete record.

The top control panel has some simple commands:

You can filter the banner list with top left select control which filter banner for its status and position.

You can search banner using the “Find” field in the top control panel.

You can add a new banner and delete a group of banner using the checkbox on the left in the list and the Delete selected command.

A refresh command is provided to easily refresh the page and see counters change.

Creating a banner

This is the screenshot for the creation of a banner. The same page is used in update view.

As you can see there are these panels:

  1. Main data:

Here you will see the ID of the banner and the generated Click Tag (for HTML5 banners) and you can specify the “Position” of the banner.

You can decide to turn it on or off with the Status selection (“Serving or Ended”).

You can choose a Title for that banner and a Campaign. Banners are grouped in advertising campaigns.

  1. Banner details:

You can create banners in three ways.

Simple banners: banners made with an image (GIF, JPG or PNG files allowed) and a link. Upload the proper image file (match your banner image size) and fill in the destination link.

HTML5 banners: banners made with HTML code, you can use images and javascripts. The creativity can be uploaded with a ZIP file. Read the further subchapters for each case details.

External code: banners made with javascript code (or external scripts) that deliver ads from another servers, like the Google Adsense code.

If you’re going to use external scripts read the related subchapter.

  1. Limitations:

In this panel you can specify how long this banner will be shown, you can decide the starting (From) and the ending (To) date (the dates are included).

You can also decide to put a Total impressions limit for a banner (suppose you want to limit to 100.000 the total impressions for a banner, you can specify it here).

When the banner reach the limit (the total limit or the ending date) it will automatically change its status to “Ended”.

You can also specify a Daily limit, that is to say that you can limit the number of impressions of a banner in a day. When the banner reach this daily limit the banner is no longer served for today but it will remain in the status of “Serving” and will be delivered again tomorrow.

For example you can put 100.000 impressions as total limit and 10.000 as daily limit. So, if you have a lot of traffic you can prevent the banner to consume all the impressions in a small period.

You can also limit the total number of clicks on that banner, so you can sell banner linked to their performance (the number of click received). If you put 100 clicks as limit, for example, the banner will stop when receive 100 clicks.

The limits work together, so you can place a banner which has a period limit a daily limit a total impressions limit and a number of clicks limitation.


  1. Stats:

In the stats panel there is a small report of the performance of your banner, which shows the current number of impressions delivered, the clicks tracked and the performance (CTR, Click Trough Rate).

Creating a simple banner with a JPG / GIF / PNG image

This banner is created by AdAdmin software using one image file and a target link.

This is the simplest banner type you can create: select an image from your computer and upload it. Be sure to match the dimensions for the Position you have selected. That is to say: pay attention to upload a 300x250 banner in a position created for a 300x250 banner. If the banner is a 728x90 pixels banner don’t upload it in a 300x250 because this could cause problems to your site (break the template or appear stretched).

To deliver this banner the AdAdmin server will output an HTML code which shows the image with a particular link that tracks the click of the user.

Creating an HTML5 banner (also responsive)

AdAdmin supports HTML5 banners. They must be uploaded in a ZIP archive.

The ZIP file must include an index.html (the filename is important) file which compose the creativity, it could use images files (jpg, svg, png, gif) and could use additional css file and javascript file. If you prefer you can also include JS and CSS code inside the index.html file (it will be faster for delivery!).

HTML5 banners are delivered with an iframe html tag that points to the index.html file, this iframe tag will have a fixed dimensions or a liquid (100% width) dimension based on the settings of the position. The liquid dimension is needed for responsive HTML5 banners.

All files in the ZIP archive must be at the same level and the archive must not contain any folder. Seen with WinRar here it is an example of the content of the ZIP file:

Inside your code remember to use the ClickTag provided in the Main Data of the banner detail page.

Instead of the link (anchor tag) of the client inside your html code put the ClickTag url.

In this way the AdAdmin software will be able to track the clicks made on the HTML5 banner. If you don’t use this trick your banner will still work but AdAdmin will not track clicks.

The link in the HTML5 banner has its target (window), so this setting will be used and the setting of the AdAdmin banner details data will be bypassed.

To get the ClickTag for your HTML5 banner, you have first to create the banner (save it without the ZIP file), so you can determine the correct link to use in your html code. You need the ID to get the link, and the ID is available after creation:

So fill in the form without any file and “Save and reopen”:

Now you have an ID and a “ClickTag”.

Get the ClickTag and put it in your HTML5 banner, in the index.html file and create the ZIP the archive.

When you have your ZIP file with the correct ClickTag you can proceed and upload it in AdAdmin.

Extra info for responsive banners

If you want to create a responsive banner you must create the appropriate rules in your css. You have to use the design media queries inside your CSS rules to enable responsive behaviour.

The AdAdmin software allows you to made responsive HTML5 banners and you have to place them in a responsive banner position.

Responsive banner example

You can find an example of a responsive HTML5 banner in the banner-example.zip included in the package, or you can download it from this link http://www.barattalo.it/adadmin/example/banner-example.zip.

It’s a simple banner with index.html, an image and a readme.txt file. Inside the index.html page there is also css for responsive media query rules and a few lines of javascript to open the ClickTag in a new window.

Creating a banner with an external script (such as Google Adsense)

You can create a banner with an external script by simply inserting the script code in the Alternative script text area.

By doing this the ad server will output (in the specified position) this Alternative script instead of the normal output of the software. When you use the Alternative script you don’t need to insert any images or links, since the banner is the alternative script.

When you use external script you can’t track clicks, but you can still track impressions.

Remember to put in the textbox only the script that shows the banner. Sometimes advertising agencies give you different scripts in a single text file, you have to place in the textbox only the javascript, normally is a block of code between <script and </script> tags.

Show data collected and reports

From the main page with the banner list you can click on the Chart link on the right to get a panel with a report of the last 30 days stats. This panel shows impressions and clicks.

The period can be changed with the controls at the top of the page, you can choose two dates to define the period.

Data are also grouped, so you can see stats for a single Banner or for all the banner of a specified Campaign.

(NOTE: This is an old screenshot, now there are also the controls to choose the period)

 

Click on “All” to see the grouped chart for the Campaign:

(NOTE: This is an old screenshot, now there are also the controls to choose the period)

Creating a position

When you go to the main menu and click on the “Positions” menu item you will see the positions list. This is an example:

In this list you can see that there is a position named “300x250” (it’s the default created in the installation process). If you click on the pencil icon to see the details you can also see the script code that you have to place in your HTML to show the banners:

You have to copy the grey code from <script... to </script> and place it in the sites where you want to deliver banner.

The check flag for “responsive” is normally flagged and it’s used to give a liquid width to simple banners and to HTML5 banners.

If checked:

1) the width of the simple banners will be 100% and height auto;

2) the width of the HTML5 banners will be 100% and height fixed to specified height.

This behaviour could affect the layout of your site (note that there is a difference).

To use a responsive banner position and make a banner that transforms from a 300x250 to a 900x250 check this flag and then use HTML5 code to handle different window sizes inside your banner, through css media queries.

When you flag the responsive checkbox the width will be forced to “-1” and you can’t edit it. It will be controlled by the HTML5 code or by the layout of the site.

Each position that you create will be available in the position selector when you create/edit a banner:

5 Clients and campaigns

Banners are displayed in Positions. Banners belong to Campaigns. And a Campaign belongs to a Client. So, when you create a banner you have to specify a campaign and this will determine the client.

When you click on the “Campaigns” menu item, you will get the list of campaigns, like this:

Mycampaign is the default campaign created in the installation process.

With the pencil icon you get the Campaign detail:

You can choose the Client who this Campaign belongs to and you can specify the Status of the campaign. Campaigns turned OFF still show banners!  By turning OFF a campaign you will hide it from the banner detail so you can’t choose a turned OFF campaign in new banners.

Create a client

When you click on the “Client” menu item you get the client list:

Myself is a default client created in the installation process.

In the client detail view (you get it by clicking on the pencil icon) you can manage the name of the client and the users who can see the details of a banner as guest users.

Add guest user to a client

In the Client detail view you can select “guest” users to view the banner statistics for a banner or a campaign. This feature is useful if you want to let your client see by himself the performance of his banner.

He will be able to see how many impressions are delivered daily and how many clicks there are for each banner.

Choose the user from the right list and press “<< Add“ to enable the guest user to see its banners. Then manually send an email with user and password to the user (at this moment, this is not a feature of the AdAdmin software, so you have to send the email by yourself outside the AdAdmin software).

Creating a campaign

A Campaign is a group of Banners. You can create groups as you want, for example: you can create a Campaign for a music festival, this group of banners contains 3 banners, which are a bit different one from each other, then put the 3 banners on different sites.

Since these banners are grouped in a Campaign you will be able to see statistics for each banner and for the group of banners (the Campaign).

In the detail view of the Campaign you can see that a campaign is connected with a Client.

Turning OFF a campaign will limit the usage of that Campaign for new banners.

In the stats view of a banner you can switch to the global campaign view by selecting the “All” item in the select menu:

(NOTE: This is an old screenshot, now there are also the controls to choose the period)


6 Users

Profiles

When you install AdAdmin software the installation process will create two users with two different profiles, an admin user and a guest user. Admins can do everything: create, edit and delete banners, campaigns, positions, clients and users.

Guests users can only see banners and campaigns stats of a specified client.

Admin user is named Gengis Kahn (user and passowrd for login is admin/admin) and the guest user is John Snow (user and passowrd for login is gu/gu).

Create a user

When you open the Users view in the main menu you will see this list, where you can edit/delete the existing users or you can create new users.

You can create other admins user and you can create guests users and connect them to clients to let your clients login and see stats.

In the User list there you can click on the pencil icon to edit the user, the second icon is to edit more details and the trash icon is for delete, as it is in other lists (banners, campaigns, etc.).

Above the list there is a button to “Add a new user”.

Here is the user detail view:

These are the main user details, the flag Active user let you deactivate user without deleting him. I will not be able to login.

As you can see at this moment password has not any strength check, you can type any password you want.

In the More informations detail you can add the user email (it will be used in the future for automatic sending emails and reports to the users, but at this moment isn’t yet used).

You can also save the creation date  for the user (at this moment this information isn’t used in the software).

7 Next features

Some improvements are planned for this software, here is the list:

Please refer to CodeCanyon page to complete list of versions and features.

https://codecanyon.net/item/adadmin-easy-adv-server/12710605

8 HOW TO UPDATE THE SOFTWARE TO LAST VERSION

When you buy your own license from CodeCanyon store (here is the AdAdmin page: https://codecanyon.net/item/adadmin-easy-adv-server/12710605) you will also receive future updates to the software for the period you choose.

If you’re upgrading from a version lower than 3.73 to a grater version (>3.73) please follow carefully these steps:

  1. Rename adadmin dir with “__BACKUP__adadmin”
  2. Rename adadmindata dir with “__BACKUP__adadmindata”
  3. Rename adserve.php file with “__BACKUP__adserve.php”
  4. Rename adtrack.php file with “__BACKUP__adtrack.php”
  5. Rename pons-settings.php file with “__BACKUP__pons-settings.php”
  6. Unzip the new adadmin folder from zip file
  7. Open the new pons-settings.php file which now is inside “adadmin” folder and update database settings
  8. Move files from old __BACKUP__adadmindata/dbimg/7banner/* to adadmin/data/dbimg/7banner/*
  9. Check for permissions 777 to adadmin/data/dbimg/7banner/ and adadmin/data/logs/7banner/
  10. Log in to new adadmin and check if everything works.
  11. From this version the url to get banners changes a little, so on sites where you’ve placed the script to retrieve adv banners, must be changed as follow.

From:

<script src="http://www.yourdomain.com/adserve.php?f=9">/*300x250*/</script>

To:

<script src="http://www.yourdomain.com/adadmin/adserve.php?f=9">/*300x250*/</script>

  1. When everything is ok with your test you can safely remove all the __BACKUP__ files.

If you’re upgrading form a version greater than 3.73 it’s easier!

When I release a fix or a new version on CodeCanyon you will receive an email from CodeCanyon and you will be able to download the new version.

Unzip the new package and overwrite all files from the ZIP archive on your server except the  pons-settings.php  in the AdAdmin main folder.

Just replace old files with the new ones.