Associate Engine : Download & Installation

 
Home > Associate Engine > Documentation > Download & Installation   Updated: 28-Oct-2010

Download & Installation

Browse Download & Installation
 


Free Demo / Full Version

The free demo and the full version are the same thing.

Download the demo software.

Then, to convert the demo into the full version, purchase a 1-year license and we will email a special file to you called a "key" that unlocks the full functionality of Associate Engine.

Once you receive your key file, upload it into the same directory where you installed the Associate Engine ae.pl file. This will convert the demo into the full version.



Download & Installation

Follow the instructions in this section to get the Associate Engine script (the free demo version or the fully-functional version) running on your server. Once you get the script running you can read the rest of the documentation.

A video tutorial is available showing how to install Associate Engine.
Click here to view the video tutorial (or view video on YouTube.com)




 

IMPORTANT: In the demo version, all links go to http://www.amazon.com (the amazon.com home page). In the demo version, links do not go to individual product pages and your amazon.com affiliate ID is not tracked. To turn the demo version into the full version that does use your amazon.com affiliate ID and links to individual products, you must purchase a license.

You can request a FREE temporary key that turns the demo into the full version for a limited time (1 month). Click here to request a key.

Note: The following instructions are for installing Associate Engine into your cgi-bin directory as ae.pl. It is possible to install Associate Engine into a subdirectory of your cgi-bin directory and/or to rename ae.pl to a different filename such as shop.pl

amzon.co.uk users: To have search results based on amazon.co.uk, see: Using Associate Engine with amazon.co.uk.

  1. Get .zip file:

    Obtain a copy of the free demo version of the Associate Engine script. Note: by using this script, you confirm that you have read and agree to the License Agreement.

    To download the free demo version: Go to http://www.c3scripts.com/amazon/release/ and move your mouse over the .zip file (or over the .tar.gz file if you prefer that format) and click the right button of your mouse and select "Save Target As..." (or something similar) to save the Associate Engine script to your computer.

    To purchase the fully-functional paid version: click here for purchasing instructions

  2. Extract files from .zip:

    Extract the files from the .zip file to your Windows computer (or from the .tar.gz file to your server).

    Note: When unzipping the .zip file, be sure that your compression software is configured to recreate the .zip file's internal directory folder structure when unzipping, otherwise all the files will end up in one directory. For example, in WinZip, select menu item "Action > Extract..." and select the "Use folder names" checkbox option.

  3. Set path to perl:

    Using a plain text editor, such as the Windows Notepad, edit the ae.pl file as follows:

    • To run a script program written in Perl, your web server uses a program pre-installed on your web server called "perl". The first line of the script tells the web server in which directory the perl program is located. The perl program is typically at "/usr/local/bin/perl". The first line of the ae.pl file is: (the #! are required):

      #!/usr/local/bin/perl

      This setting works as is on most web servers. If this does not work, then ask your web server administrator what the location of the perl program is. If you have access to the server's unix/linux command prompt, try typing the command "where perl" or "which perl". This will show you the location of the perl program.

      If necessary, change the first line of the script so it indicates the location of the perl program on your web server.

  4. Upload /cgi-bin/ae.pl:

    Use an FTP program to upload the ae.pl file to your cgi-bin directory. VERY IMPORTANT: Use ASCII transfer mode when uploading this file..

    Your web server may be set up in such a way that you might need to call the file "ae.cgi" or "ae" (no extension). On some web servers, the directory might be called "cgi". If you're not sure, ask your web server administrator.

    NOTE: Be sure to upload the file using ASCII transfer mode. If you don't upload the file using ASCII mode, you will probably see a "500: Internal Server Error" error when you try to run the script.

    If you are using the FTP program called WS_FTP, click the "ASCII" button at the bottom of the screen. If you are using the FTP program called CuteFTP, select ASCII from the "Transfer > Transfer Type" menu.

  5. CHMOD of /cgi-bin/ae.pl:

    As with any script, you must set the script's file permissions so that the script can be run, that is, make the script executable, CHMOD 755. (Every file on the server has three permissions that can be enabled/disabled: read, write, execute). Do one of the following:

    1. If your FTP program has a CHMOD command, you can use it; CHMOD 755. Select EXECUTE permissions for User, Group, and Other. If you are using WS_FTP, right-click on the ae.pl file in the server window and select CHMOD from the pop-up menu that appears. Note: Do not use CHMOD 777 since some servers do not permit 777 for .pl files.

    2. If you have access to the server's unix/linux command prompt, you can use the command "chmod ugo+x ae.pl" or "chmod 755 ae.pl" (no quotes). This tells the server to change the file permission (chmod is short for "CHange MODe") to include EXECUTE ("+x") for all groups of users (u=user/owner of the file, g=people in your user group, o=other people). Thus anyone can run the script. Note: Do not use "chmod 777" since some servers do not permit 777 for .pl files.

  6. Upload /cgi-bin/ae-ini.txt configuration file:

    Upload the ae-ini.txt configuration file to the same directory where you uploaded the ae.pl file.

  7. Upload /cgi-bin/ae-key.txt key file:

    If you purchased an Associate Engine license, then you will receive a ae-key.txt key file from us. Upload your ae-key.txt file to the same directory where you uploaded the ae.pl file. Without an ae-key.txt file, Associate Engine will run in demo mode and links will not have your associate ID.

  8. Create /cgi-bin/ae-cache:

    On your web server, create directory ae-cache (in the same directory where ae.pl is). Set write permissions on this directory using CHMOD 775. Note: Some web servers require using CHMOD 777 instead. Access ae.pl in your web browser then check to see if the ae-cache directory is still empty. If it is, then use CHMOD 777.

  9. Upload /ae-img:

    If you are using the store templates, upload the ae-img directory (found inside ae-template/store) to the root directory of your website. Images in that directory are used by the store templates. Thus those images will be available at www.mydomain.com/ae-img/*.gif

  10. Upload /cgi-bin/ae-format:

    Upload the ae-format directory to your cgi-bin directory. You should end up with a ae-format directory within your cgi-bin directory.

  11. Upload /cgi-bin/ae-template:

    Upload the ae-template directory to your cgi-bin directory. You should end up with a ae-template directory within your cgi-bin directory.

  12. Review:

    You should end up with directories/files on your web server as shown in the following diagram.

  13. Try running /cgi-in/ae.pl:

    To see if the script works, type the following web address into your web browser:

    http://www.mydomain.com/cgi-bin/ae.pl

    Replace "www.mydomain.com" with your own website address. If necessary, replace "cgi-bin/ae.pl" with the correct path/name of the script.

    A list of the current bestsellers books from amazon.com should appear.

    If you purchased an Associate Engine license: Move your mouse over any of the book links and look at the status line (at bottom-left of your web browser) to see where the link leads to. You should see your amazon.com affiliate ID in the link's address (this does not apply to the demo version which does not insert your amazon.com affiliate ID in links).

    If you see an error, see:

    1. 500 Internal Server Error:

      If your server responds with "500 Internal Server Error", then try the following solutions or see the Troubleshooting section.

      1. Re-uploading the ae.pl file using ASCII transfer mode.
      2. Set the file permissions of ae.pl using CHMOD 755
      3. Check the first line of the script and verify that it indicates the full filename of the perl program. Try changing /usr/bin/local/perl to /usr/bin/perl and see if ae.pl work now. If you don't know which directory the perl program is located in on the server, ask your web server administrator.

    2. "Request has expired. Timestamp date is ..."

      This error means that your server's clock is too far off of the correct time. Ensure that your server's clock is within 15 minutes of the correct time otherwise ae.pl will report this fatal error. This time accuracy is a requirement of Amazon.com web services. To compare the time from your server's clock with the time from an atomic clock, access your AE Configration Report (ae.pl?cfg=CFGVALUE). If you don't have administrator privileges to adjust your server's clock, then set the configuration variable clock.offset to offset the clock (e.g.: "10" to offset the clock forward by 10 seconds, "-10" to offset the clock back by 10 seconds).

    3. "Perl module 'Digest::SHA' is not installed."

      This error means that the Perl module "Digest:SHA" is not installed. Contact your hosting company to install the module. Alternatively, look in the .zip file and upload the entire "Digest" directory (as a whole) to the directory where ae.pl is located. So if ae.pl is in cgi-bin then you should end up with cgi-bin/Digest/SHA/PurePerl.pm

    4. [module name] is not installed:

      If your server responds with "LWP::UserAgent is not installed" or "IO::Socket is not installed", see the LWP Perl Module troubleshooting page.

    5. 404 File Not Found Error:

      If your server responds with "404 File Not Found Error", see the Troubleshooting section.

  14. Get an AWS Access Key from Amazon.com:

    To use Associate Engine, you need to obtain an AWS Access Key from Amazon.com.

    Following the instructions at: AWS Access Key.

  15. Verify cache directories being used:

    To see the current configuration that Associate Engine is using and to verify that the ae-cache and ae-imgcache directories are being used, type the following web address into your web browser:

    http://www.mydomain.com/cgi-bin/ae.pl?cfg

    Replace "www.mydomain.com" with your own website address. If necessary, replace "cgi-bin/ae.pl" with the correct path/name of the script.

  16. Virtual Directory (this step is optional):

    If you want to make Associate Engine appear as a virtual directory, e.g.: www.mydomain.com/amazon/type_best/mode_books (notice that there is no /cgi-bin in this address), then see Virtual Directory for further instructions.

  17. Optimizations (this step is optional):

    We recommend that you read:
    What optimizations can I do to speed up Associate Engine?



File Permissions

The following table summarizes the correct read/write/execute permissions for each file so that Associate Engine can function. In general, it is best to set only those permissions that a file/directory needs. Having excessive permissions set is not desirable because of security issues.

File or Directory CHMOD value User Permissions Group Permissions Others Permissions Comment
Read Write Execute Read Write Execute Read Write Execute
ae.pl 755 R W X R - X R - X Enable ae.pl file to be run.
ae-ini.txt 644 R W - R - - R - - Enable reading of ae-ini.txt file.
ae-key.txt 644 R W - R - - R - - Enable reading of ae-key.txt file.
ae-cache/ 775 R W X R W X R - X Enable reading/writing to ae-cache directory. If files cannot be written to the cache directory, try the alternate below.
ae-cache/
(alternate setting)
777 R W X R W X R W X Enable reading/writing to ae-cache directory. This alternate setting has Other-Write permission set. Some servers may require this permission set.
ae-format/
ae-include/
ae-asin/
755 R W X R - X R - X

Enable reading of the directories that contain read-only data. The files in these directories are not modified by the ae.pl script and thus do not require Group/Others-Write permission.

Note: The ae-include and ae-asin directories are optional. That is, create them only if you are going to use the functionality they provide. You can create them later when you start to use that functionality.

ae-format/*
ae-include/*
ae-asin/*
644 R W - R - - R - -

Set these permissions (644) for each of the files in these directories. Enable reading of the read-only data files. These files are not modified by the ae.pl script and thus do not require Group/Others-Write permission.




Renaming ae.pl

The following section assumes that you have already installed Associate Engine by following the installation instructions above.

The filename ae.pl will appear in URL's such as http://www.domain.com/cgi-bin/ae.pl?type=best&mode=books.

You may prefer to rename Associate Engine to shop.pl so that URL's will use that name, such as http://www.domain.com/cgi-bin/shop.pl?type=best&mode=books

To rename ae.pl to shop.pl (you can pick a different name if you prefer), perform the following steps:

  1. Rename ae.pl to shop.pl
  2. Rename ae-ini.txt to shop-ini.txt
  3. Rename ae-cache directory to shop-cache
  4. Rename ae-imgcache directory to shop-imgcache
  5. Rename ae-format directory to shop-format
  6. Rename ae-template directory to shop-template
  7. Similarly, rename the following directories if they exist:
    1. ae-asin to shop-asin
    2. ae-upc to shop-upc
    3. ae-include to shop-include
    4. ae-exclude to shop-exclude
  8. Edit ae-ini.txt and change the script configuration variable from "ae" to "shop" (do not include a filename ending).
  9. If you are using Virtual Directory, then edit your .htaccess file and replace ae.pl with shop.pl There should be two occurrences of this.


Installing in a Subdirectory

Associate Engine requires various files and directories. The standard installation instructions above instruct how to install everything into your /cgi-bin directory.

If you prefer, you can group all the Associate Engine files and directories into its own subdirectory such as /cgi-bin/ae/ (you can pick a different directory name other than ae if you prefer).

The steps to follow vary slightly depending upon whether you want to put the ae.pl file in your cgi-bin directory or with all the other Associate Engine files.


ae.pl in /cgi-bin/ae/

  1. The URL to access ae.pl would be: /cgi-bin/ae/ae.pl
  2. Create a subdirectory called ae (or whatever subdirectory name you prefer) inside your cgi-bin directory.
  3. Then follow the installation instructions above and wherever it refers to cgi-bin, use cgi-bin/ae instead.
  4. No changes are required to the ae-ini.txt configuration file.

ae.pl in /cgi-bin/ and data files in /cgi-bin/ae/

  1. The URL to access ae.pl would be: /cgi-bin/ae.pl
  2. Create a subdirectory called ae (or whatever subdirectory name you prefer) inside your cgi-bin directory.
  3. Then follow the installation instructions above and wherever it refers to cgi-bin, use cgi-bin/ae instead.
  4. Put ae-ini.txt in the same directory where ae.pl is located, i.e.: /cgi-bin
  5. Edit the ae-ini.txt configuration file and change all the *.dir configuration variables so that they start with "ae/", such as: cache.dir "ae/{SCRIPT}-cache"



< Previous Table of Contents Next >




E.&O.E.; © Cusimano.Com Corporation; www.c3scripts.com