Associate Engine : Programming FAQ  
Home > Associate Engine > Documentation > Programming FAQ

Programming FAQ



Does Associate Engine support amazon.de or any other of the international amazon websites?

For amazon.co.uk, search results are based on amazon.co.uk. For a live example, see www.GrandShop.co.uk For full details, see Using Associate Engine with amazon.co.uk

For Amazon's other international websites (amazon.ca, amazon.de, amazon.fr, amazon.co.jp), Associate Engine provides partial support. See amazonID.* configuration variables. Note: Search results are based on the U.S.-based www.amazon.com website -- results are not based on the international websites. See example showing "Buy from: Canada, United Kingdom" links -- the main product links go to www.amazon.com.


How do I determine the browse number to use in type=browse&mode=NUMBER ?

To determine the browse number NUMBER, go to the amazon.com webpage that you want to display. Look in the address of that webpage -- it should look something like "http://www.amazon.com/exec/obidos/tg/browse/-/NUMBER/" (you can ignore any text or numbers at the end). Use the number NUMBER that appears in the webpage address.


Show me an example. How do I show calendars (they are part of books)?
For example, if you go to the Books home page at amazon.com and then click on "Calendars" in their left index, the address is http://www.amazon.com/exec/obidos/tg/browse/-/67240/ so you would use "type=browse&mode=67240" in your Associate Engine URL, such as: http://www.c3scripts.com/cgi-bin/ae.pl?type=browse&mode=67240


How do I show bestselling calendars rather than the index of all types of calendars?
If you want to show the bestsellers of a particular browse number, then use type=best&mode=NUMBER instead. For example, bestselling calendars (browse number 67240), would be at: "type=best&mode=67240", such as http://www.c3scripts.com/cgi-bin/ae.pl?type=best&mode=67240


How do I show very specific calendars such as dog calendars?
If you want to show dog calendars, then you would clickthough the following links at amazon.com to get to the appropriate webpage at amazon.com: amazon.com home page > Books > Calendars > Animals > Dogs. Finally, you would end up at the dog calendars webpage at http://www.amazon.com/exec/obidos/tg/browse/-/67250/ so you would use "type=browse&mode=67250" in your Associate Engine URL, such as: http://www.c3scripts.com/cgi-bin/ae.pl?type=browse&mode=67250


What if I don't know what part of amazon.com to look in?
If you're not sure where at amazon.com to look, then try doing a keyword search at amazon.com. For example, suppose you want to show "people skills" books. Search for "people skills" in the books section of amazon.com. Then click on one of books in the results. On that products details page, scroll down to the "Look for similar books by subject:" section near the bottom of the webpage. For example, on the page for the book entitled "People Skills" (by Robert Bolton), there is:

If one of the links looks like what you want then click on it, such as "Interpersonal Relations", to go to that browse webpage. Then use its browse number found in the URL http://www.amazon.com/exec/obidos/tg/browse/-/NUMBER/


What if amazon.com has no browse webpage for what I want?
If amazon.com does not have a browse webpage for the particular topic you want to show, then the alternative is to use an Associate Engine keyword search or an Associate Engine advanced search (e.g.: search by author name, actor name, etc.).


Can I use Associate Engine on my PHP webpages?

Yes, you can use Associate Engine on your PHP webpages. Including Associate Engine results depends upon whether you're using PHP on a linux server or on a Windows server.


linux Apache web server:

If you are using a linux server with Apache web server software, use the PHP virtual() function, such as:

virtual("/cgi-bin/ae.pl?ssi&PARAMETERS");

The parameter of the virtual() function is the partial URL that you want to include; the URL must be partial, that is, it must start with a / instead of your domain name.

The ssi in the URL is necessary and causes Associate Engine to format the results so that they can be included in the PHP output stream. Replace the path (/cgi-bin/ae.pl) in the URL and replace PARAMETERS as required.

See Quick Tutorial.


Windows web server:

If you are using a Windows web server, use the PHP file_get_contents() function, such as:

print file_get_contents("http://www.mydomain.com/cgi-bin/ae.pl?ssi&PARAMETERS");

The parameter of the file_get_contents() function is the full URL that you want to include; the URL must be full, that is, it must start with your domain name.

The ssi in the URL is necessary and causes Associate Engine to format the results so that they can be included in the PHP output stream. Replace the path (/cgi-bin/ae.pl) in the URL and replace PARAMETERS as required.

See Quick Tutorial.


PHP in .html files:

(Note: The following section does not apply to your Associate Engine .html template file. If you want to put PHP in your template file, see the next section).

If you want your server to process PHP statements in files that have .html and/or .htm as the filename endnig, then add the following statement to your .htaccess file (or have your hosting company modify the web server's configuration):

AddType application/x-httpd-php htm html

Note that this statement will cause your web server to examine all requested .html and .htm files for PHP statements. That causes your server to do additional work per request. If you have PHP in just one file but still want it to appear as a ".html" file, then use a RewriteRule in your .htaccess file instead, such as the following statements that cause /top10.html to be internally redirected to /top10.php (the web browser's Address bar would still say /top10.html):

RewriteEngine on
RewriteBase /
RewriteRule ^top10\.html$ top10.php [L]


PHP in Associate Engine template file:

You cannot directly put PHP inside a template. It is ae.pl that is running, so the server uses the Perl language interpretter rather than the PHP language interpretter. Whatever comes out of any .pl program is sent directly to the user, it is not subsequently examined by the server for other programming language tags.

But you can use an SSI tag in the Associate Engine template to include output from any URL including from a .php file on your server. For example, suppose you add the following line somewhere in your Associate Engine template:

<!--#include virtual="/myheader.php"-->

When ae.pl processes this SSI tag, ae.pl will fetch from YOURDOMAIN.com/myheader.php and insert whatever that URL returns into the output sent to the user.

So, you can include the output of a .php file in your Associate Engine output, but you cannot include actual PHP statements.


Can I use Associate Engine using SSI (server-side-include) statements?

Yes, you can use Associate Engine using SSI statements. Use something like the following:

<!--#include virtual="/cgi-bin/ae.pl?ssi&PARAMETERS"-->

The ssi parameter is necessary and causes Associate Engine to format the results so that they can be included in the output stream.

Replace the path and PARAMETERS as required. See Quick Tutorial.


How do I configure my webserver so that HTML files in my /cgi-bin/ directory cannot be viewed?

Normally, files in the /cgi-bin/ directory should not be viewable (they should only be runnable). Done one or all of the following steps:

  1. Have your hosting company check the server's configuration file (typically at /etc/httpd/conf/httpd.conf). Your web server's configuration file is probably missing a ScriptAlias directive. See http://httpd.apache.org/docs/mod/mod_alias.html#scriptalias and http://httpd.apache.org/docs/howto/cgi.html

  2. Otherwise, create a file called .htaccess containing the following lines and put it in the same directory where ae.pl is located, such as cgi-bin/.htaccess

    IMPORTANT: If a file called .htaccess already exists, then add the following lines to it rather than replacing the existing .htaccess file.

    <Files ~ "\.(htm|html|shtml|tmp)$">
    Deny from all
    </Files>

    When a user tries to access an HTML file in your cgi-bin directory, such as http://www.domain.com/cgi-bin/ae.html, the user will see an error message telling them that permission is denied, such as: "Forbidden - You don't have permission to access to this document on this server".

  3. Otherwise, create a file called index.html in cgi-bin directory, such as http://www.domain.com/cgi-bin/index.html. The file can be completely empty (zero bytes) or contain HTML such as a "Click here" link to your home page. With the presence of an index.html file, the server will display that file when /cgi-bin/ is accessed rather than generating a directory listing.

How do I get prices to show up in results?

Make sure that your ae-ini.txt file contains "showprice yes". This configuration setting will enable prices when items are shown as a list (example).

Also, if you're showing results using the grid parameter then be sure to add ",p" to the end of the grid parameter (example) -- this will enable prices in grids. Note that the "showprice" configuration parameter (in ae-ini.txt) acts like a "global off switch" rather than an "on switch" -- thus you can quickly turn off all prices in your entire site by merely setting "showprice no".


How do I use Associate Engine with a <script> tag?

The <script> tag is a powerful yet easy to use standard HTML tag that when used with the Associate Engine script allows you to show results anywhere in your webpage such as inside a table. For example, see www.buy-here-and-save.com which contains a series of simple <script> tags.

The <script> tag is basically an HTML tag like other HTML tags that you typically see such as <font face="Arial">hello there</font> --- the <script> tag follows a similar format:

<script src="SOME_URL"></script>

The <script> tag basically tells the user's web browser to run Javascript code. The "src" tells the browser where to get the Javascript. Therefore, for example, when the following HTML tag:

<script src="/cgi-bin/ae.pl?script&type=bestseller&mode=books&grid=c:3,r:1,h:336633:FFFFFF,m,u:0"> </script>

is included on a webpage and is read by the user's browser, it causes the browser to run Javascript code fetched from the specified source. Also, Associate Engine recongizes parameters included in the src URL portion of the <script> tag. These paramaters tell Associate Engine what results you want (e.g.: set by the type= and mode= parameters) and optionally how to format the results (set by the grid= paramater). The specified source, Associate Engine, when run, generates a simple Javascript command that displays the results within the user's browser. The above <script> tag causes best seller books to be shown in a 3-column by 1-row grid with a colored heading. (see Script Parameters for details about the various paramaters)

The above <script> tag shows the following result:

The basic idea is that by using the <script> tag with Associate Engine you can place results anywhere on your webpage.

To see how this works in a live example, at the homepage of www.buy-here-and-save.com you will see on the right hand side 6 product sections each showing amazon best sellers. Each section was generated using a single <script> tag as shown in the above example. By changing Associate Engine's "mode=" paramater in each of the 6 <script> tags (i.e.: books, electronics, toys, music, etc), the corresponding results are shown. Since search engines don't understand <script> tags, none of the products shown will be indexed.

In contrast, the "categories" box that is shown on the left side of the screen at the homepage of www.buy-here-and-save.com contains ordinary HTML links. Those links link to Associate Engine such as: /cgi-bin/ae.pl?type=browse&mode=books for books (note: the type= and mode= paramters). Search engines will see this link and thus follow it and index whatever HTML is at that link (i.e. amazon results).

Depending on what you want to display on your site Associate Engine provides a lot of flexibility by letting you use <script> tags, links, or a combination of both.




When should I use a <script> tag?

If you have an existing content webpage and you want to include products on that webpage, then use a <script> tag. (Advanced users: You can also use an SSI statement.)

For example, suppose your webpage looks like the following and you want to display Harry Potter books by using Associate Engine:

Harry Potter books
[Harry Potter books
to be inserted here]

My Harry Potter Webpage

Hi! Thanks for visiting my website all about Harry Potter. I've read all the books and found them very interesting.

The books shown at the left are the most popular Harry Potter books. Click on them to see details.

I've also seen the Harry Potter movies and like them.

Thanks for visiting! Harry.

By inserting the following <script> tag into the webpage, Associate Engine will display results at that location in the webpage as shown below.

<script src="/cgi-bin/ae.pl?script&type=search&mode=books&keyword=harry+potter&grid=c:1,r:3,at,p">

Harry Potter books

My Harry Potter Webpage

Hi! Thanks for visiting my website all about Harry Potter. I've read all the books and found them very interesting.

The books shown at the left are the most popular Harry Potter books. Click on them to see details.

I've also seen the Harry Potter movies and like them.

Thanks for visiting! Harry.




I'm using a <script> tag. How do I make the "More" link show more results on the same page?

Either use an <IFRAME> tag rather than a <SCRIPT> tag, or create a custom template that looks like your website.

Another method is to turn off the "More Results" links and create a series of .html files and link them together. In ae-ini.txt, set prevNext to "no". On the 2nd page, add &page=2 to the <SCRIPT> URL. On the 3rd page, use &page=3 to get the 3rd page of results, and do that for as many pages as you want. For example, you might have dvd.html (<SCRIPT> without any page= parameter), dvd2.html (<SCRIPT> with &page=2), dvd3.html (<SCRIPT> with &page=3), etc.



How do I modify the links so they go to something like myclicktracker.pl?ASIN ?

Modify the <!--format.url--> formatting code in the Formatting Library. There is an example of this modification in: Formatting Library.




Can I index Associate Engine webpages using a website indexer such as SiteXpert?

No. You should not index any Associate Engine URL (either /cgi-bin/ae.pl?... or Virtual Directory) since your indexer would try to traverse literally millions of unique Associate Engine URL's. Configure your indexer to skip Associate Engine URL's.

For a search form, you should use a keyword search or an advanced search. The default templates (ae-template/default.html and ae-template/store/default.html) come with a keyword search form at the top of the left sidebar.




How do I make the Associate Engine Store Directory appear as my home page?

To make the Stores Directory (live example) appear as your home page, create a .htaccess file (in the directory where your homepage file would be) and use RewriteRule to make your webserver redirect to Associate Engine when your home page URL is requested. Such as:

RewriteEngine on
RewriteBase /
RewriteRule ^$ /cgi-bin/ae.pl?template=stores

FYI, the ^$ is a regular-expression pattern match string that matches "nothing" after / (see Apache webserver documentation for details).

Note: Each time your home page is requested, Associate Engine will run. This is slightly inefficient since the page output will look the same most of the time (as set by your cache stale time). If you have a lot of users visiting your home page, rather than using the above RewriteRule, you might want to look into setting up a linux cron job that periodically (e.g.: every 1 hour) captures the output from /cgi-bin/ae.pl?template=stores and saves it to the /index.html file. That way, when users go to your homepage, the webserver outputs the static /index.html file rather than running the Associate Engine script. See next FAQ for details.

See also: Virtual Directory > Home Page.




How do I set up a linux cron job to create a static HTML home page file?

If you have one or more SSI statements on your home page that call Associate Engine, your server has to process all those SSI statements every time a user visits your home page. If you home page is very popular, this could cause your server's CPU to experience a very load (i.e.: the CPU is very busy and the server slows down). Since product details do not change sooner than 1 hour (see cache.stale configuration variable), you should use an hourly cron job to capture the HTML of your home page that contains SSI statements and save the output to a static HTML file. Then, use that static HTML file as the home page file that users see. To save even more CPU, you could run the cron job every 24 hours rather than every 1 hour.

Linux reference: What is a Cron Job, and how do I use it?

VERY IMPORTANT: In all of the following, adjust filenames and paths and URL's so they match your system.

If you do not understand what any of the following menas, then contact your hosting company (or your website program) and have them set this all up for you (it involves creating a batch file and creating a cronjob to run that batch file).

At www.collectiblecats.com we have an /index.shtml file that contains SSI statements that call ae.pl to show some amazon.com products. We then have a linux cron job that "runs" /index.shtml and saves the output to /index.html which is the home page that people see. The cron job entry that we use is:

15 4 * * * /home/virtual/site9/fst/var/www/cgi-bin/shtml

This cron job entry means "at 4:15 a.m. of every day, run /home/virtual/site9/fst/var/www/cgi-bin/shtml". On our server, collectiblecats.com is site9 running under the Ensim server manager.

And the file /home/virtual/site9/fst/var/www/cgi-bin/shtml has execute permissions enabled (chmod 755) and contains:

#!/bin/sh
/usr/bin/lynx -source http://www.collectiblecats.com/index.shtml > /home/virtual/site9/fst/var/www/html/index.html

The /usr/bin/lynx command is part of linux and is a linux text-based web browser. The lynx "-source" parameter tells lynx to output the HTML source of the specified URL rather than be a web browser. The ">" is standard linux file output redirection and the output is saved to the specified file /home/virtual/site9/fst/var/www/html/index.html which is the /index.html file of our collectiblecats.com website.

So, at 4:15 a.m. of every day, /home/virtual/site9/fst/var/www/cgi-bin/shtml runs which causes /usr/bin/lynx to run and fetch the URL http://www.collectiblecats.com/index.shtml (the web server handles this request just like it would from a real user and returns HTML) and the output is saved to /home/virtual/site9/fst/var/www/html/index.html

If your server does not have /usr/bin/lynx, then try using /usr/bin/GET instead as follows (note: the command is /usr/bin/GET and it is not /usr/bin/get):

#!/bin/sh
/usr/bin/GET http://www.collectiblecats.com/index.shtml > /home/virtual/site9/fst/var/www/html/index.html




I have my templates in a directory other than /cgi-bin/ae-templates. How do I specify a different directory?

The template.dir configuration variable in the ae-ini.txt configuration file specifies the directory where templates are located. Change the value of template.dir so it is the directory where your templates are located. The value can be either relative (to where ae.pl is located) or absolute.

Examples of relative template.dir value:

ae-template
../mytemplates
../../templates

Examples of absolute template.dir value:

/var/www/html/cgi-bin/ae-template
/var/www/html/mytemplates
/var/www/mytemplates




How do I make the size of the shopping cart pop-up window smaller?

Put something like the following HTML into your template file ae-template/default.html

<A HREF="{viewcart}" ONCLICK="window.open('{viewcart}', 'cart', 'width=XXX, height=YYY, resizable=yes, scrollbars=yes'); return false" >View shopping cart</A>

Replace XXX and YYY with the width and height that you want the window to be, such as 500 and 400, respectively. And in your ae-ini.txt configuration file, set the viewcart configuration variable to no so that the standard "View shopping cart" link is not shown.

Note: The shopping cart is maintained at the amazon.com website. Thus it is not possible to change the contents of the shopping cart window. But you can change the size of the shopping cart window as indicated above.




How do I add a link to the shopping cart on my home page?

The shopping cart is at the amazon.com website. The URL to the shopping cart is:

http://www.amazon.com/exec/obidos/redirect?path=shopping-basket&tag=ASSOCIATEID

Replace ASSOCIATEID with your amazon.com associate ID.

You can then use this URL in a link, such as:

<A HREF="http://www.amazon.com/exec/obidos/redirect?path=shopping-basket&tag=ASSOCIATEID"
TARGET=_"blank">View shopping cart</A>

Remove the TARGET="_blank" if you don't want a new window to appear.

If you want the new window to be a specific size, then you have to use something like the following instead:

<A HREF="http://www.amazon.com/exec/obidos/redirect?path=shopping-basket&tag=ASSOCIATEID" ONCLICK="window.open( 'http://www.amazon.com/exec/obidos/redirect?path=shopping-basket&tag=ASSOCIATEID', 'cart', 'width=XXX, height=YYY, resizable=yes, scrollbars=yes'); return false" >View shopping cart</A>

Replace XXX and YYY with the width and height that you want the window to be, such as 500 and 400, respectively.

Note: The shopping cart is maintained at the amazon.com website. Thus it is not possible to change the contents of the shopping cart window. But you can change the size of the shopping cart window as indicated above.




I tried to change the associate ID in my ae-key.txt file but it didn't work. Why?

To prevent unauthorized use of our scripts, only we can create key files. Attempting to change the ID value of an existing key will not result in a valid key. To obtain additional keys for a script, use the Key Request form for that script. See: Associate Engine Key Request form.




How do I add keyword/description <META> tags based on the content of the site?

Edit your Associate Engine template file (e.g.: ae-template/default.html) and somewhere in between <HEAD> and </HEAD>, add the following <META> tag:

<META NAME="keywords" CONTENT="{title*}">

You could also add:

<META NAME="description" CONTENT="{title*}">

Note: Those are curly braces { and }. They are not parentheses ( and ).




Is there a list of all the {details.*} formatting tags?

See: Substitution Variables: {VARIABLENAME}




How do I display amazon.com product details locally for users and redirect search engines to amazon.com?

You may want to do this because you are finding that search engines are using up a lot of your server's bandwidth to fetch product details pages. Theoretically, a search engine could try and fetch details on every amazon.com product via Associate Engine at your website -- that's a lot of data!

First, to have Associate Engine display product details locally, you must set the asinsearch.format configuration variable, such: asinsearch.format "details6"

There is no Associate Engine configuration variable to cause Associate Engine to redirect search engines to the product details page at amazon.com. But this redirection can be done by adding something like the following lines to your .htaccess file located in your / directory (create such a file if it does not exist).


If you are not using Virtual Directory: add these 4 lines to your .htaccess file:

RewriteBase /
RewriteCond %{HTTP_USER_AGENT}  bot
RewriteCond %{QUERY_STRING}  asinsearch=([a-zA-Z0-9]+)[^,]*$
RewriteRule ^cgi-bin/ae\.pl$  http://www.amazon.com/exec/obidos/ASIN/%1/ref=nosim/AMAZONID?dev-t=D2Y5TUCCVJ7DGE [L,R=301]


If you are using Virtual Directory: add these 3 lines to your .htaccess file before the RewriteRule lines used for Virtual Directory:

RewriteBase /
RewriteCond %{HTTP_USER_AGENT}  bot
RewriteRule ^amazon/asinsearch_([a-zA-Z0-9]+).*$  http://www.amazon.com/exec/obidos/ASIN/$1/ref=nosim/AMAZONID?dev-t=D2Y5TUCCVJ7DGE [L,R=301]

(RewriteRule lines used for Virtual Directory go here after the above lines.)



VERY IMPORTANT: You must edit the above lines in the following way:

  1. To prevent typing errors, copy and paste the above lines to your .htaccess file rather than typing them in by hand.

  2. The RewriteRule is one long line that starts at RewriteRule and ends at "[L]". In the above instructions, it may appear to be one two lines; copy it to your .htaccess file as one line line without any returns.

  3. You must replace AMAZONID with your own Amazon.com associate ID otherwise sales will not be tracked.

  4. If Associate Engine is in a directory other than cgi-bin, such as cgi-local, then replace cgi-bin with the directory name where Associate Engine is located.

  5. If Associate Engine has been renamed from ae.pl to some other filename, such as shop.pl, then replace ae\.pl with the new name. Note: Use \. instead of just ., such as shop\.pl

  6. If the virtual directory is something other than amazon, then replace amazon with the virtual directory name you are using.


Spider Names

The above rules will work only if the search engine's spider robot contains "bot" somewhere in its user agent name. For example, MSN identifies itself as "msnbot/0.11 (+http://search.msn.com/msnbot.htm)".

Most search engine spider robots contain "bot" somewhere in their user agent name. If a user's web browser has a user agent with "bot" somewhere in it, the user will be redirected to the details page at the amazon.com website (with your amazon.com associate ID in the redirection) rather than seeing the product details page locally at your website.

If you want to redirect only a specific spider, such as msnbot, then change bot to msnbot

You can also check for multiple search patterns by separating then with the vertical bar | character and surrounding the entire expression in parenthesis ( ) such as (msnbot|Googlebot|Yahoo)




How do I display only books and no other product types?

The category links in the sidbar are part of the template. You can edit the template and delete those links that you do not want to appear.

Sometimes the "Similar products" section (of details pages) shows links to products that are in different catgories; for example, a book that is also a movie might include a link to that movie on DVD or to its soundtrack CD. So those links would permit users and search engine spiders to enter non-book categories. You can tell ae.pl to make all categories (except books) go to amazon.com by editing ae-ini.txt and adding browse.remote.CATEGORY statements. For example, this will make DVD's go to amazon.com instead of on your website:

browse.remote.dvd   yes

You have to add a browse.remote.CATEGORY statement for each of the catgories that you do not want on your website. See: List of all the CATEGORY values.

Here is all the browse.remote.CATEGORY statements that are possible:

browse.remote.classical   yes
browse.remote.dvd   yes
browse.remote.electronics   yes
browse.remote.garden   yes
browse.remote.kitchen   yes
browse.remote.magazines   yes
browse.remote.music   yes
browse.remote.office-products   yes
browse.remote.pc-hardware   yes
browse.remote.photo   yes
browse.remote.software   yes
browse.remote.toys   yes
browse.remote.universal   yes
browse.remote.vhs   yes
browse.remote.videogames   yes
browse.remote.wireless-phones   yes

Add one or more of these statements to your ae-ini.txt configuration file to make those categories go to amazon.com rather than saying on your website. You can put the statements anywhere in the ae-ini.txt file. Use Windows Notepad editor (or some other plain text editor) to edit the ae-ini.txt file. You can run Windows Notepad (Start > Run... > Open: notepad) and drag the ae-ini.txt icon into that Notepad window.

Note: See also default.search configuration variable if you want to set the default search. For example, to make the DVD browse index (type=browse&mode=dvd) the default search, set the following in ae-ini.txt:

search.default "type=browse&mode=dvd"

Note: To make a particular browse node remote (e.g.: Comedy DVD's, browse node 163357), rather than making an entire category remote (e.g.: all DVD's), use browse.remote.NUMBER to make browse node NUMBER remote (e.g.: browse.remote.163357). To hide a browse node from being displayed on an index page, you can also use a browse.delete.NUMBER statement (browse.delete.163357).


More FAQ's for Associate Engine:



Do you have any other webmaster tools that I can use?

Yes. Click here.



How do I contact you for support?




< Previous Table of Contents Next >




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