Documentation
AGENTS OF FORTUNE PROFESSIONAL:  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

Upgrading?

It is NOT possible to upgrade from AGENTS OF FORTUNE to the PROFESSIONAL VERSION

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.  These are all included in the tarball.
  • 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.  

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.

$localurl = "yourdomain.com";

Your domain name

$agentcode = "pickaname";

Use a UNIQUE name for your site (for example - "myaffiliate", or "salesagent") DO NOT USE SPACES

$mysqldatabase= "agentsdatabase";

Name of your mysql database.   If you are using a seperate mysql server Set $mysqldatabase to databasenameServername

$mysqlusername= "your mysql username";

Username used to login to MYSQL

$mysqlpassword= "your mysql password";

Password used to login to MYSQL

$mailprogram='/path/to/sendmail';

Full path to SENDMAIL on your webserver

$adminemail = "you\@yourdomain.com";

Your email address (YOU HAVE TO USE THE BACKSLASH HERE!)

$webmasterurl = "http://www.yourdomain.com/path/to/agents/webmasters";

Full URL to the webmasters  directory containing the login form

$clickthroughurl = "http://www.yourdomain.com/";

This is the FULL URL where people will be sent after clicking on your banner.

$cgidirectory = "/path/to/cgi-bin/agents";

This is the FULL PATH to the agents directory containing the .cgi files

$cgiurl = "http://www.yourdomain.com/cgi-bin/agents";

Full URL to the agents directory containing the .cgi files

$datadirectory = "/path/to/agents/data";

This is the FULL PATH to the agents data directory. By default is /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.

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.

 CHMOD 755

 CHMOD 777

  • add.cgi
  • login.cgi
  • banners.cgi
  • bydate.cgi
  • byuser.cgi
  • agents.cgi
  • stats.cgi
  • revoke.cgi
  • premodify.cgi
  • overview.cgi
  • configure.cgi
  • delete.user.cgi
  • export.cgi
  • getinfo.cgi
  • getpayout.cgi
  • modify.cgi
  • payout.cgi
  • newday.cgi
  • start.cgi
  • bysale.cgi
  • data directory and everything inside (schedule.db, passwords, memberdatabase)



Interfacing Your Billing System

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

Edit payout.cgi

The goal is simple - you have to pass THREE variables into payout.cgi and you have to execute payout.cgi after someone purchases from you.  There are numerous ways to do this.  If your billing software is written in perl you can place the following code inside your billing routine (be it formmail, mastergate, etc)

require "/path/to/cgi-bin/agents/payout.cgi";

&payout;

$commission may be calculated from the total dollar value of your sales or set to flat rate values.   Note that any variables you have defined in your billing software (eg:   formmail.pl or whatever) will be passed into payout.cgi.  Calling an external script from your billing software using the & statement is basically just like splicing the payout.cgi code straight into your billing software.  There is no difference between cutting and pasting payout.cgi into your billing software and calling payout.cgi using the &payout; statement.

If you were paying a flat rate structure instead then you would do this:

$commission = 25;

This sets the commission to $25.00

If you were paying a percentage of the total sale and say for example you processed your order with FORM MAIL...  If you had assigned the variable name $total inside of the form mail program to be the total dollar value of this sale and then from inside form mail you called payout.cgi

snippet from your form mail program

"$total = sum of total purchase"

require "/path/to/cgi-bin/agents/payout.cgi";

&payout;

from payout.cgi

$commission = 0.25 * $total;

This would pay your affiliates 25% of your TOTAL sales.  The $total variable was actually calculated inside of your form mail but when payout.cgi was called the variable was passed into this routine.  Note that you have to DEFINE $total you cant just tell payout.cgi to use a variable ($total) without EXPLICITLY defining this variable elsewhere.   This isnt magically going to know what you mean by $total otherwise. 

Identify and Mark Your Sale

Also you have to assign something to the $identify variable inside of payout.cgi so you can match the commission to a specific sale in case you need to revoke it later.  Use an email address, IP number, username or something which will uniquely identify each sale.  Note that you have to actually DEFINE this variable either inside of payout.cgi or inside of the billing routine you are calling payout.cgi from.  This means you have to take an actual variable name from your billing software and set identify to equal this variable.  You could also create the variable inside of payout.cgi if you wanted to.  Note also that the variable $identify is used to track the name of the PURCHASER (not the agent) so you should set it to something like the customers name, email address, or anything that would allow you to mark the sale in case you have to look it up later.

examples:  $identity eq $custname;

this would be good if you are using supercart since $custname is defined inside of mailorder.cgi

or $identity eq $username

good for internet billing proccessor since $username is defined inside of accountcreate.cgi

If you are totally lost at this point I suggest you find a cgi programmer to install this for you.

Example executing from SSI

You can also execute payout.cgi from a server sides includes tag.  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.

Setup your MYSQL database

Inside the folder mysql.stuff you will see the perl modules you need to have installed plus a small readme file with the BASIC commands you need to run this software and a file called agents.sql which sets up the database in MYSQL to store all the required data for AGENTS.  To setup the database simply create a folder inside of /path/to/mysql/agents and upload the agents.sql file as ASCII data.  Then from the command line type

../bin/mysqladmin -u root -p create agentsdatabase

This creates the actual database called "agentsdatabase"

../bin/mysql -u root -pMYSQLPASSWORD agentsdatabase < agents.sql

This loads the database tables into mysql

You should then login to MYSQL to "show tables" and make sure everything got setup correctly

../bin/mysql -u root -p agentsdatabase

If you need help with MYSQL you need to go to the source for information:  MYSQL.COM

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. 

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.

BACKUP PROCEEDURES

It is HIGHLY recommended that you regularly backup your database.  In the event major computer malfunction, power outage, server crash, etc you will be glad you did.  To the MYSQL guru this is easily done by executing the following command by crontab

../bin/mysqldump -u root -pMYSQLPASSWORD agentsdatabase > agentsdatabase.sql

RESTORE DATABASE

To restore your database from a backup you have to DROP your database, recreate the database, then reload the tables with the commands:

DESTROY DATABASE

../bin/mysqladmin -u root -pMYSQLPASSWORD drop agentsdatabase

CREATE DATABASE

../bin/mysqladmin -u root -p create agentsdatabase

CREATE TABLES

../bin/mysql -u root -pMYSQLPASSWORD agentsdatabase < agentsdatabase.sql