AdAdmin

Your easy adv server system.

Documentation

ver 3.5

INTRODUCTION

1 INSTALLATION

Requirements:

File installation and permission

Config the database connection

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 banner with a JPG / GIF / PNG imge

Creating a banner with a SWF (Flash) file

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

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 advertisings on sites, you can manage banners made with GIF, JPG, PNG, or SWF flash files, 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!


1 INSTALLATION

Requirements:

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

You must set the php ini to allow php short tags. (short_open_tag value in phpinfo() should be “On”).

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

File installation and permission

Unzip the adadmin.zip file on the root of your server, this should be the result in your document root directory.

You can have other stuff in your root (htdocs in the image) directory, but it’s important that AdAdmin software is in the root.

It can coexist with Wordpress in the same root.

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

/adadmindata/logs

/adadmindata/dbimg/7banner

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");

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 user, an admin and a guest user.

After the first login, change the predefined passwords for the admin and the guest users. 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 serve 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.

01-preview.jpg

As you can see there are these panels:

  1. Banner Details:

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

You have to specify a Link and you can decide if the link open in the same window or on a new window (this will use target=”_blank” in the html output code).

You can specify an image for the banner, and this image could be a JPG, a GIF, a PNG or an SWF file. Read the further subchapters for each case details.

Instead of an image file you could use an external script, such as the Google Adsense script or another script coming from your client. 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.

  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 banner with a JPG / GIF / PNG imge

This is the simplest banner type you can create in AdAdmin software: 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 banner with a SWF (Flash) file

AdAdmin supports SWF banners.

If you’re going to use SWF banners be sure to use the correct link inside the SWF file to track the click: when you make a flash banner you will use a button inside your file, on that button you will normally place a link and a getUrl call like this:

on (release) {
   getURL( "http://www.myclientlink.com", "_blank");
}

Instead of this code you should use the url provided by AdAdmin software:

So the correct code to put in the SWF banner is:

on (release) {
   getURL( "http://www.mydomain.com/adtrack.php?b=1102", "_blank");
}

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

As you can see in the code above the ActionScript code of getURL functions already has a target, so this setting will be used and the setting of the AdAdmin will be bypassed.

To get the link for your SWF banner, you have first to create the banner (without the SWF file), so you can determine the correct link to use in your flash ActionScript file. 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 “tracking link”.

Get the “tracking link” and put it in your SWF file (you need a Flash editor to edit the initial FLA file and compile it to get the SWF file to use).

When you have your SWF file with the correct link you can proceed and upload it in AdAdmin:

If you use an SWF banner remember to provide also an alternative version of your banner, for example a JPG image file, because some devices (iPhones and iPads) will not show SWF file. For those device AdAdmin software will deliver the JPG version instead of the SWF file.

Choose another file to be uploaded, which is the alternative JPG version for iPhones and iPads, press “Save and reopen” and this will be the final correct situation:

There are both an SWF file and a JPG file.

If you don’t upload the JPG static image for the SWF banner you will have an empty banner on iPhones and iPads. Moreover, impressions are calculated but banner is not seen on that devices, so reports and data are wrong and partial if you don’t upload the static JPG file.

 

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.

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

Position’s width and height are used only for SWF banners because the flash file hasn’t these informations inside itself.

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:

New features: