plx Ad Manager v1.6
Administrator Guide

Content

Install using Setup Wizard

^ top ^
You can use the Setup Wizard that comes with the script or if you want to take full control of what's happening and if you are familiar with script installation you can do it yourself manually. Here are the installation steps when using setup wizard:
  1. In the ZIP pack you have downloaded from our site there are 2 files (readme.txt and setup.txt) and one folder named upload. In this first step you need to upload the content of this folder (not the folder itself) to your server. You can use any FTP Client for this purpose. If you're not familiar with FTP clients and how they work don't be afraid, it is very easy. Most of the FTP programs are with explorer-like interface and come with full help to assist you. Here are some FTP clients that we prefer: Flash FXP, CuteFTP
  2. After you upload the script on your FTP you should change write permissions for the file db.php and the folder backup. These both should be write-enabled. Use FTP command CHMOD(777). Refer to your FTP client documentation on how you can change files and folders permissions.
  3. Navigate to (load in you browser) the setup wizard of your newly uploaded script. The URL should be anything like that: http://your_site_url/path_to_script/setup.php
  4. Now you need only to follow the setup steps in this wizard. You will need to know your database details (host, port, username, password), provided by your hosting company.
  5. After the setup is complete use your FTP client to delete the files setup.php and setup.sql from your server. It is important to delete these files because if they are left there it is a big security hole in the script (anybody can use the setup wizard and ruin your installation)!

Manual Installation

^ top ^
To install the script manually you should be familiar with script installation and database management (using MySQL control panel):
  1. Create a database of your choice on your server. Alternatively you can use existing database, in this case note that the tables of plx Ad Manager script are using pst_ prefix.
  2. Import the file setup.sql to the newly created database.
  3. Add 1 admin record using the following sql querry:
    INSERT INTO `pst_staff` VALUES (1, 1, 1, 'your_name', '', 'username', MD5('password'), '', '', '', '0', '', '', '', 0);
    Replace your_name, username and password with details of your choice. These details will be used for login in admin area of the script.
  4. Edit the file db.php (found in upload folder). The file content should be:
    <?php
      $db['db'] = 'db_name';
      $db['host'] = 'db_host';
      $db['user'] = 'db_username';
      $db['pass'] = 'db_password';
    ?>
    Use your database settings here (in place of db_name, db_host, db_username, db_password). If your MySQL server is using port different than default (3306) then for db_host use db_host:db_port.
  5. Upload the content of the folder upload (except the files setup.php and setup.sql which are used by the setup wizard) to your server.
  6. Load the newly installed script in your browser (http://your_site_url/path_to_script/) and login using the admin details (set in step 3). Go to Settings-Settings page in admin area and modify the script settings as you need. Note that there you should choose the time-zone of the server where the script is installed. This is used for the users to see real stats without shift in the time because of the time difference (between user's time zone and the time zone of the server).

Quick Start

^ top ^
With this quick start guide we will show you how you can start using the script in few simple steps. This is the essential of what you need to do to run and use the script.
  1. If you didn't do that already, login to admin area and change your site settings (go to Settings-Settings in admin area).
  2. Define web sites that will use this Ad Management script. Go to Lists - Web Sites. There you will see the list of the sites already added in the database. To add new web site to the list use the button (or the link) New Web Site. For any web site you will enter only 2 fields - Domain/Title and Description. Anywhere in the script the web sites are displayed by their domain/title. Description field is used only for your own reference.
  3. If you need you can add user account(s) with access Level 2 - Site Manager. For these users you can select web sites that they can manage and they will be limited only to this selection. This means they will be able to manage ads only for the web sites you allow. Site Manager can not modify the list of web sites he can manage, he can only change the details of the web sites already assigned to him. Comparing with Level 1, Site Manager doesn't have access to script settings and he can only add users of Level 3 (Advertisers). In users accounts list he will see only the Advertisers added by him and his own account (he can edit his account details).
  4. Add new ads - go to Manage Ads - Add New Ad. Enter the details for your ad, select the type of the ad and set the properties needed for the selected type ad. There are 4 ad types:
    • Text Ad / Full Code - Used for free text ads and for ads that you have code given from advertisers. For example you can use Google AdSense code here;
    • Image Banner - Image banner of any size. Both can be used - uploaded banner, or remotely hosted (linked).
    • Flash Movie - animated flash banners.
    • Tracker/Counter - invisible counter that will let you track your site visitors. You can use one single tracker for whole your site and this will give you detailed statistics for views, unique visitors, referrers, visitors details (countries, browsers, OSs, screen resolution and color depth, JavaScript supported and others).

    The stats mentioned for tracker ad type you will see for all the ads too. For banners and free text ads you will also have stats for clicks and click ratio. For every ad there are (as we call them) grouping details - Web site, web page, price category, ad category. These criteria can be used to make group of ads and to rotate these ads, using rotator code. While you add or edit ad you will see drop-down boxes for all these details. Next to every combo box there is an 'add new' icon [] that when clicked opens a popup window where you can add new items to these lists. The newly added item in this popup will be added to the corresponding combo-box on edit-ad screen and will be selected too (we presume that when you need to add new item you want to use it as a choice for ad details).
    If the ad is ordered by a partner or advertiser you can mark that in the ad using advertiser field.
    And here comes the interesting and the most powerful part (when used with understanding) - Weight, Expiration and Limitations:
    • Weight - this property tells the program how important is any ad in relation to others. This feature is useful mostly in rotators and it tells the rotator how frequently the ad should appear. As an example if you set 'ad1' with weight=1 and 'ad2' with weight=3, this means that 'ad2' will be displayed to visitors 3 times more than 'ad1'. You can also use this field to temporarily disable the ad to appear (no matter using ad code, or rotator). Just set weight=0 and the ad will not be displayed until this field is set with value different of 0 (zero).
    • Expiration - use this field to set time period for ad to be displayed. Useful for example when you have an ad ordered by advertiser and he (the advertiser) pays for a certain period of time.
    • Show... per IP - You can limit the number of times an ad appears to site visitor for an hour. For example if you set this field with value 2 then any particular visitor will see this ad only twice. Then the ad will not be displayed for the same visitor until 1 hour pass after the last time of ad display for this visitor. Note that this is limitation only for particular site visitor (recognized by IP) and not for the ad in whole. It is a good feature when you have more programs to promote with these ads. If we show an ad to any visitor few times and he didn't click it is quite possible that he won't click at all, even if he sees the ad one hundred times. So we better try with another ad. Note that we recommend using this feature only if you're using rotator to display the ad. If you are calling the ad with its ad code then this field should be set to 0 (zero, means - no limitation). That will guarantee the ad will be displayed always. Otherwise if the value is different than 0 the ad will appear the specified times and then no ad will be displayed on the place where you're using the ad code to place the ad.
    • Limit to Countries - we are using Geo location database and the script determines the country of every visitor. You can limit any ad to appear only to users coming from certain countries. Click the link Limit to countries and a popup window will appear where you can select the countries. If you doesn't choose any country the ad will be not geo-limited and will be displayed to all the visitors, no matter of their country.
    • When clicked don't show... - this feature can be used for ads of type banner and full text, when link URL is set for the ad. In other words only for clickable ads. Using this feature we can hide the ad for specified amount of time from a visitor that already clicked the ad. The user already clicked the ad, why we should continue displaying this ad... we better try with another. Again it is more useful when you are using the ad in rotation (on the site we placed rotator code and not ad code).

    That's all we can tell as a start about editing an ad. The fields specific for every ad type are self explanatory and we are sure you won't have any problems with them.
  5. Place the ad on your site. You can place the ad in 2 different ways:
    • Using ad code - Go to Manage Ads - Browse / Search. In the ad list for every ad there are few icons. Click on view ad code icon []. You will see a short JavaScript code. Place this code on your site pages where you want the ad to appear.
    • Using rotator code - go to Manage Ads - Rotator Codes. This is ad rotator code generator. On this page select the criteria you need for the rotator. The code generated will rotate only those ads that match the selected criteria. For example if you select 'my site' for web site and 'image banner' for ad type then the generated rotator code will rotate only those ads that are in 'my site' and are of type 'image banner'.
  6. You're ready. Now you should only visit the site regularly and see the statistics for your ads. The stats are very detailed and will let you make your own analysis. You can find how many visitors see any particular ad, you can find which are most visited pages on your site (using tracker), which are the referrers (for example how much traffic you get from Google or Yahoo), what is the click ratio (how impressing and effective is any ad) and so on... I guess you know how to analyze similar data. For example we found that 40% of the visitors on our site are from Spain, we never knew that before start using this software. Now we are considering a translation of our site to Spanish.

Settings

^ top ^
Now we will go in more deep examination of the program, screen by screen.
Here is what we have in the Settings menu:
  1. Edit CSS - the script design is based on one HTML template file and one CSS (Cascading Style Sheet) file. You can easily modify the interface of the script, simply by editing this CSS file. You should be familiar with CSS, what elements and what properties are allowed and how these definitions refer to the interface. For example 'h1' element in the css file corresponds to the headings, used in html pages (<h1> tag). All the properties defined in the css (color, font, alignment...) will be used in all the headings. So you simply edit the css file and all the headings on all the pages are altered. Just a note to the advanced users - we have 2 classes defined for tables - 'frm' and 'lst'. The class 'frm' is used for all the tables, that are used to format form fields. The class 'lst' is for list tables (where items are listed). For 'lst' tables 2 different classes are defined (row0 and row1) for the odd and even rows of the table.
    To be able to edit the CSS file directly from the admin area of the script you should make sure that the file main.css is write enabled (ftp command - CHMOD(777)) on your server.
  2. Countries - this list is only informative. You see all the countries that are used in the script for the Geo-location feature. As we explained earlier in the views statistics for every ad you can see which countries the visitors come from. So all the countries in this list are recognizable.
  3. Browsers - this is the list of recognizable browsers, used by visitors. Every browser sends a string to the server called 'user agent'. This string carry information about the browser type, the version and the operation system. In the list of browsers you see Title and Preg-Match fields. The first defines how the browser is displayed to users of the script and the second is used as a pattern in regular expression search performed on the user agent. With this search the browser type and version are distinguished. Sounds complicated? It is not. But you can not bore with this problem. The script comes with all the definitions you need. And we will take care on updates when new browser or new version appears in the world. We will notify you or you can regularly check our site (plxwebdev.com) for updates.
  4. OSs - the list of recognizable operation systems. All the explanations we gave for browser are valid here too. Generally you shouldn't modify this list (unless you're familiar with user agents and regular expressions). We take the responsibility to update this list when needed.
  5. Backup & Restore - All the stats are stored in a MySQL Database. The data can be exported from and imported to the MySQL Server. When you click the button 'Create Backup File' the data will exported in .sql file, stored in the 'backup' folder of your server. In the name of that backup file the date is included for easy reference. Once that backup file is created you can download to your computer and store for eventual future needs. It is recommended not to leave backup files in the backup folder. Once you have it downloaded you should delete from the server.
    If your data is broken in some way (due to server problems or hackers attack) you can restore the data using your backup file(s). To restore the data from certain .sql file upload it to the 'backup' folder on your server and rename the file to 'backup.sql' (remove the date from the name). Then on the backup & restore screen of the script click the button 'Restore'. Note that if you have any previous data stored in the MySQL database it will be replaced by the data from the backup file. This means that after the restore procedure is completed the script content and data will match and look exactly as they were in the past on the day when the backup file is created.
  6. Settings - script configuration. Here you define:
    - Site URL (where the script is installed) - you will see our suggestion there, probably this is the value you should use;
    - Date Format - defines how the dates are displayed on the site. There is a help icon that when clicked will open a popup window with explanation and examples on what characters can be used in this formatting string;
    - Stats - Bar Height - in the statistics there is a graphical representation of the data. Here you define the height (in pixels) of the bars in these graphics;
    - Server Time Zone - the time zone where the server is located. It is essential setting that allows the users to see real stats and not shifted in the time due to the time difference between the user and the server time zones.

Lists

^ top ^
  1. URL Mapping - You can use URL mapping to diplay friendly URLs (for Referrers and click URLs) in the stats. You define a search string and if this string is found in the URL it is displayed as you have defined in Display As field. Note that you can use regular expression patterns in the search field (if you know how to use RegExp) and you can use brackets () to enclose tagged expressions. Then in the display as field you can reference the tagged expressions by [1], [2], [3], etc. Note that even when we display the URL using more convenient text this text is used only for the title of the link. The link still refers the full URL and when you click this link you will go to the referring page (in Refferers List) or the page where the ad is clicked (in Click URLs List).
    Here are some examples:
    • Search String: google.com
      Display As: Google
      When we use the above definition the url:
      http://www.google.com?q=keyword&any_other_long_text_in_the_url
      will be displayed as:
      Google
    • Search String: .*(google.com).*q=([^&]*).*
      Display As: Google Search - [2]
      In this example we are using regular expression. It tells "if there is any character followed by google.com followed by any character followed by q= followed by any character different than & followed by any character, extract tagged expressions in the brackets".
      [2] in Display As field tells the second tagged expression to be put in the text (the first is google.com and the second is the part between q= and & or end of string). And when we have the url:
      http://www.google.com?q=keyword&any_other_long_text_in_the_url
      it will be displayed as:
      Google Search - keyword

    You can make big use of this feature. Here is another example from our live practice. This script (plx Ad Manager) is listed in Hot Scripts directory and the url there is "http://hotscripts.com/Detailed/64139.html". We are using URL Mapping and this URL is displayed in our Ad Manager as "HotScripts - plx Ad Manager". I think it tells more than the number 64139...
    Visit our forum to read more tips and tricks (not only on this subject): plxWebDev - Forum.
  2. Web Sites - This is a list of the web sites that will use this Ad Management script to manage their ads. To add new web site to the list use the button (or the link) New Web Site. For any web site you will define only 2 fields - Domain/Title and Description. Anywhere in the script the web sites are displayed by their domain/title. Description field is used only for your own reference.
    Eevery ad has a property 'web site' that takes any of the sites from this list.
    In rotator code generator if you specify web site (any of these in the list) the rotator will display all the ads for this site (the ads that have 'web site' property set the same as the one set in the rotator).
  3. WebSite Pages - If you want you can group your ads by page of appearance. In this list you see and define the pages available for any web site.
    You can use rotator to display on any of these pages only the ads that are intented for that page exactly. For example if you have two ads 'Ad-1' and 'Ad-2' and you want these ads to appear only on the index page of your site then you can define a web page named 'Index' and then you set this page for 'wep page' properties of the ads and the rotator. Put the rotator code on your index page and see these 2 ads rotated.
    Tip: 'web page' is only conventional name. You can use this ad property not only for pages, but for page space too or whatever group you need. For example you can define 'My Index page - Top Banners' or 'All the pages - Left Column' or even 'All my ads that are green'. :-)
  4. Price Categories - just another grouping property that you might find it usefull. If you have different price categories you can define them here. Can be used for grouping ads in rotator. See the explanations above for WebSite Pages, the same rules apply here.
  5. Ad Categories - If you have different ad categories you can define them here. Can be used for grouping ads in rotator. See the explanations above for WebSite Pages, the same rules apply here.
  6. Advertisers - manage the advertisers that ordered ad space. For every advertiser you create account that he can use to login to the site and see the stats for his ads. Users of level 1 and 2 can add/modify advertisers account and can select the ads that any advertiser have access to. Obligatory fields for advertiser are name, username and password. All the other fields (Email, Address, Phone...) are for your own reference.
  7. User Accounts - manage all the users that have access to the site - administrators (level 1), site managers (level 2) and advertisers (level 3). Advertisers can be managed on any of the 2 screens - 'Advertisers' or 'User Accounts':
    • Level 1 - Admin - these users have full access to the site. This is the site owner or the admin. He can add/modify accounts of level 2 and 3 and can limit their access to certain web sites and/or ads. He can select which web site(s) and ads (in these sites) a Site Manager can manage. He can select for which ads an Advertiser can view the stats.
    • Level 2 - Site Manager - in comparison to level 1 this user can not modify the settings and can not add/modify users of level 1 and 2. He can manage the ads in the web sites assigned to him (by Admin). He can add accounts of level 3 (Advertisers) and can grant these users access only to those ads that he have access himself. Site Manager can manage the lists used for ad properties (website pages, price categories, ad categories) and he will see only those items that he defined himsel. For example if 'Site Manager 1' define 'Price Category 1' then 'Site Manager 2' will not see this category.
      Of course the Site Manager can see all the stats for the ads of his possession and can modify his own account details too (username, password, name, etc.).
    • Level 3 - Advertiser - this user can only view the stats for the ads which are attached to him. And of course he can login and logout to the system. :-)