Documentation
AGENTS UNLIMITED:  V9.0

WARNING - THIS IS FARILY ADVANCED CGI CODE

Our support policy confines us to answering SPECIFIC questions about the installation.  We do not teach perl, systems configurations or unix as part of the membership.   If you require this level of support you will have to pay for installation.   Feel free to give it a shot - if you have the time and like to learn you are on the right page.  For more information regarding support policies read the FAQ.  If you prefer to have the system installed for you simply contact PSYBERCORE to have this arranged.

Preleminary Material for review

System Requirements

  • Perl 5
  • Mysql Database Software
  • Msql-Mysql Module
  • DBI Module
  • Sendmail
  • Crontab Recommended for Backups
  • Ability to communicate with billing software
  • Password protection ability recommended
  • Unix recommended

Preliminaries

  • Determine the path to PERL 5 on your web server host.  Note that some web hosting companies run both PERL 4 and PERL 5.  Make ABSOLUTELY sure you are not setting this up under PERL 4.  Ask your administrator if you are not sure.
  • You need to have MYSQL, the MYSQL-MSQL MODULE, and the DBI PERL MODULE installed for this software to work. 
  • If you need to review or learn the basics of CGI and Perl visit THE TUTORIAL
  • Download the tarfile for this program and save it to your desktop.
  • Unpack the tar archive on your desktop using a program that unpacks UNIX TAR ARCHIVES. If you don't have such a program then download WINZIP FREE from SHAREWARE.COM
  • After you have unpacked the TAR archive you will have a collection of folders and files on your desktop.  Now you have to do some basic editing of each of these files (or at least some of them).  Use a text editor such as wordpad, notepad, BBEdit, simpletext, or teachtext to edit the files.  These are NOT WORD PROCESSOR DOCUMENTS they are just simple TEXT files so don't save them as word processor documents or save them with extentions such as .txt or they will NOT WORK.   Note that there may be a some files inside of folders which are "blank".   This is normal.

Preparing the CGI scripts

Define Path To PERL 5

The first step is to open up each and every file that has a .cgi extention and edit line number one of each script.  Each of the cgi scripts is written in perl 5. For your scripts to run they must know where perl 5 is installed on your web server. The path to perl 5 is defined to a cgi script in the first line of the file. In each of the cgi scripts the first line of code looks something like this:

#!/usr/bin/perl

If the path to perl 5 on your web server is different from /usr/bin/perl you must edit the first line of each cgi script to reflect the correct path. If the path to perl 5 is the same no changes are necessary. If you do not know the path to perl 5 ask the webmaster or system administrator at your server site.  

Setup your MYSQL tables

The .sql file is included inside of the tarball for this cgi system.  Upload the .sql file into mysql before installing the cgi scripts.  Without the .sql file already in place nothing is going to work.  See the MYSQL TUTORIAL for more information or ask your system administrator to to this for you.

Configure the .cgi files

configure.cgi

This file pretty much runs the whole show.  If you screw this one up don't count on anything working properly.   In other words, make sure you take the time to do this step CORRECTLY.  Ask your administrator for help if you need to.  Below are the variables used in ALL of the other cgi scripts.  All of the other cgi programs use configure.cgi to figure out where certain things are.

SECTION ONE (commission geneology)

  • $mlmcode = "geneology";    you don't really need to change this variable
  • $reward[0]=0;  these are explained below
  • $reward[1]=0;
  • $reward[2]=0;
  • $reward[3]=0;
  • $reward[4]=0;
  • $reward[5]=0;
  • $reward[6]=0;
  • $reward[7]=0;
  • $reward[8]=0;
  • $reward[9]=0;

The reward depth variables are the commission values for each successive payout level.  $reward[0] is the highest value and $reward[9] is the lowest.  You can add as many levels as you want although we only deal with 10 levels by default and in this discussion (0-9).  To get a clearer idea of how these variables work let me give an example.  Say we want to pay flat rate commissions to our affiliates.  We want to pay $10 to the person that actually send the sale, then $9 to the person that referred the affiliate, $8 to the the person that referred the person that referred the affilaite, $7 to the next and so on...  We set our geneology variables like so:

  • $reward[0]=10;
  • $reward[1]=9;
  • $reward[2]=8;
  • $reward[3]=7;
  • $reward[4]=6;
  • $reward[5]=5;
  • $reward[6]=4;
  • $reward[7]=3;
  • $reward[8]=2;
  • $reward[9]=1

Remember that $reward[0] is the person actually sending the sale.  The ones further down ($reward[9] being the furthest) are the people that through time actually send the affiliate.

Now let's look at another example.  Say we want to pay a percentage of the sale starting with 10% of the total to the primary affiliate, 5% to the secondary, 4% to the next until we hit zero.  First we have to pass the $total dollar amount of the sale to configure.cgi from your billing software.   For simplicity lets assume that your billing software (call it billing.cgi calculates the total dollar amount of the sale and passes it into a variable called $totalsale.  Then we add another line into configure.cgi and adjust our geneology variables as follows:

  • $reward[0]=.10 * $totalsale;
  • $reward[1]=.05 * $totalsale;
  • $reward[2]=.04 * $totalsale;
  • $reward[3]=.03 * $totalsale;
  • $reward[4]=.02 * $totalsale;
  • $reward[5]=.01 * $totalsale;
  • $reward[6]=0;
  • $reward[7]=0;
  • $reward[8]=0;
  • $reward[9]=0;

Now we have effectively made this a 6 level program.  In a similar manner if we wanted to create a 50 level program we would just add more $reward levels up to $reward[9999999] or whatever.  Obviously you have to make sure you do not "bankrupt" the system though since if you are paying more commissions than the amount of the sale you won't be making any money right?

SECTION TWO

The rest of the variables are pretty straightforward - just a bunch of paths and urls as usual...  See the documenation for AGENTS PRO if you need more clarification on these variables as they are fairly similar.

  • $joinurl = "http://www.affiliatedomainname.com/agents/index.html";
  • $joincgi = "http://www.affiliatedomainname.com/cgi-bin/agents/join.cgi";
  • ###########################################################################
  • # PAYOUT http://www.affiliatedomainname.com/cgi-bin/agents/payout.cgi?$identity&$total
  • $localurl = "www.affiliatedomainname.com";
  • $agentcode = "agentspro"; #DO NOT USE SPACES THOUGH
  • $mysqldatabase = "mysql database name";
  • $mysqlusername = "mysql username";
  • $mysqlpassword = "mysql password";
  • $mailprogram='/path/to/sendmail';
  • $adminemail = "you\@yourdomain.com";
  • $webmasterurl = "http://www.affiliatedomainname.com/agents/webmasters/";
  • $cgiurl = "http://www.affiliatedomainname.com/cgi-bin/agents";
  • $clickthroughurl = "http://www.targetdomain.com/";
  • $cgidirectory = "/path/to/cgi-bin/agents";
  • $datadirectory = "/path/to/cgi-bin/agents/data";

Upload Your Edited CGI and Database Files

  • Upload all of the cgi files (.cgi) into a directory you create called "agents" inside your cgi-bin (http://yourdomain/cgi-bin/agents)
  • Make a new directory inside of your /cgi-bin/agents folder data
    • http://yourdomain/cgi-bin/agents/data/

    Note there are 3 files inside the data folder (schedule.db, passwords, and memberdatabase) all of these 3 files except schedule.db are just blank text files.   schedule.db is a database for organizing your pay periods.  Clear out any blank lines inside of the "passwords" and "membersdatabase" files before uploading them.

Upload The Edited HTML Files

  • Make a directory inside of your webspace called agents (http://yourdomain/agents/) and 2 directories inside of this called webmasters and admin (http://yourdomain/agents/webmasters, http://yourdomain/agents/admin)
  • Modify the form action tags of the admin (index.html) page and the webmasters (index.html) page and upload these into their respective directories.
  • If you are not allowing textlinks then you will want to customize the banners.cgi html output so it doesnt give instructions for text links.  Simply edit the html in between the ENDHEADER markers inside of banners.cgi

Password Protect the admin Directory

SEE THE TUTORIAL FOR INSTRUCTIONS FOR PASSWORD PROTECTING DIRECTORIES

Upload Your Banner image(s)

  • Upload your banner(s) into the http://yourdomain/agents/webmaster directory. 

WHEN YOU ARE FINISHED...

http://www.yourdomain.com/agents/index.html

    SIGNUP PAGE FOR NEW AFFILIATES

http://www.yourdomain.com/agents/webmasters/index.html

Where users will login to get bannercode, check stats, modify info

http://www.yourdomain.com/agents/admin/index.html

Password protected admin area

ALL CGI will be http://www.yourdomain.com/cgi-bin/agents/

File Access Permissions

File access permissions must be set correctly for this program to run. The table below lists the permissions of each file which are to be set by the unix command ( chmod ) used to set the correct access permissions. You must set the access permissions for each of these files.  As usual you will set all .cgi files to 755 (rwx-r-x-r-x)and all other files and directories to 777.


Interfacing Your Billing System

See the AGENTS OF FORTUNE files for the other version for examples on interfacing into DMR and IBILL

payout.cgi (distributing the commissions)

payout.cgi is the script that actually causes commissions to be distributed.  By default the script is setup to work by passing a "QUERY STRING" to payout.cgi of the following format:

http://www.yourdomain.com/cgi-bin/agents/payout.cgi?$identity&$total

where $identity is some type of unique identifier used to track the sale (such as an email address or username).  $total is the $total dollar amount of the sale.

So what happens is after your shopping cart or whatever finishes a sale you should have the RESULTS page print out the URL inside of an image tag like this

http://www.yourdomain.com/cgi-bin/agents/payout.cgi?buyer@whatever.com&55.95

This tells payout.cgi that buyer@whatever.com just spent $55.95 at your website and then payout.cgi figures out who the commissions should go to after that.

Alternatively you can also call payout.cgi from inside your billing cgi the same way you would from the other AGENTS programs (see documentation for agents of fortune)  If you choose to execute payout.cgi that way you will need to comment out the following lines inside of payout.cgi so they don't cause problems.

  • $query = "$ENV{'QUERY_STRING'}";
  • ($identity,$total) = split(/&/,$query);
  • &payout;
  • print "Content-type: text/html\n\n";
  • print "\n\n";

The key thing to remember is TWO VARIABLES are required by payout.cgi to distribute commisssions.  $total (which is the total dollar value of the sale) and $identity (which is any unique identifier you can use to track who made the sale - such as the email address or username of the purchaser)

Example executing from SSI

You can also execute payout.cgi from a server sides includes tag.  This will only work if the cgi software is installed on the same server as your billing software.  The routine will have to be modified slightly to retrieve the proper information (the cookie from ENV(REMOTE_USER).  This executes the payout routine the first time the new user logs in.  You may have to rename your page to .shtml instead of .html on some machines - ASK your system administrator the requirements on your server to execute SSI.

<!--#EXEC CGI="/cgi-bin/agents/payout.pl" -->

Note that your members directory MUST be password protected with .htaccess in order for this to work

Cookies, IP's and Ports

If you haven't guessed by now, Agents of Fortune uses COOKIES to keep track of commissions.  When an surfer clicks on one of your affiliates banners a cookie is set inside their browser and remains there until something like the year 2003.  Anytime that visitor returns to your site and buys something payout.cgi sucks the cookie out of the browser and writes to a database the commission information.  Likewise if this surfer also signed up for your affiliate system the cookie would write to a database and Agents would know that this new affiliate was referred to you by someone else.  The secondary commission information is all tracked in the member databases. 

The thing about cookies (and its a good thing) is that you can only retrieve cookies that you sent.  This means it is totally IMPOSSIBLE for you to read all the cookies in my browser that have been set by 100's of other websites tracking my behaviour.  Cookies can only be read from the exact same IP address and PORT that they were set by.

The reason this is very important is that if you have your billing system on a secure server (using port 443) then payout.cgi would be executed on port 443.  If this is the case agents.cgi (which sets the cookie) but also be executed on port 443.  Thus you cant have the URL to agents.cgi be something like       /agents.cgi and the URL to payout.cgi be something like  https://www.superscripts.com/payout.cgi   They have to be executed on the exact same DOMAIN and PORT.  This may also apply depending on how your isp sets up their webserver on the www domain alias.   Some ISPs setup yourdomain.com on different IP's than the www.yourdomain.com alias.

Crontab newday.cgi

The newday.cgi file must be set to execute every day at midnight.  If you dont do this, your stats will become corrupted.  You also need to make sure the "require" statements are set to ABSOLUTE PATHS on most systems for them to properly function.  See example below taken from newday.cgi

require "/home2/superscripts.com/htdocs/test/agentsmlm/cgibin/configure.cgi";

Operating your Affiliates Program

START THE SYSTEM

From telnet cd to the cgi-bin/agents directory and run start.cgi

perl start.cgi

ADMINISTRATION

The administrative interface is basically a navigational and editing interface.  If you take a little time to push buttons you will see how it works.  You can zoom into the statistics from any point starting at the yearly overview and zooming into the individual users statistics.   From the payout menu you can revoke sales or delete affiliates.

EXPORTING PAY TABLES

The payout menu allows you to export the current pay period sales data into a flat file ASCII delimited database which is stored inside the /cgi-bin/agents/logs directory.  The file will be called #.payout.txt where # is the numerical value of the current pay period.  This database structure is set by default to be seperated by the pipe character |

CHANGING PAYOUT SCHEDULES

The file inside of /cgi-bin/data/schedules.db is a table of the pay periods broken up into one pay period per line.  The default pay schedule consists of 24 periods (24 lines).  There are no restrictions to how you can restructure this table.  Make sure you do NOT have any extra blank lines in this file however or it will totally throw off your statistics.