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

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 and India. 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

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.