Documentation
AGENTS OF FORTUNE PROFESSIONAL: V9.0
WARNING - THIS IS FAIRLY 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
Zip File for this program and
save it to your desktop.
- Unpack the Zip archive on your desktop using a
program that unpacks Zip Files. If you don't have such a program then download
WINZIP FREE from SHAREWARE.COM.
- After you have unpacked the
Zip 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
|