NAME Business::Associates - a library to handle the new XML interface for the Amazon.com Associates program. SUMMARY This package replaces the Amazon Recommends (tm) links to provide a powerful and simple to use interface that allows you to embed complex, highly targeted ads on your web site (or other documents). This modules supports many new features that are not available with the standard interfaces. For example, multi-mode searches, i.e. the ability to search across multiple product categories (dvd+video+music+...) is fully supported. See also http://cybaea.com/Associates.html for more information and example screen shots. Currently, only the Amazon.com Associates program is supported. OVERVIEW OF DOCUMENTATION The good news is that if you are new to this library, then you are reading the right document. Carry on! This document tells you everything you need to know to get started with the package. It takes you through including complex ads on your web site so you can start making money now. The Associates package uses a three-stage working model: 1. Retrieve data from the Associates program's XML interface. In the case of Amazon's program, that involves a HTTP request to the `rcm.amazon.com' server. 2. Transform the data into the desired output format. This is done using a technology known as XSLT and, in the examples included in this distribution, it converts the XML from the server into HTML that we can display as part of our web site. 3. Format the data visually. For the HTML output that we generate here, we use Cascading Style Sheets (CSS) which is the standard way to specify the formatting of a web site. This document, the Business::Associates manpage, provides an installation and quick-start guide, as well as an overview of the entire package. Read this first. The three stages are documented in three different overview documents: 1. Data retrieval is documented in the Business::Associates manpage (this document). 2. Data transformation is documented in detail in the Business::Associates::Stylesheet manpage. 3. Visual formatting is documented in detail in the Business::Associates::Formatting manpage. Additionally, for detailed programmer's references, see the Business::Associates::Data manpage, the Business::Associates::XML manpage, the Business::Associates::Cache manpage, the Business::Associates::Communication manpage, and the Business::Associates::Imgsize manpage. The order suggested here will minimize forward references, but I strongly suggest that you read the three documents above first. INSTALLATION If you are reading this, then chances are that you have already installed the package. But here are the instructions again: Download the latest version of the package from http://cybaea.com/Associates.html. It will be in the form of a compressed archive with the name Business-Associates-x.yy.tar.gz where *x.yy* is the version number (e.g. 1.00). Unpack this archive and go to the newly created directory. On a Unix-like system, you would do $ gunzip -c Business-Associates-x.yy.tar.gz | tar xvf - $ cd Business-Associates-x.yy Then build and install the package in the usual perl way. Note that to install you probably have to be `root'. $ perl Makefile.PL $ make $ make test % make install For more information on this process, including how to install without being the superuser, see the ExtUtils::MakeMaker manpage. Copy demo files This is an optional step, but you will probably want to copy the files from the demo/ sub-directory: demo/Associates.css and demo/associates.shtml normally go to the document root of your web server, while demo/a.pl goes to your `cgi-bin' directory. For my server (Red Hat Linux), I do: $ cp demo/Associates.css demo/associates.shtml /var/www/html/ $ cp demo/a.pl /var/www/cgi-bin/ Your directories may vary. You should edit the a.pl file to include your Amazon.com Associates Id (instead of the default, which is mine). Find the line $Business::Associates::Data::Associates_Id = "allanengelhardt"; and change `allanengelhardt' to your id. You'll probably want to incorporate (some form of) the cascading style sheet in your main style sheet. You can do this easily by adding @import url("/Associates.css"); near the top of your style sheet (before any instructions). If your web server is already configured for server-side includes, and it is running, then you should now be able to do $ mozilla http://localhost/associates.shtml to see the results (requires an active internet connection). Substitute your web browser for `mozilla' above. Images The default scripts and style sheets provided with this package references a number of images from Amazon that are not provided in this download. You'll need an Amazon.com Associates account to download them from https://ssl-images.amazon.com/images/G/01/associates/logos2000/a150X75w.gif https://ssl-images.amazon.com/images/G/01/associates/logos2000/126X32-w-logo.gif https://ssl-images.amazon.com/images/G/01/associates/photo2000/cp_pic_88x31.gif The samples expect to find them in the amazon sub-directory from the web server's document root (typically something like /var/www/html/amazon/. See README.XSLT-STYLESHEETS for more information. Server Side Includes If your Apache server is not already configured for server-side includes, then enable it in httpd.conf by finding and un-commenting the lines # # To use server-parsed HTML files # AddType text/html .shtml AddHandler server-parsed .shtml See your Apache manual for details. For other web servers, please consult the manual. No Server Side Includes !? If your server is not configured for server-side includes, then you should still be able to test the package with a command like $ mozilla http://localhost/cgi-bin/a.pl?keywords=make+money+now though your browser may display the HTML source rather than rendering it. (Try saving as an .html file and then loading that, if this is the case.) QUICK START Please read the the section on "INSTALLATION" first. I assume that you already have an Amazon Associates account. The Amazon Associates program provides for individual web sites to sell books and other items to their visitors through Amazon.com while earning a small commission, at the time of writing usually 5%. For more information please see http://associates.amazon.com/. The sections below cover HTML, CGI, and mod_perl interfaces to this package. Quick Start: HTML All that is needed to start using this package is *a single line* in your HTML page. If you are using Apache with server-side includes then that line could be as simple as: This makes a simple banner three items wide with a logo (Amazon's or your own - it's your choice) to the left of the items. It does a keyword search for books (the default) on the string "xml" and displays the top three Amazon best sellers. Quick Start: CGI Below, we present a complete CGI program that uses this package. Apart from declarations, it is *only four lines long*. #!/usr/local/bin/perl -Tw use Business::Associates::Data(); use Business::Associates::XML(); $Business::Associates::Data::Associates_Id = "'allanengelhardt'"; my %args = ( associates_id => $Business::Associates::Data::Associates_Id, disable_img_size => "true()" ); my $what = "xml"; # Search string my $mode = "books"; # Product category my $ss_name = "Associates"; my $type = "keywords"; # Or: browse my $data = Business::Associates::Data->$type ($what, $mode); my $xml = new Business::Associates::XML ($data) if defined $data->xml(); my $s = $xml->transform($ss_name, %args) if defined $xml; print "\n\n$s\n" if defined $s; You should change the value of *Associates_Id* from `allanengelhardt' to your own Amazon.com Associates Id. Note the extra quotes in that string. For the moment, treat *%args* as a magic argument. The *$what* variable is the search string for keyword searches, and you should separate keywords with the `+' character (e.g. `$what = "make+money+fast"'. If *$type* is `"browse"', then *$what* is the browse category (e.g. `"301668"' for popular music). Normally, you'd get these arguments from the CGI parameters, see demo/a.pl for an example of this, and see also the CGI manpage. See also demo/a.pl for an example that supports searches across multiple product categories. See the section on "CGI SCRIPT" for more details on options to the a.pl script. Quick Start: mod_perl The module is easy to use from any perl program and provides maximum performance from mod_perl (see next section). See the previous section for an example, and the individual package documentations for the complete API. BACKGROUND The Amazon Associates program provides for individual web sites to sell books and other items to their visitors through Amazon.com while earning a small commission, at the time of writing usually 5%. For more information please see http://associates.amazon.com/. The Associates web site provides many tools for building links to products on Amazon.com, but in early 2002 a completely new interface was developed to allow web sites full control to build their links as they wanted. This new interface returns structured data about best selling items at Amazon. It is currently possible to retrieve this data for any of Amazon's product lines, including books, magazines, DVDs, etc. The data can be specified by keyword search (e.g. "garden+furniture") or by browse category, which is a classification of Amazon's items (e.g. `All Products / Camera & Photo / Brands / Canon / Film Cameras / SLR Cameras') that provide fine-grained control over the items returned. This structured data is provided as XML, which is a popular way to encode both data and the information about data. For more information on XML you can look at http://www.xml.org/ and http://www.xml.com/ for tutorials, tips, and further links. XML is an official standard of the World Wide Web consortium who you can find at http://www.w3.org/. Even though there are many and excellent tools for manipulating XML it can be a bit daunting. This package brings together all the tools for building efficient ads on your web site. Some of the benefits and design goals of this package are outlined in the subsections below. Performace On my middle-of-the-road Pentium machine running Linux, the conversion of the raw Amazon XML to the formatted HTML banner (about 3k of HTML) takes about 7 milliseconds. Conversion of the same XML to another HTML format (e.g. to sort by author or price instead of the default sales rank) takes only about 5 milliseconds. The parsed style sheets are cached in memory, saving 2 milliseconds on all but the very first call. To get anywhere near this performance you need to use mod_perl or some similar technique that avoids the overhead of creating a new process. The included CGI script run in just under 300 ms on my machine when retrieving the data from disk. A very large part of this is the overhead of starting a new process and loading perl: the core processing is less than 30 ms. Efficiency For efficiency and to reduce network load, this package automatically caches the results from Amazon for 24 hours. Next time your web server needs the results for a given keyword combination of browse category it is retrieved from your disk, not from the network. This greatly improves the performance of your system. Amazon only updates the bestseller list every 24 hours, so you are not loosing information by this. The caching is also a condition for using the Amazon XML interface. Separation of Code, Data, and Presentation The design of this package separates code, data, and presentation to simplify maintenance of complex web sites. The code is written in pure perl, and should run on practically any machine regardless of architecture. It is responsible for the result caching and network communication, and for orchestrating the whole effort. Data transformation is done using XSLT which is a standard for transforming XML. This is a very powerful transformation language with excellent support of development tools. This package includes a powerful default transformation as well ans several well-documented examples on how to extend or modify this. The presentation is managed using standard cascading style sheets. All HTML (or xhtml) elements are clearly and uniquely identified , allowing precise control over the look of the finished result. It is possible to have different visual formatting for different result categories (e.g. Books can look different from Electronics). Portable The package is developed in perl, and should work on any platform with a functioning perl installation. The package uses libxml2 and libxslt, two excellent libraries from the Gnome project (http://www.gnome.org). These are pure C libraries and should provide maximum portability (and performance, see the Performance entry elsewhere in this document). DESCRIPTION This package offers the ability to create ads and other information in conjunction with an Associates program. An *Associates program* is a service provided by an online retailer whereby affiliates are rewarded for referrals to the retailer. Typically, the reward is a percentage of the sales price. The best known of these programs, and the only one currently supported by this package, is the Amazon.com Associates program. For more information, and to sign up, please visit http://associates.amazon.com/. This package works with an Associates program that provide an XML interface to their search engines. In the example of the Amazon.com interface, it is possible to obtain their bestseller lists for any category of product (books, DVDs, software...) for specific keywords (e.g. Jennifer+Lopez) or for a specific "browse category" (e.g. Canon brand 35mm SLR film cameras). XML is a standard way of encoding data and information about the data (e.g. "this is a title", "this is a price"...) that is very popular and has good tool support. However, XML is not usually intended to be viewed directly by the end-user, instead it is an intermediate format that should be converted, for example to HTML. The Associates package uses a three-stage processing model: 1. Data retrieval. The raw XML data is retrieved from the Associates program's XML server, using keywords or browse categories. For efficiency, the XML data is cached locally, reducing the network load of your web server. 2. Data transformation. The raw XML data is then transformed to the target data format, usually HTML which allows your web server to display banner ads and the like. 3. Visual formatting. The transformed data needs to be formatted visually. This includes setting font sizes, deciding on image displays, etc. These are separate stages to support separation of code and data, to allow maximum scalability of your web site, and to allow for other formats (e.g. different ads for WAP or iMode devices). CGI SCRIPT The provided CGI script, a.pl, is, with server-side includes, the easiest way to get started with this package. The script accepts a number of arguments. Many of them are shown in the associates.shtml file in the demo/ sub-directory, and in the following we briefly summarize the main options. *type* [Default: keywords] Must be one of "browse" or "keywords" for browse category or keyword searches, respectively. Defaults to "keywords". Examples: *keywords* [Required] *browse* [Required] This is a string that indicates the keywords (for keyword searches) or the browse category (for browse searches) for which the bestseller list should be retrieved. The two forms, *keywords* and *browse* are synonyms. This is the only required argument. Separate multiple arguments with a `+', and be sure to encode any arguments that are not valid in a URL with the `%xx' notation (see also the URI::Escape manpage or the Apache::Util manpage). Examples Keyword search for books on XML and XSLT. Browse category search. *mode* [Default: books+music+dvd] The so-called *mode* or product category to search. Separate categories with a `+' sign. Valid modes for the Amazon.com Associates program includes: `books magazines music classical-music vhs dvd toys baby videogames electronics software universal garden kitchen photo pc-hardware'. Note that multi-mode searches can take some time when the data is not cached. *width* [Default: '3'] The output of the default data transformation style sheets is a box of items. This parameter specifies the width of that box, in number of items. See also *height* below. *height* [Default: '1'] The output of the default data transformation style sheets is a box of items. This parameter specifies the height of that box, in number of items. See also *width* above. Example: The quotes are optional, but recommended (the parameters are technically XPath specifications). *ss* [Default: Associates.xslt] Specifies the style sheet that is responsible for the data transformation stage of the processing. For example, to sort items by artist (instead of the default sales rank), use *images* [Default: 'auto'] The Associates package has the ability to display images on any of the four sides of the advertisement. Use any combination of `'auto'', `'top'', `'left'', `'right'', and `'bottom'' separated by spaces, or `'none''. The value `'auto'' puts an image on the top if `width <= height' and on the left if `width > height'. Note the extra quotes (this is an XPath parameter). *img_src_(top|left|right|bottom)* This is the source (`SRC' attribute of the HTML `IMG' tag) of the images (see *images* above). The default is `'/amazon/a150X75w.gif''. Note the extra quotes. See example in the previous item. *class* [Default: 'A_catalog'] The default transformation style sheets produces a HTML `table' containing the ad. This specifies the `class' attribute of the `table' entity. See also the Associates::Formatting manpage. *coversize* [Default: 'T'] Specifies the size of the image used for the cover. Valid values include 'T', 'M', and 'L' for thumbnails, medium, and large images, respectively. Note the extra quotes. TO DO Upload to CPAN. More XSLT examples. More tests in the install scripts. SEE ALSO Data transformation is documented in detail in the Business::Associates::Stylesheet manpage. Visual formatting is documented in detail in the Business::Associates::Formatting manpage. Additionally, for detailed programmer's references, see the Business::Associates::Data manpage, the Business::Associates::XML manpage, the Business::Associates::Cache manpage, the Business::Associates::Communication manpage, and the Business::Associates::Imgsize manpage. The order suggested here will minimize forward references. See also the CPAN manpage, http://www.perl.com/CPAN, the httpd manpage, http://www.apache.org/, the XML::LibXML manpage, the XML::LibXSLT manpage, the libxml manpage, http://www.gnome.org/, the Cache::Cache manpage, the File::Spec manpage, the HTTP::Request manpage, the LWP::UserAgent manpage TRADEMARKS Amazon, Amazon.com, and other names used in this document may be the registered trademark of Amazon in the United States of America and other jurisdictions. Please see http://www.amazon.com/ for more information. Other names may be trademarks of their respective owners. AUTHOR This package was written by Allan Engelhardt COPYING Copyright (c) 2002 Allan Engelhardt This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA