2. The Perl modules needed are DBI and DBD::mysql. It also helps to have Net::SMTP.

3. You can use the helper.cgi script to figure out all the appropriate server paths, Perl modules installed, etc...this script can be found here: Download Now

4. You NEED to be able to trigger a commission after a sale is made on your site. This means that you NEED to be able to edit your thank you page or figure out some way to trigger the sale.cgi script after a purchase is made on your site. In order to have percentage commissions, you MUST be able to add the final purchase price to the tag of code that triggers sale.cgi.

MySQL is simply a database that EXISTS SEPARATELY from your web server, hosting account, etc...thus, it usually needs to be set up separately by yourself (if you run the server) or by contacting your ISP to set it up.

It's quite simple - just send an email to your ISP's support saying:

"Hi! I'd like to have a MySQL database set up with my account. Please make the database name 'whatever' and the password 'whatever'."

That's it! Sit back and a day or two later (if you have a good hosting company) you should get an email saying that the database is set up.

MOST web hosts allow you to do the above through a control panel. Usually your username and password is the same as your FTP account and the database name is "yoursite_com" or something similar. Sometimes you have to create the database yourself.

Now, the best thing to do is just test it out:

TELNET TO YOUR SERVER (in Windows, select Start->Run->then type "telnet mysite.com") or possibly use a telnet client (SSH if you need it) like Secure CRT from Vandyke Technologies.

Once you have a prompt - type in: mysql -u yourserverloginname -p

HIT RETURN - THEN PUT IN YOUR PASSWORD

Then you should receive a prompt:
mysql>

simply type:
mysql> use yourdatabasename <<RETURN>>
mysql> go

And it should say "database changed".
THIS MEANS YOU ARE GOOD TO GO!

2. SETTING UP THE SCRIPT
 

Extract all of the files in the zip file locally, then upload via a FTP program.

1. Create a directory in your cgi-bin called "affiliates" (or named whatever you want). Within that directory, create a directory called "emails".

... cgi-bin/affiliates
... cgi-bin/affiliates/emails - chmod 777
... cgi-bin/affiliates/templates - chmod 777

2. Upload all the files in the cgi-bin folder to the "affiliates" directory. Upload all of the example emails to the "emails" directory and chmod 777. (MAKE SURE YOU DO THIS IN ASCII MODE!) Upload all the graphics in the images folder to a non-cgi directory. (DO THIS IN BINARY MODE!)

3. CHMOD all of the cgi script files 755 except for config.cgi and common.cgi.

4. CHMOD config.cgi, common.cgi, and signup.html 777

5. Fire up your browser and execute the admin.cgi script. You will be presented with with a login page - the default password is "superpass". Once logged in you will encounter a page asking for your MySQL variables. All is explained there. Once you get the script connected to your database, you will be forwarded to the main admin page.

The first thing you will need to do is go to the "configuration" area and spend some time filling in some of the settings, paths, and URLs for your program.If you need help with your paths, I suggest downloading my helper.cgi script which you can get for free at groundbreak.com.

Once finished, you can begin testing the program.

7. Run signup.cgi and sign up as an affiliate. NOTE: in the extras/HTMLforms folder there are some example template signup forms and stats login pages that you can customize. Make sure the forms point to the appropriate scripts.

8. Log into the stats.cgi page and see if you are logged in successfully.

9. At the stats.cgi main page, click on the affiliate link at the bottom, make sure you are sent to the right page, then go back and reload the stats page to see if the "hit" was logged.

10. Log into the admin.cgi script and make sure it's tracking everything correctly.

11. Move on to part three - integration with your existing payment system.

12. A FEW WAYS TO REDUCE FRAUD IN THE AFFILIATE PROGRAM:

• to be absolutely "hackerproof" I would recommend making sure all files are chmoded 755 after the script is working properly (this means changing config.cgi and common.cgi to 755.
• You can place admin.cgi, common.cgi, and config.cgi in their own .htaccess protected directory. All you need to change is to add the FULL PATH to the "required files" at the top of all the scripts that aren't in this directory.
• You can rename both clickthru.cgi AND sale.cgi and the script will still work fine.
   
• I would definitely recommend renaming sale.cgi so someone couldn't guess it.
   
• The IP tracking is the best way to prevent duplicate commissions from people re-triggering the system. It's best to set this to a couple of hours.
• Many people integrate the commission triggering routines directly into their shopping system. This is the ONLY true way to prevent fraud.
• Use the secret word at the admin page. You can set that word there - then add the "secret=SECRET" variable to the code that triggers the commission.

ADDING EXTRA FIELDS:

The script now comes with 5 empty fields you can use to store more info about your affiliates and also include this info in the replicated websites. Adding these fields is user-friendly, just go to the admin configuration page and add the fields at the bottom. Only the ones you fill in will be shown to your affiliates for editing.

In your signup form, however, you MUST call these fields Field1, Field2, Field3, Field4, and Field5 because those are the names used to insert the info into the database. For example, if you want a new field called "Favorite Book" you would go to the admin configuration page and name Field 1 "Favorite Book", then in your signup form (using our stand-alone html template forms makes this easier) just add some code like this:

Favorite Book: <input type=text name=Field1 size=30>

That's it - the info should be added to the database and the affiliate can even edit their "Favorite Book" at the stats page.

RECURRING COMMISSIONS:

All you need to do is edit the first two "require" lines in recur.cgi to contain the FULL PATH to config.cgi and common.cgi. Then, you must set a crontab job to execute the recur.cgi once a day. Remember to set the appropriate recurring time period at your admin configuration page.

IMPORTING YOUR OLD UA DATA:

Also included is a script called convert.cgi that will transfer all your existing UA2000 text version data over to the MySQL database. TO RUN THIS PROPERLY, you must have the old UA2000 "data" directory in the same directory as the convert.cgi script. This means you either have to copy UA-SQL into the old UA2000 directory OR copy the old "data" directory into the new folder of UA-SQL.

UPGRADING FROM THE OLD MYSQL SCRIPT TO THE NEWEST VERSION:

Basically, you can just copy the cgi scripts over the old ones, run admin.cgi, and reconfigure any new variables that appear blank. If you are upgrading from a version prior than February 2002, you'll need to run the transfer.cgi script (in the /extras/upgrade_old_mysql_version_to_new folder in the zip file) to import the old hits into the new system.

PLACING THE AFFILIATE'S NAME INTO HTML PAGES:

Also included is a script called getcookie.cgi which when called by a special javascript tag will put the affiliate's name in an HTML page or order form. This script is found in the "extras/Developer Tools " folder of the zip file. When calling getcookie.cgi with a javascript tag in an HTML page it will print out "Id: AFFILIATE" in place of the tag. You can edit getcookie.cgi to print out anything you want, from a hidden form tag to a paragraph of info. Just don't use any quotes (") in what you want to print out. Here is the tag you can call the script with - make sure to edit the url to getcookie.cgi:

<SCRIPT LANGUAGE="JavaScript1.1" SRC="http://www.yoursite.com/cgi-bin/affiliates/getcookie.cgi"></SCRIPT>

CALLING CLICKTHRU.CGI AS A "DIRECTORY":

You can now have shorter affiliate urls AND also have the ? removed from the url:

http://www.yoursite.com/g.o/affiliatename or
http://www.yoursite.com/cgi-bin/affiliates/clickthru.cgi/affiliatename

This is nice because people can promote their affiliate urls in the search engines.

To do this you must set configuration variable #4 to YES, then you can rename clickthru.cgi to anything you want. In configuration variable #3 you need to modify the url to clickthru.cgi as such:

http://www.yoursite.com/cgi-bin/affiliates/clickthru.cgi/<username>

It's essentially the full url to clickthru.cgi (or whatever you name it) followed by a slash and the tag that gets replaced by the affiliate's username.

Now, you can also place clickthru.cgi in your main directory IF you can execute cgi scripts there. You can also place the .htaccess file that you can find in the "extras/affiliatetools" folder of the zip file in any directory and have cgi scripts executed there. You MUST open the .htaccess file and rename the extention you want to use as a cgi script. For example, by default the .htaccess file will execute any file with the extention ".o" as a cgi script - this is for when you rename clickthru.cgi to g.o and place it in your main directory.

Also, you need to edit clickthru.cgi (or whatever you name it) where you see:

require "config.cgi";
require "common.cgi";

You need to put the FULL SERVER PATH to both of these files. You only need to do this if you placed clickthru.cgi in a different directory than those two files.

PART THREE - INTEGRATING THE SCRIPT WITH YOUR EXISTING SYSTEM
 

Both the good and the bad part of Ultimate Affiliate is that you can pretty muchintegrate it with any billing, shopping cart, or payment system that is out there.In fact, I have yet to find a program that is compatible with any other affiliate system and is not compatible with UA. So, that said, with a little (maybe a lot?) of work and asking Groundbreak.com for support help you can get it integrated.

For the uninitiated, "integration" means this: In order for UA to give commissionson purchases at your site - it needs to be "triggered" by your existing payment system to register the commission. Also, if you accept different amounts of money and want to give a percentage commission, you must also pass the final purchase price to UA so it can calculate the commission.

Here is a run down of the ways to do this:

FIELDS USED TO TRIGGER A COMMISSION IN SALE.CGI
 

In every circumstance, you will be triggering a commission by executing sale.cgi in some manner. Here is a list of the variables that you can send sale.cgi during this process:

Example link:
http://www.yoursite.com/cgi-bin/affiliates/sale.cgi?cashflow=AMOUNT&goods=INVOICE&secret=SECRET

cashflow: This is the ONLY required field and should contain the final purchase price that the percentage based commission is calculated with.

goods: This is an extra field that you can use to record an invoice number or other tracking variable that you can use to match sales to commissions. Instead of "goods" you can also use "extras".

secret: At the admin.cgi configuration page you can set the "secret" variable for sale.cgi. If you create a secret word you MUST include it in the sale.cgi trigger code as the "secret" variable.

recur: You can use this field to make a commission recurring, even if you have recurring turned off at the admin page. The only valid values for this variable are DAILY, WEEKLY, MONTHLY, and YEARLY. Only valid if you turn on "allow extra variables sent to sale.cgi" at the admin configuration page.

affiliate: If your payment system can carry the referring affiliate's username through to sale.cgi, you can send it to sale.cgi in this variable and the script will consider this affiliate to be the referring affiliate. This bypasses the cookie/IP routines that find the referring affiliate's username. Only valid if you turn on "allow extra variables sent to sale.cgi" at the admin configuration page.

IF YOUR EXISTING SYSTEM IS A PERL SCRIPT
 

When integrated with an existing perl-based shopping cart, most likely you will need to own your own secure certificate for your domain name. This is because cookies can only be written and read from the same domain name, so if the script runs on http://yoursite.com and your shopping system uses your hosting companies secure domain https://securesite.com then it won't work because the cookies can't be read. In this case you need both http:// and https://yoursite.com. Secure certificates cost $125/yr from http://www.thawte.com.

You'll probably have to know a little about Perl to do this. Open up your existing script and look through it for the subroutine that calulates the final purchase. Often you'll find the "email" that gets sent out after a purchase or the "redirect" to the URL you want after the purchase. You'll be putting in the code around these areas. Just remember, it HAS to get EXECUTED at the FINAL stage of the purchase ONE TIME ONLY.

At the admin page, you'll have to set the "Call the sale script as:" variable as a "subroutine".

Then, open sale.cgi and comment out "require config.cgi;" and "$cashflow = $q->param(cashflow);" at the top of the script (place a "#" in front of those two lines).

Finally, in your shopping cart or payment processing script, put in these lines:

use CGI::Carp qw(fatalsToBrowser);
use CGI qw (:standard);
$q = new CGI;
require "/full/path/to/config.cgi";
require "/full/path/to/common.cgi";
require "/full/path/to/sale.cgi";
$cashflow = $amount; #where the $amount is whatever variable contains the final purchase price.
&salecommission; #executes the commission subroutine

Then, do some testing to see if it works, remember, if you are using the IP checking to prevent double commissions, you'll have to wait ten minutes between tries (or turn this function off at the admin page).

CALLING THE SCRIPT VIA THE "IMAGE TAG" METHOD
 

This is probably the most versatile way to call the script. It can be done with shopping carts written in Perl or other languages as long as they allow you to "customize" the thank you page with the final purchase amount.

At the admin page, set the "Call the sale script as:" variable as a "image tag".

You must also upload the "invisible.gif" image to a non-cgi directory on your server. Then, at the admin page, set the "Path to the invisible graphic" to the /full/path/to/invisible.gif

Finally, put the image tag in your "thank you" page:
<IMG SRC="http://www.yoursite.com/cgi-bin/affiliates/sale.cgi?cashflow=$amount" border=0>

Notice that "$amount" should be replaced with whatever tag carries your final purchase price.

That's it! Whenever this image is called the script will register the commission.

To test the script out - turn off the IP tracking after a sale and referral checking, then
execute sale.cgi in your browser and you should get a blank page (the little invisible image
tag is actually in the top left of the screen). Then, you can even see if commissions are
being tracked by type in the full sale.cgi url with the cashflow variable:

http://www.yoursite.com/cgi-bin/affiliates/sale.cgi?cashflow=20

Where 20 would be the example final purchase price...

CALLING THE SCRIPT AS A "SCRIPT"
 

In this method, you are either forwarding the user directly to the sale.cgi file after a sale - or you are having them click on a link which will send them to sale.cgi (registering the commission) which then redirects them to a "thank you" page of your choice. They will not know they were sent to sale.cgi...

At the admin page, set the "Call the sale script as:" variable as a "script".

Then, have your payment system either forward the user as a POST or GET method to the URL of sale.cgi. Now, if you have a singly priced item and want a flat fee commission. Set the script that way and that's all you'll have to do.

However, if you want percentage commissions, you'll have to have your system forward the user to:
http://www.yoursite.com/cgi-bin/affiliates/sale.cgi?cashflow=$amount
where your system will substitute the "$amount" for the final purchase price. For example, www.authorize.net can be set to do this in their administration page. You can send them by a link button on your "thank you" page or silently with a silent "POST" to the sale.cgi script.

CALLING THE SCRIPT AS A "JAVASCRIPT POPUP"
 

This is the newest addition to to different ways you can integrate the program with your existing system. You should use this method if you can pass your final price to the thank you page - BUT, the thank you page is on a different "secure" server than the rest of the scripts.

You see, cookies can only be written and read from one domain name - so if you installed Ultimate Affiliate on one domain and want to call the script from your "virtual" secure server the cookie will not be read.

This method pops up a small window that says "thank you" and then quickly dissappears. But it's actually calling the sale.cgi using your normal non-secure URL. The buyer doesn't get any messages about security, and this method is completely safe for your customers.

Here we go. After you've set the correct variables in the admin page (ie. changed the settings to "javascript popup") you need to add this code to your thank you page. It needs to be placed anywhere between your <HEAD></HEAD> tags. After the <TITLE> tag and before the <BODY> tag:

<script>
window.open('http://www.yoursite.com/cgi-bin/affiliates/sale.cgi?cashflow=AMOUNT&goods=INVOICENUMBER',"","width=300,height=150")
</script>

Notice that you need to replace the AMOUNT with the variable that will be replaced by the price in your thank you page. The same goes for the INVOICENUMBER Then test it out to make sure it's working with your system.

You can edit the HTML in the little window by opening sale.cgi and scrolling down to the bottom. You'll see a little snippet of HTML right after the words "javascript popup".

FINALLY, MAKE SURE TO WRITE GROUNDBREAK.COM SUPPORT FOR HELP AS WELL AS CHECKING OUT
THE SUPPORT FORUMS FOR PEOPLE WHO MAY HAVE HAD THE SAME PROBLEM.

GOOD LUCK!