mySimpleAds User Manual

Please see the readme_install.txt file located in the root of the mySimpleAds directory. If you will be updating an existing installation, please see the read_upgrade.txt file also located in the root of the mySimpleAds directory.

Overview

mySimpleAds is ad management for the rest of us. It was designed with the website publisher in mind who would like to get his/her ads up on a site without having to spend ages climbing up a hefty learning curve. mySimpleAds provides useful features such as GeoTargeting and ad expiration, without any unnecessary bloat.

Host System Requirements

PHP 5.2.0 or greater
MySql 3.23 or greater

Administration

Accessing

To access your mySimpleAds administration panel, point your web browser to...
http://yoursite.com/yourmysimpleadsdirectory/admin/index.php . Then in the username box, enter your Administrator username as selected during the install process. Same goes with the password box.
Your advertisers, at your discretion, can also login here to administer their ads. You assign them a username and password in the Advertisers section.

Navigation

mySimpleAds Administration area is logically broken up into different areas of administration. These areas are :

Ads : The Ads area is where you will enter your ad information and individual ad options, such as which in which countries will or will not display the ad.

Advertisers : The Advertisers area is where you can keep track of information on each advertiser, whose ads you might be displaying. The information is for your reporting purposes and organization only. This is also the location to set the advertisers' username and password, if you would like them to login to administer their ads.

Ad Groups : The Ad Groups area is where you can create groups that will house multiple ads to rotate amongst. For example, to show ad one in the United States and ad two everywhere else, you would create an Ad Group and assign ad one and ad two to the group. Paste the Ad Group code into your website and the two ads will rotate amongst each other based on visitor's country.

Ad Stats : The Ad Stats area is where you can monitor your advertising impressions, from looking at pie charts to downloading CSV spreadsheets for analyzing with your favorite tool. You can also access the stats via various RSS feeds.

Configuration : The Configuration area is where you can set the mySimpleAds options, such as turning on/off GeoTargeting. It is also where you can change your administrator user id and/or password.

Maintenance : The Maintenance area is where you can accomplish such things, as backing up your database, downloading your stats to a CSV file, and checking for GeoIP Database updates.

Ads : Listing current ads

To list the current ads in your mySimpleAds system, click on the Ads link in the navigation menu to access the Ads area (this is also the default area when you first login to the Administration area). The Ad Listing table will be displayed which provides an overview of all the ads currently in the system. The table displays information including : ID, Status, Last Update Time, Description, Advertiser, Ad Group, Impressions, Clicks, and Click Through Rate (CTR).

The Ad Listing table also provides the links to edit an ad, delete an ad, and get the code for an ad.

Note: If an advertiser logs in, they will only see and optionally be able to administer their own ads.

Ads : Creating a new ad

To create a new ad, click on the Ads link in the navigation menu to access the Ads area (this is also the default area when you first login to the Administration area). On the top right of the Ad Listing table, click the Create a New Ad link. Now, lets walk through the options...

Ad Enabled : Click 'Yes' to enable the ad, or 'No' to disable the ad.
Ad Description : Description of the ad (for your reporting purposes only).
Advertiser : Select the advertiser (for your reporting purposes only).
Ad Group : Select the Ad Group(s) to which the ad will be assigned (if any). Ads in the same group will then by cycled amongst each other. Select '-none-' to not have this ad be part of a group.
Keywords : Comma-separated list of keywords to target this ad (maximum of 255 chars). If one of the keywords is called from a website then this ad will be in rotation for that spot. Leave empty to not be part of any keyword call. Special characters, like spaces will need to be encoded in the ad code, like %20, so try to avoid them if possible.
Ad Weight : Ad weighting allows you to show one add more than another when they are both a member of the same group. Select the ad weight for the ad amongst the ads in it's group. 10 is the highest weight, with this ad being shown as much as possible. You can leave all ads at 10 by default to evenly distribute.
Use GeoTargeting Settings From Another Ad : If you want to use the same GeoTargeting settings as another ad, select the source Ad ID here. Just leave this unselected to set this ad with its own GeoTargeting settings.
Display in these countries/cities/regions ONLY : Select one or more locations from the list to display the ad in those locations ONLY. To display in all locations (except any listed in the 'do not display' box), select nothing.
Display in all countries BUT these : Select one or more locations from the list to NOT display the ad in those locations. It will display in all other locations. To display in all locations (or only those specified in the 'only' box), select nothing. To select multiple entries hold down the Shift key or Ctrl key (or similar key for your OS).
Start Date : Select the date for which the ad should start. To pick a day if none is already selected, first select the month and the rest of the options will appear. To remove a start date, select the empty option above the 'January' in the month selector. Beginning that day the ad will be displayed when called.
Expiration Date : Select the date for which the ad should expire. To pick a day if none is already selected, first select the month and the rest of the options will appear. To remove an expiration date, select the empty option above the 'January' in the month selector. On that day the ad's status will be set to disabled on the first attempt to display it.
Limit Impressions : Lets you limit the number of impressions for the ad for a particular time period. If you wish to limit the number of impressions for this ad in a given time period: Type in the number of impressions (times ad will display) and select the time period. To not limit the ad, just set the number of impressions to zero and the clear the timeframe pulldown. Note: This feature requires the Stats Module be enabled.
Ad Type : Select the type of ad
- Ad Code : Select Ad Code for pasting in javascript and other code from an ad provider, such as Google AdSense.
  - Ad Code : The code from an ad provider such as Google AdSense. Some PHP code can be entered here as well (make sure you use opening and closing PHP brackets). You can also enter your plugin function here, as noted in the Plugins section of the manual.
  - Text Link : Select Text Link for adding straight text links to your site.
    - Anchor Text : The anchor text for the text link, such as 'ClipperSoft'.
    - Link URL : The URL to link to (include the http://, https://, etc.), such as 'http://www.clippersoft.net'.
    - Link Target : Target window to open in the browser using the standard HTML Target attribute for links. This allows you to have a clicked link open in a new window, or just use the existing window Default is '_blank', which will open the clicked ad in a new browser window.
    - CSS Class : Name of the CSS Class to format the link. Can be left blank, which is default.
    - Track Clicks : Click 'Yes' to track clicks on the ad, or 'No' to disable tracking and just use direct linking.
    - Use Cookie Tracking : Click 'Yes' to use cookies to prevent displaying the ad to the same user, or 'No' to not use cookie tracking. The cookie will last for a period of 1 week (or until the user clears their cookies.) Note: If there are no other ads to be displayed, or the user has seen them all, this setting will be ignored.
    - Enable Dupe Click Protect : Click Yes to block click tracking on visitor's IPs that have visited today. Clicks will only be registered the first two times for that ad from the visitor during the day.
      Stats must be enabled for this function.
  - Image Banner : Select Image Banner for showing image based (jpg, gif, swf, etc.) banners on your site.
    - Banner Source URL : The URL pointing to the banner image, such as 'http://www.mysite.com/images/banner.jpg'.
    - Banner Link URL : The URL to link to (include the http://, https://, etc.), such as 'http://www.clippersoft.net'. This is not used for Flash banners.
    - Link Target : Target window to open in the browser using the standard HTML Target attribute for links. This allows you to have a clicked link open in a new window, or just use the existing window Default is '_blank', which will open the clicked ad in a new browser window.
    - Banner Alternate Text : The image alternate text for the 'alt' property of the 'img' tag, such as 'Home of ClipperSoft'. This is not used for Flash banners.
    - Banner Caption : Linked text shown below image banner. It can include html formatted code.
    - Banner Image Height : The height of the banner image file.
    - Banner Image Width : The width of the banner image file.
    - CSS Class : Name of the CSS Class to format the link. Can be left blank, which is default.
    - Track Clicks : Click 'Yes' to track clicks on the ad, or 'No' to disable tracking and just use direct linking. This is not used for Flash banners.
    - Use Cookie Tracking : Click 'Yes' to use cookies to prevent displaying the ad to the same user, or 'No' to not use cookie tracking. The cookie will last for a period of 1 week (or until the user clears their cookies.) Note: If there are no other ads to be displayed, or the user has seen them all, this setting will be ignored.
    - Enable Dupe Click Protect : Click Yes to block click tracking on visitor's IPs that have visited today. Clicks will only be registered the first two times for that ad from the visitor during the day.
      Stats must be enabled for this function.

When completed, click the Save button to create the ad, or Cancel to exit without saving the changes.

Note : For Flash banners, the clicks must be handled internally by the Flash file itself. You must add the appropriate Action Script code to the Flash file, by doing something like the following...

The preferred method is using the new clickTag code...

http://www.adobe.com/resources/richmedia/tracking/designers_guide/

...mySimpleAds will read the clickTag code and redirect the visitor to the URL.

Another option is to make your entire movie a link, make a huge button covering the entire thing with a getURL code. Using the effect palette, make the button transparent.

To make a text link, type something with your text tool and turn it into a button. Then add a getURL to that button.

Ads : Editing an existing ad

To edit an existing ad, click on the Ads link in the navigation menu to access the Ads area (this is also the default area when you first login to the Administration area). In the Ad Listing table, click the Edit Icon in the row of the ad you wish to edit. You will then be brought to the ad options page, with the options as listed in the 'Creating a new ad' section above. In addition to the options above, you will also be able to reset your lifetime Ad impressions and clicks, as well (assuming the Ad has impressions/clicks).

When completed, click the Save button to store the ad changes, or Cancel to exit without saving the changes.

Ads : Deleting an existing ad

To delete an existing ad, click on the Ads link in the navigation menu to access the Ads area (this is also the default area when you first login to the Administration area). In the Ad Listing table, click the Delete Icon in the row of the ad you wish to delete.

You will be prompted with an 'OK' or 'Cancel' box. Click OK to delete the ad, or Cancel to exit without deleting the ad.

Ads : Getting the Ad Code for your website

To get the Ad Code for inserting into your website source, click on the Ads link in the navigation menu to access the Ads area (this is also the default area when you first login to the Administration area). In the Ad Listing table, click the Ad Code Icon in the row of the ad you wish to retrieve the code for.

If the ad you wish to display is a member of an Ad Group, you can select to either display the Ad Group or just the individual ad. mySimpleAds will display both options for you, when available.

mySimpleAds supports multiple ad codes per page. Simply insert each Ad Code in your page - no special procedures need to be followed.

In the Ad Code page, select the code type you wish to use. The code types are as follows :

PHP Insert Code : The page where you will use this code must be able to parse PHP code (usually by naming the file with a '.php' extension). The 'include_once' path is the file system path (not a URL path) to the 'mysimpleads.php' file relative to the directory the source code is placed into. To simplify things, it is usually best to use the full file system path, which mySimpleAds shows by default in the Ad Code. If you are inside a PHP block when placing the ad code into your website pages, make sure to leave out the php tags ('<?php' and '?>').
PHP Remote Read Code : The Remote Read Ad Code will display the output generated by mySimpleAds in the location you place it in your website page. You can use this code on any page, anywhere, as long as the web host the page will be on has their PHP ini setting of 'allow_url_fopen' set to 'true' (or 'on'). The page where you will use this code must be able to parse PHP code (usually by naming the file with a '.php' extension). The 'readfile' path is the URL path to the 'mysa_output.php' file. If you are inside a PHP block when placing the ad code into your website pages, make sure to leave out the php tags ('<?php' and '?>').
Javascript Injection Code : The Javascript Injection Ad Code will display the output generated by mySimpleAds in the location you place it in your website page, through the use of a javascript call. You can utilize this code wherever PHP is not available in your website page. You can simply copy and paste the Javascript code anywhere into your website, as you would with the PHP Ad Code. It will also work on remote domains. The injection code cannot display javascript code, such as that from AdSense.
Ajax Rotating Banner/Text Links Code : The Ajax Rotating Banner/Text Links Code will allow you to rotate your banner or text link ads at a specified interval without a page refresh. You can simply copy and paste the Javascript/Ajax code anywhere into your website, as you would with the PHP Ad Code. It will also work on remote domains. The Ajax Rotating Banner/Text Links Code cannot display javascript code, such as that from AdSense.

Click Back to Ad Listing to return to the Ad Listing table page.

Advertisers : Listing current advertisers

To list the current advertisers in your mySimpleAds system, click on the Advertisers link in the navigation menu to access the Advertisers area. The Advertisers Listing table will be displayed which provides an overview of all the advertisers currently in the system. The table displays information including : ID, Description, URL, Number of ads, and the advertiser's custom RSS URL.

The Advertisers Listing table also provides the links to edit an advertiser, and delete an advertiser.

Advertisers : Creating a new advertiser

To create a new advertiser, click on the Advertisers link in the navigation menu to access the Advertisers area. On the top right of the Advertisers Listing table, click the Create a New Advertiser link. Advertiser listings are for your reporting / organizational purposes only. Now, lets walk through the options...

Advertiser Description : The description / name of the advertiser.
Advertiser's Email : The email address of the advertiser contact.
Advertiser's Contact : The contact name for the advertiser.
Advertiser's URL : The URL for the advertiser.
Advertiser Comments/Notes : Any additional comments about the advertiser for your records.
Advertiser Login : If you would like to have your advertiser login and view or manager their ads, you can assign them a username and password to do so.
Advertiser Read-Only Access : If you would like the advertiser to only view their ads and not be able to create or edit them, you can set this to provide them only Read-Only access.
Advertiser's RSS Stats Feed Password : Password for the advertiser to be able to access their RSS stats feed showing their advertisement statistics.
Advertiser's RSS Stats Settings : Settings for the Advertiser's RSS Stats Feed. Select Yes or No as to whether to show that particular statistic to the advertiser in their stats feed.

When completed, click the Save button to create the advertiser, or Cancel to exit without saving the changes.

Advertisers : Editing an existing advertiser

To edit an existing advertiser, click on the Advertisers link in the navigation menu to access the Advertisers area. In the Advertisers Listing table, click the Edit Icon in the row of the advertiser you wish to edit. You will then be brought to the advertiser options page, with the options as listed in the 'Creating a new advertiser' section above.

When completed, click the Save button to store the advertiser changes, or Cancel to exit without saving the changes.

Advertisers : Deleting an existing advertiser

To delete an existing advertiser, click on the Ads link in the navigation menu to access the Advertisers area. In the Advertisers Listing table, click the Delete Icon in the row of the advertiser you wish to delete.

You will be prompted with an 'OK' or 'Cancel' box. Click OK to delete the advertiser, or Cancel to exit without deleting the advertiser.

Advertisers : Advertiser's RSS URL

mySimpleAds allows you to see your statistics via an RSS feed. You can setup a password for each advertiser, and then get their particular RSS feed URL by clicking on their RSS URL icon in the Advertisers table.

The feed will only show the advertiser the statistics to the ads they are assigned to. So, each advertiser will not see any other advertiser's statistics.

Note: You can get your admin RSS feed from the Stats page, which will show all your ads statistics.

Ad Groups : Listing current ad groups

To list the current Ad Groups in your mySimpleAds system, click on the Ad Groups link in the navigation menu to access the Ad Groups area. The Ad Groups Listing table will be displayed which provides an overview of all the Ad Groups currently in the system. The table displays information including : ID, Description, URL, and Number of ads assigned.

The Advertisers Listing table also provides the links to edit an Ad Group, delete an Ad Group, and get the Ad Group Ad Code.

Ad Groups : Creating a new ad group

To create a new Ad Group, click on the Ad Groups link in the navigation menu to access the Ad Groups area. On the top right of the Ad Groups Listing table, click the Create a New Ad Group link. Now, lets walk through the options...

Group Description : The description / name of the group. It is used for your reporting / organizational purposes only.
Number Of Ads To Display : The number of ads to display horizontally or vertically in a row. The default is 1.
Multiple Ad Layout : If displaying more than one ad at a time, do you want them displayed next to each other (horizontal) or on top of each other (vertical).
Advertisers With Modify Rights : If you will be letting advertisers login, you can assign them ownership of existing groups, so they can view or modify them. Any new Groups that they create will automatically be assigned to them.

When completed, click the Save button to create the Ad Group, or Cancel to exit without saving the changes.

Ad Groups : Editing an existing ad group

To edit an existing Ad Group, click on the Ad Groups link in the navigation menu to access the Ad Groups area. In the Ad Groups Listing table, click the Edit Icon in the row of the Ad Group you wish to edit. You will then be brought to the Ad Group options page, with the options as listed in the 'Creating a new ad group' section above.

When completed, click the Save button to store the Ad Group changes, or Cancel to exit without saving the changes.

Ad Groups : Deleting an existing ad group

To delete an existing Ad Group, click on the Ad Groups link in the navigation menu to access the Ad Groups area. In the Ad Groups Listing table, click the Delete Icon in the row of the Ad Group you wish to delete.

You will be prompted with an 'OK' or 'Cancel' box. Click OK to delete the Ad Group, or Cancel to exit without deleting the Ad Group.

Ad Groups : Getting the Ad Group Code for your website

To get the Ad Group Code for inserting into your website source, click on the Ad Groups link in the navigation menu to access the Ad Groups area. In the Ad Group Listing table, click the Ad Group Code Icon in the row of the Ad Group you wish to retrieve the code for.

The different code types and their descriptions are as described in the 'Ads : Getting the Ad Code for your website' section above.

Ad Stats : Stats Overview

The Ad Stats area gives you a detailed overview of your Ad impressions. Select the Ad to view, along with the time frame, and click View. A pop-up window will appear showing:

Overall Ad Impressions
Hostnames
Countries
Regions
Cities
Referers
Days of the Week
Browser
Platform

All will be ranked and include a pie-chart.

You can also access all your ad stats via a Stats RSS Feed. The password protected feed can be consumed by any RSS reader, simply by using the URL provided on the Ad Stats page.

Configuration : Configuration options

To access the configuration options in your mySimpleAds system, click on the Configurations link in the navigation menu to access the Configuration area. Now, lets walk through the options...

Administrator username : The username to login with for the administrator.
Administrator password ( - confirm) : The password to login with for the administrator.
Administrator Email Address : The email address to send your admin password to, in case you need to recover it.
mySimpleAds Install URL Path : The full url to your mySimpleAds install, ex: http://www.myserver.com/mysimpleads.
Banners directory : The name of the directory that contains your banners - relative to your mysimpleads directory. Do NOT enter a trailing or preceding slash!
Enable Change Prompts : Click 'Yes' to enable the popup change prompts after making a change in the Admin Console, or 'No' to disable the prompts.
Enable Plugins: Click 'Yes' to enable the plugins system, or 'No' to disable the plugins system. Enable this only if you plan to place a plugin in the plugins directory, otherwise just leave it disabled.
Enable Stats Module : Click 'Yes' to enable the detailed impression stats module, or 'No' to disable the impressions stats module.
IPs to ignore in Stats : Enter a comma separated list of IPs to not display when in the stats module. This can be used to filter out your own IP.
Block Bots from Stats : Click 'Yes' to enable the filtering out of most bots impressions/clicks, or 'No' to not filter any possible bots.
Archive Stats Older Than : Enter a number for the number of days beyond which the stats will be archived. The archived stats will still be available in your stats queries. This is just done to speed up inserting. Note: The archiving process only occurs when you login to the admin console.
Enable ad expiration : Click 'Yes' to enable the ad expiration option, or 'No' to disable the ad expiration option.
Enable GeoTargeting : Click 'Yes' to enable the GeoTargeting option, or 'No' to disable the GeoTargeting option.
Enable GeoTargeting Locations: Click 'Yes' to enable the GeoTargeting for Countries, Cities, or Regions, or 'No' to disable the particular GeoTargeting location. For Cities/Regions, If you did not select this option during install/update, you will need to run the mySimpleAds Update process (again), and select it there. That will allow the database table to be installed. The size of the database is too large to install, unless it is needed.
Tracking Cookie Expiration : Number of hours until cookie expires when using the Tracking Cookie to prevent the same ad being displayed to a user.
Enable Ad Descriptions In Ad Code : Click 'Yes' to enable the ad's description to be included as part of the ad code for your website (just for clarity purposes), or 'No' to not include the description.
GeoTargeting Settings : Disable/Enable the various GeoTargeting locations.
Default country : When using GeoTargeting, if the country is not found, which country should be selected.

When completed, click the Save button to store the configuration changes, or Cancel to exit without saving the changes.

Maintenance : mySimpleAds Maintenance

To access the maintenance options in your mySimpleAds system, click on the Maintenance link in the navigation menu to access the Maintenance area. Now, lets walk through the options...

Version : This checks against the clippersoft.net server as to whether you are using the latest version of mySimpleAds or not.
Backup Database : This link will download a full mySQL download to your browser to allow you to save a copy of your database to your local computer.
Export stats to CSV file : Export the compiled stats table to a CSV file for local viewing.
Export stats to CSV file and Purge archived stats data : This function will export your stats table to a CSV file. Then it will remove all records in your archived stats table.
Check for GeoIP Database update : A new GeoIP database is released at the beginning of each month. This function will check to see if a newer version is available for download.

Plugins

mySimpleAds supports a basic plugin system when its necessary to extend its ad serving functionality. For example, if you work with an ad company that provides their own PHP code, you can place that code into a plugin and be able to call it from mySimpleAds.

Variables available from mySimpleAds...

$ads->mysa_ip : The visitor's IP Address

Example : 127.0.0.1

$ads->mysa_cc : The visitor's Country code (if GeoTargeting countries is enabled)

Example : US

$ads->mysa_rc : The visitor's Region code (if GeoTargeting regions is enabled)

Example : US|6

$ads->mysa_cyc : The visitor's City code (if GeoTargeting cities is enabled)

Example : US|6|los angeles

The file must be saved with a '.php' extension and the plugin system must be enabled in the Configuration section, for the plugin to be accessed.

Sample plugin...

<?php

function hello(){

global $ads;

echo 'Hello, your IP Address is:'.$ads->mysa_ip;

}

...You can then create an ad in mySimpleAds using the 'ad code' type, and enter '<?php hello(); ?>' (without the quotes) to have the function run, just as any other ad code would.

How-To / FAQ / Troubleshooting

Please check the ClipperSoft website and forum at http://www.clippersoft.net for the latest information and tips on working with mySimpleAds.

Contact

Please use the help desk or contact form at the ClipperSoft website, http://www.clippersoft.net, to contact us about specific issues.

Thank you for using ClipperSoft's mySimpleAds for your ad management needs!