March 28,

mySimpleAds Docs and FAQs

How does licensing work?

When you purchase mySimpleAds, you own it for life. It never expires. You get a full year of support and any minor/major updates during that time.

You can continue getting support and all updates for every year after that, by just continuing your account. If you wish, you may also cancel your account, but you will no longer have access to updates or support. If you do want to cancel, make sure it’s near your year’s end of your license, so you can continue getting updates and support until then.


How do I update mySimpleAds?

mySimpleAds v2 now lets you download and install the latest updates right from within its console. Just go to the Configuration page (the gear icon) and you can click the Check for mySimpleAds Updates button to check/install any updates.

You can also download the latest version from your Membership Account page and upload the zip to the ‘f3/cache/tmp’ directory. Then go to ‘admin/index.php/install’ in your mySimpleAds console to start the upgrade.

Note that you must have an active account on here to be able to get the latest updates.

Installing mySimpleAds

How to install mySimpleAds…

  1. Download a copy of mySimpleAds from your ClipperSoft Membership Account page.
  2. Unzip the archive (make sure to unzip leaving the
    directory structure intact).
  3. (optional) Create a MySQL database and MySQL user account that will
    house mySimpleAds.  This can be done through your webhost with tools such
    as phpmyadmin or cpanel.
    You can use an existing database if you would like.
    The mySimpleAds tables are all prefixed with ‘mysa_’, so they should not
    run into any table conflicts.
  4. Open ‘config.orig.php’ in your favorite text editor and fill in your database
    details, including database hostname, database name, and database username
    and password. Then save the file as ‘config.php’.
  5. Copy/FTP the ‘mysa2′ folder (and all its sub-directories) to your
    website. Note: You can rename ‘mysa2′ to anything you would like.
  6. Make sure your webserver account/group has write access to the mysa2 directory
    and files. Leave ‘public’ with read only access.
  7. Open up your favorite browser and point it to the
    ‘mysa2/admin/index.php?install’ script.

Follow the steps provided in the web installation portion and you’re done!

Creating an Ad
  1. To create an ad in mySimpleAds, we select the Create link under the Ads menu.
  2. Next we get to select the kind of ad to create, including Image Banner, Video, Text Link, and Free-form (which allows javascript ads such as Adsense, and custom PHP code).
  3. In the edit form, we first enter in a descriptive title for the ad. Then we can assign the ad to a particular advertiser for easy stats reporting.
  4. Next we assign it to any groups and keywords. An Ad Group allows you to show a series of ads in the same spot on your sites, similar to an ad zone. Keywords let you target ads by keyword instead of a particular ad or group Id.
  5. You can limit when your ad starts displaying or stops displaying. You can also limit how many impressions or clicks it receives per a period of time.
  6. You can also limit where or where not the ad displays around the world. You can target by country, region/state, or cities.
  7. Since we created a banner image ad in this example, we will now upload the image. You can also select it from the existing images, or put in any URL for images hosted elsewhere. mySimpleAds lets you specify a large banner size and small banner size. If you upload a small banner size that image will be used to display to smaller screens, like smartphones (iphone, android, etc). You can preview any ads you uploaded to make sure it was the right one.
  8. Lastly in the ad form, we enter in the banner destination URL, image Alt tags, and any captions we would like. Captions let you display HTML around any side of the image. When ready, click Save to save the ad.
  9. Back in the ad listing, you can now copy the ad code to paste onto your site to display the ad.
  10. In the ad code listing, you can select how the ad will be displayed. There are multiple options, depending upon whether it’s an ad, group, or whether it contains javascript code in the ad. If available the mySimpleAds javascript ad code is generally the easiest to use, and lets you just paste it into most sites. The PHP ad code can be used in PHP based websites. There is also an HTML only option which works great for an Email Campaign where javascript and PHP can’t be used.
  11. Finally, copy the ad code and paste it into your website’s code where you want the ad to be displayed.
Paypal Configuration

mySimpleAds uses PayPal Express Checkout. You’ll need a business PayPal account, which is free to sign-up for. Once you have a PayPal business account, you just need your API credentials. PayPal shows you how to get your API credentials on their developer site. Just follow the few steps under ‘Creating Classic API credentials’. You don’t need certificate credentials.

Your API Username, API Password, and signature will then be listed on your PayPal account profile. You just need to copy/paste those into the mySimpleAds configuration page. Note that you’ll have different accounts for PayPal sandbox vs PayPal live, so your credentials might be different, as well.

Serving Ads to Mobile Devices

mySimpleAds Image Banner Ads allow for two sizes of images. The ad code will analyze the screensize of the device the ad is displayed on and, if available, will show the smaller size image to that device. In most cases, desktops and tablets will see the Large Banner and smartphones, like the iPhone, will see the Small Banner. If you don’t specify a Small Banner, all devices will simply get the Large Banner.


If your sites receive a lot of mobile traffic, having smaller size images (in both dimensions and file size) is probably worth trying out. Especially since some of these devices may be on a slower network, having a smaller image file size to download will be quite beneficial in having the visitor see your ad.

The Scheduler and Stats Processing

To keep the ad serving and page load as fast as possible, items, such as processing the stats and checking for ad start/end dates is done in backend processing request. When a visitor comes to your page and receives an ad, a call is made to a couple APIs, one which checks if any stats need to be processed, and one which runs a scheduler. The scheduler handles things like ad limiting, cache cleanup, and sending weekly stats emails.

Given that the stats processing and scheduler is triggered by a visitor coming to your site, if you have no visitors, they will not run. Of course, if you have no visitors, there really is no need for them to run. The stats are stored in a queue and that queue is processed every 10 minutes or so, again depending upon if a visitor loads the ad.

You can manually trigger them…

  • Stats queue processing : mysa2URL/api/index.php?pq
  • Scheduler : mysa2URL/api/index.php?scheduler


Sending Emails and SMTP Settings

By default, the mySimpleAds configuration will use your host’s PHP.ini Mail settings to send any email. If that doesn’t work, or is possibly going into SPAM folders, you can also set an SMTP server, like GMail’s.


In the mySimpleAds configuration page (the gear icon in the top right), select SMTP as the Mail Type. Then enter your SMTP server settings.

For example, here would be GMail’s SMTP Server settings…

  • SMTP Host :
  • SMTP Server Port : 465
  • SMTP Username: your gmail username
  • SMTP Password: your gmail password
  • SMTP Security Type: SSL
Creating an Ad Group

Ad Groups in mySimpleAds let you show a series of ads in the same spot on your websites. They work similar to ad zones. You don’t need to pre-define any locations, you can place their ad code anywhere on your sites.

  1. Click Create under the Ad Groups menu.
  2. In the ad group form enter in a title for the ad group.
  3. Assign any ads to the ad group. These are the ads that will be rotated in the spot you place the Ad Group ad code. You can also add any keywords, so you can call the group via keyword instead of Id. You can set the ordering of the ads to be a Weighted Random (they will rotate randomly with those set to higher weights being earlier in the list), as you order them in the select window, or by click performance. If you choose to order them as you selected them, and you have it set to only show one ad at a time, it will rotate among those ads in that order, and if you show more than one ad at a time, it will not rotate, but just show them in your selected order. When ordering by Click Performance, it will sort the ads by number of clicks over the last 7 days, highest to lowest. It updates it automatically via the scheduler every 6 hours.
  4. Select the number of ads to display in the spot at the same time, either horizontally, vertically, or in some custom way. So, for example, to display a column of three ads, you select ‘3’ as the Number of Ads to display and select ‘Vertically’ for Ad layout. Then click Save to save the ad group.
  5. To display the Ad Group on your sites, you select the ad code icon for that ad group from the ad group listing.
  6. Select how you would like the group to appear on your site. You can also select whether to use JavaScript or PHP based ad code. JavaScript is the most universal, but if you have any ads in the group which contain JavaScript themselves, like Adsense, only the PHP option will be available.
  7. Finally, copy and paste the ad code into your website’s code.
Creating a Sales Spot

When you’re ready to start monetizing your sites, you can use mySimpleAds to create advertising Sales Spots. mySimpleAds will handle all steps from the page listing the spots for sale to the advertiser buying and creating the ad. First step is to create a Sales Spot. You’ll place the ad code for this spot on your site where advertiser’s ads will appear.

  1. Select Create under Sales Spots.
  2. In the Sales Spot form, enter in a title. This title will be displayed on your sales spot’s page for the site in question.
  3. Select a Fill group. So, you don’t have an empty spot on your site, you can select a fill group. Ads from the fill group will be displayed in the spot (along with any sold ad spots) until the maximum spots that you select next is reached.
  4. You next select the maximum number of ads that will be displayed in this spot. If all spots are full, no one will be able to purchase any more spots. If any spots are open, ads from the fill group will be displayed to make up any missing number of spots.
  5. Select the type of ad that will be displayed in this spot, such as Image Banner. These are the same types used when creating an ad.
  6. Set the pricing for the ad. This includes setting the actual price and currency, along with the method of pricing, such as CPM, CPC, or per time period.
  7. Finally you enter in the site information where the ad spot will be displayed. All Sales Spots that have the same Site URL will be displayed on the same Sales Spot Advertising listing page. The Site name will be used as part of the title of the Sales Spot listing. You can also set a contact URL for someone to contact you from the advertising page. The Spot image will be displayed above the sales spot listing. So, you will want to make a screenshot of your site showing where the ad will be displayed. Click Save when you are ready to save the spot.
  8. To start displaying the Sales Spot, or to see the Sales Spot Advertising listing page, select the ad code button for that listing in the listing table.
  9. Select how you want the Sales Spot displayed on your site and copy/paste the ad code into that location on your site.
  10. To get the URL for your Sales Spot Advertising listing page, click the Sales Page URL tab. If you click the URL listed you’ll be take to the listing page.
  11. The Sales Spot Advertising listing page will list all spots available for sale on the particular site in question. All spots for the same site URL will be listed together on the same page. Advertisers can now start purchasing spots on your site.
What Do the Different Roles for Users Mean?

mySimpleAds lets you create multiple user accounts. Each account can be for a different purpose, or role.

The three types of roles are…

  • Super Admin – There should only be one Super Admin. This account has full access to every aspect of mySimpleAds, including all accounts.
  • Admin – Admins can manage Ads, Groups, and Sales Spots, but can’t manage Users nor site Configuration.
  • Advertiser – Advertisers only have access to ads they create. You can use them for reporting/categorizing your ads, similar to how mySimpleAds v1 worked. All people who purchase ads to your site through mySimpleAds will automatically be assigned the Advertiser role.


mySimpleAds Changelog

Please see the ClipperSoft Blog for the latest changelog entries.


Blocking Cache Access

mySimpleAds caches database access to lighten the load on MySQL and speed up operations. In most cases it’s fine setup how it is. The directories (/f3/cache and /f3/cache/tmp) have an index.htm in them to prevent directory listing, as well as an .htaccess to prevent access when using an Apache web server. If you want to block access to those directories and you’re using the NGinx web server, just add this to your site’s server configuration…

        location ~/(MYSA2/f3/cache|MYSA2/f3/cache/tmp){
                deny all;
                return 404;

…replacing ‘MYSA2′ with your mySimpleAds directory name.

Recommended Mobile Banner Image Sizes

For your Small Banner Image size that you want to target mobile devices (smartphones) with, both IAB (helps set online advertising guidelines) and Google use/recommend roughly these sizes for smartphones…


Mobile leaderboard (320×50)

Large mobile banner (320×100)

Small square (200×200)

Square (250×250)

Medium rectangle (300×250)


…even if you deviate from these exact sizes, it gives you a rough range that you can work under.

How do I translate or change the text language?

In the ‘/admin/app/dict’ directory you will find ‘en.ini’. This is the default English language file. It’s in INI format, as such…


Do NOT change this file! This file gets updated, and any changes you make to it will get overwritten on any updates. Instead create a new file with your lowercase language ISO name being the file name.

For example, for Great Britain English, in the same directory create ‘en-gb.ini’. Then copy any of the lines you want to change from ‘en.ini’ into that file. Change the text to the right of the equals (=) sign. It will then use your ‘en-gb.ini’ translations for any browser that states its language is ‘en-gb’.

You can get a list of Language Culture Names from…


Ordering of Ads in an Ad Group

Group Ad Ordering

You can order your ads by three ways…

  • Weighted Random – This will order the ads randomly, take into account their weights. You can set the weight for an ad in the ad edit form. The higher the weight the further up in the ordering.
  • As Ordered – This will set the ad order to be how you assign the ads to the group in the select boxes. If you have it set to only show one ad at a time, it will rotate among those ads in that order, and if you show more than one ad at a time, it will not rotate, but just show them in your selected order
  • By Click Performance – It will set the order of  the ads by number of clicks over the last 7 days, highest to lowest. It updates it automatically via the scheduler every 6 hours.
How to use an Ad in an Email Newsletter?

mySimpleAds HTML Only Email Ad Code

For banner images and text links, mySimpleAds supports an HTML Only based ad code.

HTML Only will use a tracking pixel to get the impressions and standard HTML for the click. It can be used in places such as newsletters, where javascript may not be supported.

You can get the HTML Only ad code in the same page as the regular Ad Code, just click the HTML Only option on the bottom (as shown in the screenshot).


What do the different Ad Status labels mean?

The ad listing table includes a column that shows the current status of the ad. Here is what each status means…

  • On : Ad is running
  • Off : Ad is not running
  • Ended : Ad is not running and reached its end date
  • Ending : Ad is within 7 days of reaching its end date
  • Scheduled : Ad has a start date that hasn’t been reached yet