This content plug-in for Joomla! embeds Amazon product information into a content article, with affiliate links that earn money for you when a user clicks the link and makes a purchase from Amazon. The plugin works for Joomla 1.5x to 3.

You can buy the plugin here.

You can view some examples here.

Requirements

The plugin uses the Amazon product advertising API. It requires an API key, which you can easily (and freely) obtain by opening an account at http://aws.amazon.com/. We describe this process here, it is worth reading through before you try

You will also require a valid Amazon Associates ID, which you obtain through creating an account here. You will require permission for each domain on which you wish to use your ID, you can obtain this through your Amazon Associates account. This is important, the Amazon product advertising API will not return results without this. It is also important from your point of view: this ID is used to credit your account when a user clicks your link and makes a purchase from Amazon.

How It Works

The plugin sends a signed request (known as a REST request) to the Amazon server. The request is signed using a public key and a secret key known only to yourself - you obtain both these when you sign up for your AWS account. An unsigned request will be ignored, a correctly signed one will return Amazon product information as an XML feed, which the plugin then parses to obtain the information.

There are two types of request that return product information:-

• an item lookup request will return results for up to 10 items identified by their ASIN number, which is a unique identifier that Amazon attaches to every product it sells. For books the ASIN is identical to the 10 digit ISBN number
• an item search request will use keywords to search the product database, which can be restricted to a particular search index, such as books, or be a search of the entire database. Up to 10 results will be returned per search.

The plugin can support either type of request.

Usage

There are two ways to use the plugin to embed Amazon products, using the Joomla article metatags to search the Amazon product database; or using a simple embedding code to place the results in an article or elsewhere. Many extensions such as K2 and Virtuemart will also support Joomla content plugins, so the use of embedding code means that you can add product information to a wide variety of content.

Using Article Metatags

The easiest way to use the plugin is to simply select the section, category or individual articles using the plugin manager. The plugin will be automatically rendered, and the output appended to the selected articles. The plugin will use the article metatag keywords to run a keyword search on the selected Amazon site. If you want to display a specific product you can supply the ASIN as a metatag, however you may find that using embedding code is more reliable.

You can use the plugin parameters to select the number of tags to use. The default is 2, and it is usually good to use one or two at most, the reason being that Amazon will only return search results that contain all keywords, if too many are used then it unlikely to return any results.

Using Embedding Code

You can also use embedding code to render the plugin for an individual article. This allows you to have greater control over the results returned, including allowing you to select an individual product by ASIN or ISBN (10 digit).

To embed the plugin, use the following format:

{amazonWS:itemId=xxxxxxxxxxxx;associatesid=xxxxxx;showPrices=yes;country=com}

with the parameters specified as a list separated by semi-colons (;). yes can be replaced by no to switch the options off, replace xxxxxxxx with the relevant values. See the section below for a summary of the available parameters.

Because you have specified the itemId the plugin will use this to perform an item lookup. Note that you do no normally need to specify all these parameters, you can set most options in the Joomla plugin manager, you only need to specify the parameters in the embedding code if you want to override the plugin manager options. The most common form for an item lookup request is simply:-

{amazonWS:itemId=xxxxxxxxxxxx}

or

{amazonWS:itemId=xxxxxxxxxxxx,yyyyyyyyyyyy,zzzzzzzzzz}

the list can include up to 10 values for the itemId, as a comma separated list. You can find the Amazon itemId by looking at the Amazon listing for your chosen item. It will be listed under product details. It will be the value of the ASIN number, except in the case of books, where it will be the ISBN-10 number.

Item Search

If you leave out the itemId parameter the plugin will send a search request instead. In this case you must at least include an author, title or keywords parameter, for example

{amazonWS:keywords=biscuits,cheese}

You can include as many keywords as you want, as a comma-separated list. However it is not a good idea to include more than 2 or 3 at most, the reason being that Amazon will only return results that match ALL keywords, so that the more you include, the fewer results will match.

Search Index

You can control the type of products returned by including a searchIndex parameter, for example

{amazonWS:keywords=biscuits,cheese;searchIndex=Grocery}

If you are doing a keyword search, the search index does not need to be specified, because the default value of 'All' will be used, although you can include it. However, if you are using an author or title search, you will need to specify Books or another category where this kind of search is supported (see the Amazon documentation for further details). For example

{amazonWS:author=Rowling;searchIndex=Books}

The available values for searchIndex are:-

All
Apparel
Automotive
Baby
Beauty
Blended
Books
Classical
DigitalMusic
DVD
Electronics
ForeignBooks
GourmetFood
Grocery
HealthPersonalCare
Hobbies
HomeGarden
Industrial
Jewelry
KindleStore
Kitchen
Magazines
Merchants
Miscellaneous
MP3Downloads
Music
MusicalInstruments
MusicTracks
OfficeProducts
OutdoorLiving
PCHardware
PetSupplies
Photo
SilverMerchant
Software
SoftwareVideoGames
SportingGoods
Tools
Toys
VHS
Video
VideoGames
Watches
Wireless
WirelessAccessories

Not all of these are available for all Amazon countries. If you get an error message saying that the search index is invalid, it means that the one you are using does not exist for the country database you are using.

Summary of Plugin Parameters

Summary of Plugin Shortcode Parameters

Name	Default Value	Possible Values	Description
itemId			10 character product ASIN or ISBN, or can be a comma-separated list of up to 10 ASINs, use for item lookup which fetches specific products
keywords			one or more keywords for item search, this will search all the product information for the keywords
searchIndex	All	listed above	used to limit the keyword search to specific product type
showPrices	yes	yes, no	show the Amazon list price
showSalePrices	yes	yes, no	show the Amazon sale price
showAmountSaved	yes	yes, no	show the amount save (off list price)
showNewOfferPrices	yes	yes, no	show the lowest new offer price
showUsedOfferPrices	yes	yes, no	show the lowest used offer price
showCollectiblePrices	yes	yes, no	show the collectible price
showRevs	yes	yes, no	show the Amazon customer reviews
showEditorial	yes	yes, no	show the editorial review (this is basically the product description, usually the same as on the Amazon product page)
country	com	com, de, co.uk, fr, co.jp, ca, cn, it, in, es, com.br, com.mx	the Amazon country database from which you want to display results - normally you will set this once in the plugin options rather than using short code, but you can override this using short code eg country=de
associateId			the tracking (affiliate id) to include in the product links - normally you will set this once in the plugin options, but you can override it in the short code eg associateId=myname-21
author			use instead of keywords parameter to make a search only of authors eg author=Rowling
brand			use instead of keywords parameter to make a search only of brand information eg brand=Apple
manufacturer			use instead of keywords parameter to make a search only of manufacturer information eg manufacturer=Samsung
publisher			use instead of keywords parameter to make a search only of publisher information eg publisher=Blackwell
title			use instead of keywords parameter to make a search only of title, notice you don't need the complete title, just a few key words eg title=Pride, Prejudice
browseNode		Positive integer	browse nodes are positive integers that identify product categories, for example, Literature & Fiction: (17), Medicine: (13996), Mystery & Thrillers: (18), Nonfiction: (53), Outdoors & Nature: (290060). You can find more about browse nodes here.
maxresults	10	number from 1 to 10	this parameter controls the number of results displayed for an item search, note that Amazon will always return a maximum of 10, for results beyond the first 10 use the itemPage parameter
itemPage	1	number from 1 to 10 (1 to 5 if searchIndex = All)	use to display results beyond the first 10, eg itemPage=2 displays the second 10 results. There is no way to display beyond the first 100 results, Amazon suggest in that case to refine your search
sort	relevance	'price' (low to high), '-price' (high to low), 'salesrank', 'titlerank' (Alphabetical: A to Z), '-titlerank' (Alphabetical: Z to A) and many others	control the sort order of results using the sort option, which can take many values, depending on the search index and your locale. You can see the complete list here. Eg: sort=-price
useAccordion	no	yes, no	Use a collapsible accordion to display results, to save space on the page
modalReviews	no	yes, no	have the customer reviews display in a modal window when you click a link, rather than in an iframe on your page
articleLayout	article	article, blog, search, book, brand, or custom layout name	control the layout when an an item lookup is viewed in a Joomla article view. Note that you can create your own custom layout, it you put it in the plugin tmpl folder you can then specify the layout using this parameter, eg if your custom layout is called dvd, use articleLayout=dvd
blogLayout	article	article, blog, search, book, brand, or custom layout name	control the layout when an an item lookup is viewed in a Joomla blog view, as for the article view, you can set your own custom layout, eg if your custom layout is called dvd, use blogLayout=dvd
searchLayout	search	article, blog, search, book, brand, or custom layout name	control the layout of item search results, eg searchLayout=dvd
mode		simple	use this to override the plugin behaviour, if the plugin is using the shopping cart mode on your site, but you want to override this and have just a simple link to the Amazon site for your product, then put mode=simple in your short code
linkType		internal, external	use this setting to force product links to point to a product page on your site (internal) or directly to the Amazon site (external)

You don't have to specify all the parameters, any that you omit will take the default values set in the plugin configuration, or the default value listed above.

Controlling the Results Page

By default, Amazon returns the first page of results, containing up to 10 results. You can change this using the itemPage option, which  can take a value from 1 to 10, and is used with search operations to determine which page of results are displayed. If you select a value over 10 you will get an error.  Amazon recommend in that case that you refine your search to return fewer results.

Controlling the Sort Order

You can control the sort order of results using the sort option, which can take many values, depending on the search index and your locale. The default is 'relevance', which depends on how often the keywords turn up in the item description. If you leave the sort option blank this is the ordering which will be used, which will normally be a good choice. Other popular ones that are defined in most cases are 'price' (low to high), '-price' (high to low), 'salesrank', 'titlerank' (Alphabetical: A to Z), '-titlerank' (Alphabetical: Z to A).

You can see the complete list here: http://docs.aws.amazon.com/AWSECommerceService/latest/DG/localevalues.html

Associates IDs for Authors

If the administrator allows the Amazon associates ID can be set by the article author in the embedding code. Otherwise the adminstrator can specify that his or her own associates ID must be used. This is done by editing the plugin parameters in the Joomla plugin manager.

Please note that Amazon now require you to obtain permission for each domain on which you use your ID. It will not return results until you do.

Countries

The Amazon product advertising API is available for the following countries: USA, Canada, UK, France, Germany, Italy, Japan, China, India, Spain, Brazil and Mexico. The plugin can support all these. Normally you would set the country in the plugin manager options, but, if you want to display products from more than one country website you can include this as a parameter in the embedding code. Country can take the values

• com
• de
• co.uk
• fr
• co.jp
• ca
• cn
• it
• in
• es
• com.br
• com.mx

 Caching

By default the plugin will fetch information directly from the Amazon server each time it displays. You can set it to cache the results from Amazon by setting the Cache Time option (on the debugging tab). Set a time in minutes, usually 10 is a good choice. To turn caching off again, reset the time to zero. While you are setting up the plugin and embedding it in your content, it is a very good idea to have the caching turned off, because otherwise you may not see the results you expect.

The advantage of caching is that it will speed your page loading time, and it will avoid problems with Amazon's 'fair use' policy. They restrict the number of requests that they will respond to, approximately one per second per site. They allow some flexibilty, but if you find that you are no longer getting any results, or only intermittently getting them, then this is the likely explanation, so you are recommended to turn on caching. Amazon do prefer that you keep the cache time short, so that prices do not change.

The plugin will automatically manage the cache, so that old results that lie outside the cache time will be deleted, so you do not have to worry about clearing it.

Layouts

You can select differing layouts for whether the plugin output is viewed in an article displayed in Joomla article or blog layout. You can set these using the plugin articleLayout and blogLayout options, which can be set either in the plugin manager or using the plugin embedding code.

You can also define your own layouts, simply by adding your own file to the amazonWS/tmpl folder, it will be automatically detected by the plugin. The easiest way to do this is to make a copy of an existing template, just give it a new name, edit it, then upload it to the folder. If you are creating a new template from scratch remember to give the file a .php extension or it will not be recognized, also remember to include at the beginning of the file the line

<?php defined( '_JEXEC' ) or die( 'Restricted access' );?>

This prevents the file from being directly accessed by an attacker.

Once you have set up your new layout you should see it listed in the plugin article and blog layout options. You can also specify it inline. For example suppose you have created a new template called music.php, you can then use the embedding code

{amazonWS:itemId=xxxxxxx;articleLayout=music;blogLayout=music}

Note that you do not include the .php extension in the embedding code. You do not need to include both the articleLayout and blogLayout options, if one is not included the value will be taken from the plugin options set in the plugin manager. For example you might want to have a standard layout for when the article is viewed in blog layout, consisting of just the product title and price and a thumbnail image, so you would set this in the plugin manager, then just specify the articleLayout in the embedding code.