COSMICPERL


AffiliateClick User Guide


© Copyright CosmicPerl.com (Lyle Hopkins) 2004. All rights reserved. No part of this or any of the attached documents shall be reproduced/stored in any way whatsoever without written permission from the Copyright holder. The Copyright holder holds no responsibility for errors or omissions. No liability is assumed in any way for damages resulting from the use of this document/program.


Sections in this files

1. Terms of Use IMPORTANT
2. Installation instructions
3. Template editing
4. Integration
5. Testing the system is working
6. Trouble shooting
7. BUG report
8. Getting rid of 'CosmicScripts.com' link
9. Using the script

1. Terms of Use

AffiliateClick is the first completely free affiliate software product made available on the Internet. It may be free, but you must comply to certain terms for any use of this software, commercial or otherwise to be legal.
A) You MUST keep the links back to cosmicperl.com, cosmicscripts.com and allaffiliatepro.com that appear on most of the pages. Removal or attempts to hide these links will result in your use of the software becoming illegal.
B) You MUST NOT re-distribute any of this program in whole or in part for free or for payment without prior consent from CosmicPerl.com
C) You MUST NOT use this software for any illegal sites, or activities.
D) You MUST ensure your affiliate program is tracking properly before launching your affiliate program. Affiliates will not promote you if you are ripping them off.


2. Installation Instructions

Some files need to be opened and modified. To start with, make sure the first line of the file (if it's a script) points to the location of perl on your server. This is usually:
#!usr/bin/perl or #!usr/local/bin/perl. (Make sure you point to perl ver5+)
By default this is #!usr/bin/perl if your path to perl is different you need to change this in each .cgi file.

Setting the Configuration
All the configuration variables are in a file called 'variables.var'. You need to set these variables to your own values in order for the program to work properly. Be very careful when editing this file.

Program Details
$programurl

The folder where you put the program files, such as:-
"http://www.yourdomain.com/cgi-bin/affiliate"

$statsloginurl

The folder where you put the program files, such as:-
"http://www.yourdomain.com/affiliate/login.html"

$companyname This should be your company name. This will appear as the from name in outgoing emails. Example:-
"Cosmic Networks Ltd"
$recipient Your e-mail address. This is the email address that all the programs mailings will be from. Example:-
'webmaster@cosmicperl.com'
$mailprog Change this to your sendmail path on Unix systems or your SMTP server on Win32 systems. Example:-
'/usr/lib/sendmail' or 'mail.cosmicperl.com'
$site1 to $site5 The website(s) you are advertising. This could be just 1 or 5 different sites. Example:-
"http://www.cosmicperl.com"
$currency

Your local currency symbol to use in the program. Example:-
'$' or '£'

$commission

Commission percentage 0 to 100. If you do not want to offer a percentage commission, set this to 0. Example:-
"20"

$flatrate Payment per flat sale, 10 for $10. If you do not want to offer a flat percentage then set this to 0. Example:-
"10"
$minimumpay The minimum commissions a webmaster must have to be included in a pay period. Example:-
"50"
$commissionperiod This is the lifetime of the tracking cookie in days. Example:-
"30"
$data_path The sub-folder in which data will be stored. This must be writeable. Default:-
"data"
$payday_path The sub-folder in which PayDay CSV files will be stored. Default:-
"payday"
$requiredjoinfields List of required join fields, separated by ','. Default:-
"name,address1,city,area,postcode,country,website,email,username,password"
$wipeold Set to 1 to wipe old payperiod data 0 to keep all data. When set to 1 data for this payperiod and the last payperiod will be kept, older data will be removed. Default:-
1
$yearstart Set to the year this affiliate program was started. Example:-
"2004"
$sessiontimeout Time in minutes that a login session can last before timeout. This applies to both the affiliate area and your management area. Default:-
"10"
Tracking Details
$poststyle


0 for GET, 1 for POST. If you're integrating using the 1x1 img tag tracking method this must be set to 0 for GET. You can then ignore the next 3 variables. If you are integrating with a POST back, then you must set the next 3 variables.
Default:-
"0"

$postprice Name of the post variable that contains the amount of the order. Example:-
"amount"
$postid Name of the post variable that contains the unique order ID. Example:-
"id"
$postsent Name of the post variable that contains the unique sales tracking password. Example:-
"enc"
$postredirec The thank you page to redirect to after a sale POST has been received. This is a URL. Example:-
"http://www.yourdomain.com/thankyou.html"
$saletrackpassword Unique sales tracking password for improved security. This must be a unique number that you should update regularly. To disable this feature set this variable to empty "". Example:-
"SFJfhj36"
$policyurl This is the URL to your compact privacy policy. This file is made in the next section, if you already have one you need to adapt your p3p.xml file so that it uses the affiliate tracking policy for your affiliate script folder. This is described later in the template editing section. Example:-
"http://www.yourdomain.com/w3c/p3p.xml"
Message Variables
The following is the message that will be sent to you with the updated affiliate information
$mailhostupdatesubject Message Subject. Example:-
"Affiliate info updated"
$mailhostupdate Message Body. Example:-
"An affiliate has updated their info in your affiliate program.
His details have been listed below\n\n"
The following is the message that will be sent to the affiliate with his updated user information
(This version includes the location of your stats login page, and how to link page.)
$mailuserupdatesubject Message Subject. Example:-
"Your updated Affiliate Info"
$mailuserupdate Message Body. Example:-
"Updated info for our Affiliate program.
For information on how to link to us go to this URL
http://www.yourdomain.com/affiliate/yourhowtolinkpage.html
To view your stats go to this URL
http://www.yourdomain.com/affiliate/yourstatslogin.html

The details in which you updated are listed below\n"

The following is the message that will be sent to you with the amount owed to the webmaster
$mailhostpaydaysubject Message Subject. Example:-
"Affiliate PayDay"
$mailhostpayday Message Body. Example:-
"Affiliate pay due\n\n"
The following is the message that will be sent to the user with his pay message
$mailuserpaydaysubject Message Subject. Example:-
"Affiliate PayDay"
$mailuserpayday Message Body. Example:-
"You have earned the following pay this period\n\n
The following is the message that will be sent to you when a new affiliate signs up with the user information
$mailhostjoinsubject "A new Affiliate has joined"
$mailhostjoin "An affiliate has applied to your affiliate program.
His details have been listed below\n\n"
The following is the message that will be sent to the applying affiliate with his user information.
(This version includes the location of your stats login page, and how to link page.)

$mailuserjoinsubject

"Thanks for joining"
$mailuserjoin

"Welcome to our affiliate program.
For information on how to link to us go to this URL
http://www.yourdomain.com/affiliate/yourhowtolinkpage.html
To view your stats go to this URL
http://www.yourdomain.com/affiliate/yourstatslogin.html

IMPORTANT: A warning to cheaters, this software is
designed to catch cheaters in many ways,
SO BE WARNED

The details in which you signed up with are listed below
To change or update your details go to the stats page\n\n"

All files from the zip file bar join.html, index.html, p3p.xml, policy.p3p, privacypolicy.html and login.html should be uploaded into a sub-folder of your cgi-bin (we recommend a folder named 'affiliate').
ALL FILES, BAR ANY PICTURE FILES, SHOULD BE UPLOADED IN ASCII.
You also need to create the data folder and the payday folder, such as 'data' and 'payday'.
The files join.html, index.html, policy.p3p, privacypolicy.html and login.html need to be uploaded to a folder of your choice outside your cgi-bin (we recommend a folder named 'affiliate'). This is because .html files cannot be viewed inside the cgi-bin. The other .html files must stay in the cgi-bin as they are displayed in through the scripts. The file p3p.xml must be uploaded to a folder named 'w3c', such as 'www.yourdomain.com/w3c/p3p.xml'. If you already have a p3p.xml file, then it must be modified as directed the the template editing section below.

The table below shows what chmod (Unix) each file should be given.

Filename chmod
admingen.cgi 755
adminpass.txt 777
affiliate.cgi 755
affiliate2.cgi 755
cosmic.pm 755
error.log 777
join.cgi 755
manager.cgi 755
sendmail.pm 755
stato.cgi 755
variables.var 444
'data' 777
'payday' 777

The table below shows what file permissions (Win32) each file should be given.

Filename chmod
admingen.cgi read write execute
adminpass.txt read write execute delete
affiliate.cgi read write execute
affiliate2.cgi read write execute
cosmic.pm read write execute
error.log read write execute delete
join.cgi read write execute
manager.cgi read write execute
sendmail.pm read write execute
stato.cgi read write execute
variables.var read
'data' read write execute delete
'payday' read write execute delete

3. Template editing

You can edit the template files using a WYSIWYG HTML editor such as DreamWeaver or AceExpert. You can also edit this file as Raw HTML using a text editor. NOTE:- FrontPage and other editors change the layout of the HTML, this causes serious problems with templates. If you are using FrontPage then please edit Raw HTML.

About the ::symbols::

The symbols such as ::name:: and ::company:: are very important. Our software replaces these symbols with data relating to the customer inquiry. When editing the template do NOT remove these symbols.

TIP:- It is often best to try out this program first with the default templates. This should give you a better idea of where the templates are displayed when you are editing them.

Below is a list of the templates, their symbols with what they represent and other parts that need changing.

INDEX.HTML - This is the template used for your affiliate main page where they can join or login.
You will need to create the tandc.html page for your terms and conditions for your affiliate program. You will also need to give a brief explanation of how your affiliate program works and what commissions you offer.

JOIN.HTML - This is the template used for your affiliates signup form.
You will need to adjust the FORM action to point to the location of join.cgi in your 'cgi-bin'. This looks like:-
<form action="join.cgi?want=stage1" method="POST">
And will need to be changed to something like:-
<form action="/cgi-bin/affiliate/join.cgi?want=stage1" method="POST">
Depending on where you have installed the scripts.

You may also want to remove one of the commission type options if you are offering only a commission or only a flat program. You MUST NOT remove the type field completely. You may replace the selection box with a hidden field such as:-
<input type="hidden" name="type" value="comm">

You may want to use the extra fields. You can use any of these 4 fields to collect the extra information you require. Simply change the HTML text next to the extra field input box. The name of the text box must remain as extrafield1, etc.

There are no symbols in this page.

JOINUP.HTML - This is the template used for your affiliates signup confirmation form.
You will need to adjust the FORM action to point to the location of join.cgi in your 'cgi-bin'. This looks like:-
<form action="join.cgi?want=stage1" method="POST">
And will need to be changed to something like:-
<form action="/cgi-bin/affiliate/join.cgi?want=stage1" method="POST">
Depending on where you have installed the scripts.

You MUST NOT remove the hidden type field. This field looks like:-
<input type="hidden" name="type" value="::type::">

The symbols in this page are:-

::name:: This is replaced for the input affiliates name
::company:: This is replaced for the input affiliates company name
::payee:: This is replaced for the input affiliates payee name
::address1:: This is replaced for the input affiliates address line 1
::address2:: This is replaced for the input affiliates address line 2
::city:: This is replaced for the input affiliates city address
::area:: This is replaced for the input affiliates area address
::postcode:: This is replaced for the input affiliates postcode address
::country:: This is replaced for the input affiliates country address
::website:: This is replaced for the input affiliates website URL
::email:: This is replaced for the input affiliates email address
::ssn:: This is replaced for the input affiliates SSN
::username:: This is replaced for the affiliates chosen username
::password:: This is replaced for the affiliates chosen password
::type:: This is replaced for the affiliates chosen payment type in code form ('comm' or 'flat')
::paypal:: This is replaced for the input affiliates paypal email address
::extrafield1:: This is replaced for the input affiliates extra field 1
::extrafield2:: This is replaced for the input affiliates extra field 2
::extrafield3:: This is replaced for the input affiliates extra field 3
::extrafield4:: This is replaced for the input affiliates extra field 4
::typer:: This is replaced for the affiliates chosen payment type in words (for display to affiliate)

JOINUP2.HTML - This is the template used for your affiliates signup complete page.
You will need to adjust the 'Statistics Area' link so that it points to your login.html page outside your cgi-bin. The HTML code is:-
<a href="login.html">Statistics Area</a>
And will need to be changed to something like:-
<a href="/affiliate/login.html">Statistics Area</a>
Depending on where you have installed the scripts.

The symbols in this page are:-

::name:: This is replaced for the input affiliates name
::company:: This is replaced for the input affiliates company name
::payee:: This is replaced for the input affiliates payee name
::address1:: This is replaced for the input affiliates address line 1
::address2:: This is replaced for the input affiliates address line 2
::city:: This is replaced for the input affiliates city address
::area:: This is replaced for the input affiliates area address
::postcode:: This is replaced for the input affiliates postcode address
::country:: This is replaced for the input affiliates country address
::website:: This is replaced for the input affiliates website URL
::email:: This is replaced for the input affiliates email address
::ssn:: This is replaced for the input affiliates SSN
::username:: This is replaced for the affiliates chosen username
::password:: This is replaced for the affiliates chosen password
::type:: This is replaced for the affiliates chosen payment type in code form ('comm' or 'flat')
::paypal:: This is replaced for the input affiliates paypal email address
::extrafield1:: This is replaced for the input affiliates extra field 1
::extrafield2:: This is replaced for the input affiliates extra field 2
::extrafield3:: This is replaced for the input affiliates extra field 3
::extrafield4:: This is replaced for the input affiliates extra field 4
::typer:: This is replaced for the affiliates chosen payment type in words (for display to affiliate)

LOGIN.HTML - This is the template used for your affiliates login form.
You will need to adjust the FORM action to point to the location of stato.cgi in your 'cgi-bin'. This looks like:-
<form action="stato.cgi?want=enteradmin" method="POST">
And will need to be changed to something like:-
<form action="/cgi-bin/affiliate/stato.cgi?want=enteradmin" method="POST">
Depending on where you have installed the scripts.

MENU.HTML - This is the template used for your affiliates management area page.
You only need to adjust the look and feel of this page. If you are promoting multiple sites you can do so by adding &site=site2, etc, to the end of the affiliate link code.

The symbols in this page are:-

::paydue:: This is replaced for the affiliates current commissions
::session:: This is replaced for the affiliates current session ID
::programurl:: This is replaced for the URL to your affiliate program script folder
::username:: This is replaced for the affiliates username

STATSPAGE.HTML - This is the template used for your affiliates management area stats page.
You only need to adjust the look and feel of this page. If you are only offering percentage commission or only offering flat rate you can remove the code for either details display.

The symbols in this page are:-

::paydue:: This is replaced for the affiliates current commissions
::stats:: This is replaced for the stats display type
::totalsales:: This is replaced for the total number of sales
::salevalue:: This is replaced for the total value of the sales processed
::commissionp:: This is replaced for the commission rate you are offering
::flatrate:: This is replaced for the flat rate per sale that you are offering

UPDATEPAGE.HTML - This is the template used for your affiliates update info page.
You may also want to remove the change type options if you are offering only a commission or only a flat program. You MUST NOT remove the hidden type field.

You may want to use the extra fields. You can use any of these 4 fields to collect the extra information you require. Simply change the HTML text next to the extra field input box. The name of the text box must remain as extrafield1, etc.

The symbols in this page are:-

::name:: This is replaced for the input affiliates name
::company:: This is replaced for the input affiliates company name
::payee:: This is replaced for the input affiliates payee name
::address1:: This is replaced for the input affiliates address line 1
::address2:: This is replaced for the input affiliates address line 2
::city:: This is replaced for the input affiliates city address
::area:: This is replaced for the input affiliates area address
::postcode:: This is replaced for the input affiliates postcode address
::country:: This is replaced for the input affiliates country address
::website:: This is replaced for the input affiliates website URL
::email:: This is replaced for the input affiliates email address
::ssn:: This is replaced for the input affiliates SSN
::username:: This is replaced for the affiliates chosen username
::password:: This is replaced for the affiliates chosen password
::type:: This is replaced for the affiliates chosen payment type in code form ('comm' or 'flat')
::paypal:: This is replaced for the input affiliates paypal email address
::extrafield1:: This is replaced for the input affiliates extra field 1
::extrafield2:: This is replaced for the input affiliates extra field 2
::extrafield3:: This is replaced for the input affiliates extra field 3
::extrafield4:: This is replaced for the input affiliates extra field 4
::typer:: This is replaced for the affiliates chosen payment type in words (for display to affiliate)

UPDATEDONEPAGE.HTML - This is the template used for your affiliates update info complete page.

The symbols in this page are:-

::name:: This is replaced for the input affiliates name
::company:: This is replaced for the input affiliates company name
::payee:: This is replaced for the input affiliates payee name
::address1:: This is replaced for the input affiliates address line 1
::address2:: This is replaced for the input affiliates address line 2
::city:: This is replaced for the input affiliates city address
::area:: This is replaced for the input affiliates area address
::postcode:: This is replaced for the input affiliates postcode address
::country:: This is replaced for the input affiliates country address
::website:: This is replaced for the input affiliates website URL
::email:: This is replaced for the input affiliates email address
::ssn:: This is replaced for the input affiliates SSN
::username:: This is replaced for the affiliates chosen username
::password:: This is replaced for the affiliates chosen password
::type:: This is replaced for the affiliates chosen payment type in code form ('comm' or 'flat')
::paypal:: This is replaced for the input affiliates paypal email address
::extrafield1:: This is replaced for the input affiliates extra field 1
::extrafield2:: This is replaced for the input affiliates extra field 2
::extrafield3:: This is replaced for the input affiliates extra field 3
::extrafield4:: This is replaced for the input affiliates extra field 4
::typer:: This is replaced for the affiliates chosen payment type in words (for display to affiliate)

P3P.XML - This is the xml file used to direct to your compact privacy policy.
You need to adjust the POLICY-REF to point to the compact privacy policy on your server.
<POLICY-REF about="http://www.cosmicperl.com/ace/cgi-bin/policy.p3p#AffiliateClickCookieTracking">
And will need to be changed to something like:-
<POLICY-REF about="http://www.yourserver.com/affiliate/policy.p3p#AffiliateClickCookieTracking">
Depending on where you uploaded the policy file.

If you already have a p3p.xml policy reference file, then you need to update it to include this new policy for the affiliate tracking folder. An example of a reference file pointing to multiple policies is:-
<META xmlns="http://www.w3.org/2002/01/P3Pv1">
<POLICY-REFERENCES>
  <POLICY-REF about="http://www.yourdomain.com/privacy/mainpolicy.p3p#MainPrivacyPolicy">
  <INCLUDE>/</INCLUDE>
  <EXCLUDE>/cgi-bin/affiliate</EXCLUDE>
  <COOKIE-INCLUDE/>
</POLICY-REF>

<POLICY-REF about="http://www.yourdomain.com/affiliate/policy.p3p#AffiliateClickCookieTracking">
  <INCLUDE>/cgi-bin/affiliate</INCLUDE>
  <COOKIE-INCLUDE/>
</POLICY-REF>
</POLICY-REFERENCES>
</META>

POLICY.P3P - This is the compact privacy policy.
You need to adjust the discuri to point to the privacy policy html file on your server.
discuri="http://www.cosmicperl.com/ace/cgi-bin/privacypolicy.html"
And will need to be changed to something like:-
discuri="http://www.yourserver.com/affiliate/privacypolicy.html"
Depending on where you uploaded the policy html file.

PRIVACYPOLICY.HTML - This is the privacy policy html file.
There is no real need to edit this file. If you do so be careful not to corrupt the information it contains.

Everything should now be setup and ready to go. You just need to integrate to track sales and test the system.

4. Integration

There are 2 methods of integration. These methods work with different credit card processors and systems. These methods are based on GET being used with a 1x1 img tag and POST being used with post back.

Most systems use the GET method. This involves adding a 1x1 img tag to your order complete or thankyou page. Such as:-
<img src="http://www.yourdomain.com/cgi-bin/affiliate/affiliate2.cgi?id=ORDERID&amount=ORDERAMOUNT&enc=SALETRACKPASSWORD" height=1 width=1 border=0>
ORDERID must be swapped for your shopping carts or card processors order id symbol that will be swapped for the actual value when a sale goes through. ORDERAMOUNT must be swapped for your shopping carts or card processors order amount symbol that will be swapped for the actual value when a sale goes through. SALETRACKPASSWORD must be swapped for the value of your $saletrackpassword variable.

Some systems use the POST method. This is where your card processor or shopping cart posts back to a script on your server after a sale. This post includes information such as the order ID and amount. To use the sales tracking password feature you will need to use a passthrough variable with your cart/processors post back system. You must set the $postprice, $postid and $postsent variables to the names of the associated post back fields. If $postsent is empty the password will be picked up from the query string &enc=.

We have started a page where people can list the integration methods for the various card processors and shopping carts. You can post a request in the bbs there, and contribute your own findings. Visit:-
http://www.cosmicperl.com/support/affiliateintegration.html

Secure tracking notes:- Some times secure tracking is required. This involves setting up click.cgi and click2.cgi on a secure server along with the securedomain.com/w3c/p3p.xml compact privacy policy file and cosmic.pm. If you do not have access to a secure server, or have access to one that is not willing to upload p3p.xml to the /w3c folder then we can provide you with a secure installation of click.cgi and click2.cgi from cosmicsecure.com. Contact us for details.

5. Testing the system is working

You MUST check that the cookies are being set properly and the sales are being recorded before you launch your program. Failure to do so will be a breach of the terms of use and may well result in legal action against you.

For the management area to be available and for the password encryption to work properly you must first run admingen.cgi. This will automatically test your servers encryption type and set your password.

First check the signup is working by following through the join forms. Then login as the affiliate and test the affiliate link. After following the affiliate link, check your cookies to see that the cookie named AFFILIATE has been set for your domain. Then proceed to place an order. Log back in as the affiliate and check your stats. If the sales was recorded and commission rewarded you are good to go. Otherwise check the file error.log. This file contains any errors recorded by affiliate2.cgi, if no errors have been recorded then the tracking script has not been called so your integration must be checked. This may well mean the URL to affiliate2.cgi is wrong. The errors in the error.log should direct you to where the problem lies so that you may fix it.

6. Trouble shooting

As this script is free we do not offer free support on this product. You may purchase support, installation or integration from us on our site. We also provide a free support forum where you may be able to get the help you need fro other AffiliateClick users.

7. BUG report

If you find any bugs, glitches or problems then please contact me at:

bugs@cosmicperl.com

with the subject "AffiliateClick bug report".

8. Getting rid of the 'CosmicPerl.com', 'AllAffiliatePro.com' and 'CosmicScripts.com' links

On some of the pages there are mandatory links to our sites. Keeping these links is a part of the terms of use of this software package. Removal of these links is illegal. If you want an unbranded affiliate program with many more features and functionality then upgrade to AllAffiliatePro available at AllAffiliatePro.com

9. Using this script

Link to the index.html page so that affiliates can join and login. To access the management area run manager.cgi?want=admin. To do this you will first need to run admingen.cgi to generate your username and password. From the management area you can run reports on affiliate earnings, edit affiliate info, remove affiliates, check affiliate orders, remove orders, email your affiliates and generate a payperiod. You can also update your login password.

When running your affiliate program you must ensure you are tracking sales correctly. When it comes time to generate a pay period do a backup of the data folder first. Generate a pay period ONLY after the month has ended. Pay periods are generated up to, but not including the current month. Make sure you pay your affiliates in a timely manner. Before generating any pay period always check the tracked order id's to make sure no fraudulent orders have been put through.

If you want new features and functionality, and want to upgrade to a fully fledged affiliate program with all the power, bells and whistles then visit allaffiliatepro.com

Good luck with your affiliate program! Check our sites for more free scripts, commercial scripts, and useful webmaster tools and advice.

Free cgi scripts at CosmicScripts.com
Cgi scripts at CosmicPerl.com
Affiliate software at AllAffiliatePro.com

AffiliateClick powered by CosmicPerl.com
affiliate software from the makers of AllAffiliatePro
free cgi scripts from CosmicScripts.com
cgi scripts from CosmicPerl.com