AdAdmin

Your easy ad server system.

Documentation

ver 3.94

Software available on CodeCanyon:

https://1.envato.market/adadmin


INDEX

INTRODUCTION

1 INSTALLATION

Requirements:

File installation and permission

Config the database connection and run database installation

First login

Check Settings

2 HOW IT WORKS

3 Menu commands

4 Banners and positions

The banner dashboard (banner list)

Creating a banner as an Administrator

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

Creating a responsive banner with 2 images and Templates

Creating an HTML5 banner (ZIP)

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

Show data collected and reports

Config GeoIP feature

Creating a position

5 Clients and campaigns

Creating a Campaign

Campaign statistics

Create a client

Add an advertiser user to a client

6 Users

Profiles

Create a user

7 Selling process with Advertisers

Configuring

Define sellable positions

Kart and checkout

8 Multilanguage support

9 Next features, TO DO planning

10 HOW TO UPDATE THE SOFTWARE TO LAST VERSION

FOR NEWER VERSIONS

FOR OLD VERSIONS


INTRODUCTION

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

This software is an ad-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 position, which are automatically rotated.

Here is a full list of the features:

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

You can download the AdAdmin software from CodeCanyon:

https://1.envato.market/adadmin


1 INSTALLATION

Requirements:

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

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 (you can rename the amb folder to match your poreferred address, do not use “ad” or “banner” strings in the url to prevent adblocking software):

Assets directories are inside the “amb” folder and they don't need mandatory to be placed in the root of your web server.

Remember to CHMOD 777 or 755 (it depends on your server configurations) these directories (must be writable, php user must be able to create, edit and delete files):

/adadmin/data/logs

/adadmin/data/dbimg

/adadmin/data/geoip

If these folders are not writable, please manually CHMOD 755 or CHMOD 777 those directories.

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

Config the database connection and run database installation

After unzipping the file go to the browser and load www.yourdomain.com/yourfolder, if your domain is www.test.com and you have placed everything in the /amb folder put this address in the browser:

www.test.com/amb

This will load this page:

Insert your db data and click on “Proceed”. This script will insert data in the pons.settings.php file. If everything works fine you will see this:

Click on proceed to run database installation queries.

You will see this screen at every update we will be distributing on CodeCanyon.

First login

We have automatically created some banners, positions, campaings and clients to start with a working set like in our demo. There are also two users, one admin and an advertiser:

user: admin                                ADMINISTATOR

pwd: admin

user: gu                                ADVERTISER

pwd: gu

Check Settings

After the first login navigate to Config > Settings as admin and set up the variables needed:


2 HOW IT WORKS

An ad 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:

<div id="AAVDIV1"></div><script src="http://www.mydomain.com/adserve.php?t=AAVDIV1&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. Some items may change with software version.

        


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 “Position” of the banner and its selling mode (CPM/CPD/CPC) and the Status which can be Serving or Ended  or Paused or Scheduled (if you’re selling banenrs there will also be Not Paid and Pending). There is also a small preview of the banner, if -instead of the preview- there is an icon the meaning is:

 html 5 banner uploaded with a zip file.

 script banner with inline html/js

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

The top control panel has some simple commands to filter the banner list based on status, position, client, campaign.

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

You can add a new banner and delete a group of banners 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 as an Administrator

Here is the screenshot for the creation/update of a banner.

As you can see there are these panels:

  1. Main data:

When you edit a banner you will see the ID of the banner and the generated ClickTag (for HTML5 banners). During creation ID and ClickTag are not visibile.  You can specify the “Position” of the banner.

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

There is also a Paused status which can be used to temporary block a banner from being viewed.

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

When you sell banner near the status you will also see indication about the price model used for selling this ad position:

  1. Banner details:

You can create banners in three ways.

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

Script: Instead of a simple banner, you can create a block of HTML code to show a banner, here you can place also an external service code, such as the Google Adsense script. We’ve also implemented “templates” to easily add a scripted banner to handle, for example, responsive banners, overlays, etc..

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.

  1. GeoLocation:

In this panel if you’ve activated the geolocation with ip address feature you can specify a geographical target for your banner.

When you choose this targeting method, every time a banner with geolocation value setted should be displayed the software checks if the ip of the current user is in that location. If it is, it shows the banner. If it isn’t the banner is skipped, the view isn’t counted and another banner is displayed.

See Config GeoIP for more information.

  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 reaches 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 reaches 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 from consuming all the impressions in a small period.

You can also limit the total number of clicks on that banner, so you can sell banners linked to their performance (the number of clicks received). If you put 100 clicks as limit, for example, the banner will stop when it receives 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.

In limits there is also a “Redux factor” that can be used to fine tuning banner views by:

Suppose you have two banners in the same position. If one banner is more important you can reduce the number of views of the less important one so that the more important is more visibile. If the banners have the same value you can leave “No reduction” as the selected redux factor.

There are also limits to show banners only on mobile devices or desktop browsers, normally banners are shown to both desktops and mobiles.

Frequency cap allows you to show a banner a defined number of times per user per day. Normally there aren’t limits. This can be useful if you use for example overlay banners that cover your content, since they can be annoying.

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

If you’ve filled the price field with a value in the Main data, here you can see the resulting CPM (cost per mille impressions, or cost for thousand) the CPC (cost per click) the CPD (cost per day).

Values are calculated in realtime, so you may reload the page and find different results, at the end of the campaign you will see the correct value of your banners.

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

Simple 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 a responsive banner with 2 images and Templates

You can create a responsive banner with 2 images, for example one for small screens and one for desktops. This is, for example, a MASTHEAD banner, with resolution 970x250 on desktop and 320x100 on mobile. To make this job you have to use the Script text area and input here the correct HTML code to display the image.

To simplify this process we’ve created “Templates”. Choose a template and the code will appear in the Alternative script text area.

The code in the script section contains some special codes that are changed by AdAdmin during the delivery process.

Here is the complete lists of the codes supported:

Can help. This code is sobstituted with the ID number of the banner.

The “Responsive banner with 2 images” template is a responsive bannner that can be used to deliver Mastheads, Leaderboards and other classical formats that have a size for desktop and a size for mobile.

Creating an HTML5 banner (ZIP)

AdAdmin supports HTML5 banners.
These banners are more complex and can be used to make banners that contain videos or animations. You must code the banner by yourself (
note: for a simpler responsive banner, you can use the Alternative Script text area and the Template select, see “Creating a responsive banner with 2 images and Templates”).


The HTML5 banner must be uploaded inside 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 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 with HTML5 and ZIP files, 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 make 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 an 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 is also grouped, so you can see stats for a single Banner or for all the banners of a specified Campaign.

 

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


Config GeoIP feature

To use geo location to target banner views you have to download the IPs free database (or buy the more precise one) from this site https://lite.ip2location.com/ . The process is easy:

  1. Register and then go to Download page. Copy your personal “Download Token”.
  2. Choose if you want to geo target countries or also regions and cities:

DB1LITE contains information for contries only. It’s small and it’s the best choose if you have to target traffic by country

DB3LITE contains information for countries, regions and cities. It’s quite big (uncompressed it’s 200MB) and containse 2.9M of rows.

  1. Then go to AdAdmin > Config > Settings, and click on GEOIP_TOKEN to insert your personal Download Token and choose db type in the  GEOIP_CSV parameter:

If you choose DB3LITE with also data for regions/cities, you can limit the database to use only the data from a country (suppose you are in Italy and you want to show banners on different regions of italy). To limit the DB3LITE database to Italy, for example, put the code IT in the GEOIP_LIMIT_COUNTRY setting value.

  1. Once you’ve added the GEOIP_TOKEN, choosen the GEOIP_CSV and GEOIP_LIMIT_COUNTY you can click  on the Get Update button.

This will download the csv and import records. If you use DB3LITE db setting this action will take a while. A loading gif is showed and you can see progress.

IMPORTANT TIP: If you are interested in only 1 country region/city data, import everything and then manually delete the records not belonging to your country. This will speed up all the queries.

If you need help you can ask in the AdAdmin Codecanyon forum or write directy to me for support.

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 <div id=... to </script> and place it in the sites where you want to deliver banners. Just click on the code to copy it.

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 320x100 to a 900x250 check this flag and then use HTML5 code to handle different window sizes inside your banner, through css media queries. The iframe containing the banner will be resized to match the height defined inside of the banner.

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:

The flag “Available for purchase” lets you sell the ads in this position, and make this position available to advertisers. When you sell banners you have to specify the price.

There are three price models available:

  1. CPM
    Banners are sold with a price for 1000 views. CPM stands for Cost Per Mille impressions. It’s the cost for 1 thousand impressions.
  2. CPC
    Banners are sold with a price for 1 click. CPC stands for Cost Per Click.  You define the price for 1 click.
  3. CPD
    Banners are sold on a daily basis, CPD stands for Cost Per Day. So you decide a price for one day.

These data will be used to calculate the price during the sell process of the advertiser.


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.

Creating a Campaign

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

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.

TOTALLY OFF also stops serving ads.

Campaign statistics

From the campaign list you can click on the chart icon to see the graphic daily chart of banner views and clicks.

You can change start and end date and filter for each single banner of the campaign. You can also export all the chart data to CSV format for your custom analysis.

Create a client

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

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 an advertiser user to a client

In the Client detail view you can select an “advertiser” user 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 select list of available users (each user can handle only one client):

6 Users

Profiles

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

Advertiser (if payments setting is ON) can buy ads, create campaigns and see stats.

If payments are OFF Advertiser users can only see their banners and campaigns stats.

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 users 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 lets you deactivate the 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 information 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 Selling process with Advertisers

Configuring

Since version 3.94 AdAdmin supports the selling process of ads with Paypal payments.

To sell banners in your AdAdmin software you need a Paypal account, login in Paypal developer account dashvboard: https://developer.paypal.com/developer/accounts/

Create an application and get your credentials: Client ID and Client Secret.

Put these settings in your AdAdmin settings in the section PAYPAL_CLIENTID and PAYPAL_SECRET.

With Paypal you can use a “sandbox” server to test the system or you can use the “live” server to sell.

Use the sandbox to make test wiithout spending real money, Paypal will give you fake accounts with fake money to perform every test you want.

When you activate Payments in settings mode there will be a link to create a new user in the login page:

New users can sign in autonomously and buy ads.

Define sellable positions  

You must configure some position to be sellable, because each position isn’t automatically sellable. You need to go to positions and edit the position that you want to sell. You have to define the selling model (CPM / CPD /CPC) and price.

Kart and checkout

When payments are ON users can sign in, create a campaign and buy ads.

The process is composed of a few simple steps:

  1. The advertiser user create a banner.

Fill in the data in the banner creation form, upoad images, insert link...

Specify the price he wants to spend.

The system calculates the views or the days (it depends on the selling model) and if it has enough data it will also show the approximately the duration of the banner (for CPC and CPM).

Specify the geoip targeting (if it’s available), frequency cap and technological targeting (mobile/desktop)

The advertiser can specify also the starting date for the banner

  1. The user proceed to checkout

When the user clicks on the Paypal button the payment process starts on Paypal server.

The user comes back to its banner list and the banner is saved as “Pending”.

  1. The Administrator check the banner uploaded by Advertiser.

You should check if target link is ok for you, and if the pictures or the scripts uploaded are ok.

  1. If the banner is fine, the Administrator changes the status from Pending to Serving and the banner is shown to visitors on your site.

8 Multilanguage support

AdAdmin is available with two languages file “English” and “Italian”.

To change the language open the pons.settings.php file in AdAdmin main folder and change the line with:

define("LANGUAGEFILE",'en.lang.txt');

Available languages file are en.lang.txt and it.lang.txt.

If you want to create a new language file you can save a copy of english file, open it with a text editor, it’s a CSV file, the first column is the label and the second column is the translation in your language.

Open it file to better understand. :)

9 Next features, TO DO planning

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

Do you have a feature request?

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

https://1.envato.market/adadmin


10 HOW TO UPDATE THE SOFTWARE TO LAST VERSION

When you buy your own license from CodeCanyon store (here is the AdAdmin page:https://1.envato.market/adadmin ) you will also receive future updates to the software for the period you choose.

FOR NEWER VERSIONS

If you’re upgrading from a version greater than 3.73 it’s easy!

Rename your pons-settings.php file to pons-settings.php_OLD Unzip the new package and overwrite all files from the ZIP archive on your server.

Open the pons-settings.php file in the AdAdmin main folder and place here your database settings from the _OLD file. (Only DB settings!)

Run again the new install.php file (it will make some database changes if needed).

NEW VERSION 3.85 NEED ALSO A POSITION CODE UPDATE:

From:

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

To:

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


        Change
UNIQUEID to a different name for each position, keep the correct f parameter for each position.

FOR OLD VERSIONS

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 the 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 ad banners, must be changed as follows.

From:

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

To:

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


        Change
UNIQUEID to a different name for each position.

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