The Beginning: MySQL
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's quite simple
- just send an email to your ISP's support saying:
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.
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
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> use yourdatabasename <<RETURN>>
And it should
say "database changed".
THIS MEANS YOU ARE GOOD TO GO!
2. SETTING UP THE SCRIPT
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
... 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
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
- 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
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:
<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.
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.
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
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
HTML page or order form. This script is found in the "extras/Developer
Tools " folder of the zip file. When calling getcookie.cgi
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:
CLICKTHRU.CGI AS A "DIRECTORY":
You can now have shorter affiliate urls AND also have the ? removed
from the url:
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:
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
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:
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.
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:
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:
This is the ONLY required field and should contain the final
purchase price that the percentage based commission is calculated
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".
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.
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.
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.
YOUR EXISTING SYSTEM IS A PERL SCRIPT
with an existing perl-based shopping cart, most likely you will
need to own your own secure certificate for your domain name. This
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.
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).
your shopping cart or payment processing script, put in these lines:
use CGI qw (:standard);
$q = new 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).
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
At the admin
page, set the "Call the sale script as:" variable as a
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
the image tag in your "thank you" page:
"$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
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
Where 20 would
be the example final purchase price...
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
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.
you want percentage commissions, you'll have to have your system
forward the user to:
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.
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
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.
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
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:
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
SURE TO WRITE GROUNDBREAK.COM SUPPORT FOR HELP AS WELL AS CHECKING
THE SUPPORT FORUMS FOR PEOPLE WHO MAY HAVE HAD THE SAME PROBLEM.