- Background Information on Amazon Module and the Amazon Product Advertising API
- Installation and Configuration
- Using the Amazon ASIN CCK type
- Using Views with Amazon
- Using the Amazon Examples Sample View and CCK type / field
- Using Tokens
- Using the Filters Provided with the Amazon Filter Module
- Theming Templates (.tpl.php)
- Amazon Store Module
- Associate IDs and Locales
- Technical Details
- Migrating data from Amazontools (Drupal 5) to Amazon module (Drupal 6)
Amazon.com (and its variants in the UK, France, Japan, etc.) provides a Product Advertising API which is enormously powerful and provides information about books and many other consumer products. Amazon Module provides that functionality for Drupal using the Product Advertising API.
Using this module requires you to have an Amazon AWS account which you can get at Amazon AWS. In addition, you probably will want an Amazon Product Advertising account, which you get at Product Advertising API. To understand fair use of the API, read that page and their License Agreement.
Each item on Amazon.com has a unique identifier called an ASIN, or Amazon Standard Identification Number. It's 10 characters long. Note that ASINs for the same item may be different on different versions of Amazon's site (different locales, such as France, Japan, etc.)
To use this module, the ASIN will be the fundamental concept. You can get ASINs to use several ways. You can use the Amazon Search module, you can search Amazon.com, or you can use the Amazon Store module. On any product page on Amazon.com, you will see the ASIN in the "Product Details" section. It is also clearly visible in the page URL.
In place of an ASIN you can also use an ISBN number or an ISBN-13 or an Amazon.com link.
- Install and enable the modules as usual. Normally, this just means untarring into sites/all/modules and enabling the modules you want on the modules page.
- You must enable the Amazon API module.
- Amazon Field provides the Amazon CCK type.
- Amazon Filter provides a Drupal filter in the form [amazon ASIN thumbnail] that you can use to put Amazon data directly into content in the body of any item.
- Amazon Media provides extended support for books, music, DVDs, and software.
- Amazon Search provides a rudimentary search facility.
- Amazon Examples provides a sample CCK type and view that demonstrate how to use Amazon module with CCK and views. It requires the features module. To turn it on, either enable the module or go to the Features configuration page at admin/build/features and enable it. (When features is turned on, it seems to hide the amazon_examples module, letting you manage it only from within its own interface.)
- Obtain an Amazon AWS account if you do not already have one. Go to http://aws.amazon.com and sign up. Then you'll need to go to the "Security Credentials" page to get your Access Key ID and Secret Access Key. Note: If you already use Amazon AWS and do not want to disclose your keys by configuring them on the site, you can get a new free Amazon AWS account.
- Go to admin/settings/amazon (Administration -> Configuration -> Amazon API) and configure the module with:
- Locale: Which store are you going to use? US? UK? Japan?
- Amazon Referral Settings: Every purchase bought by a referral can get you a commission if you would like. You can set this to the Drupal Association's ID, the module developer's ID, or to your own. To get your own ID, sign up at the correct Amazon locale signup location..
- Your Amazon keys. Instructions on getting an account if you don't have one are above.
- After configuring, go to the test page (the "test" tab) and enter a valid Amazon ASIN. An example might be 0596515804. Click the submit button and make sure that the system can look up the ASIN. If it succeeds, you're all set!
Using the Amazon ASIN CCK type
Note: If you enable the Amazon Examples module (provided), it provides a preconfigured CCK type which you can experiment with. The following instructions just duplicate that.
The simplest and easiest way to use Amazon information is with a CCK type. If you have enabled the Amazon Examples module, then you already have a CCK type to work with. The following instructions will just duplicate that.
- Create a content type at admin/content/types/add.
- Add a field and set the field type to "Amazon Item".
- Create a node or two of this content type. The ASIN field requires either a 10-digit ASIN (Amazon Standard Identification Number) which each product on Amazon's websites provides, a link to the product page on Amazon's site, or an ISBN-13 number like "978-0596515805".
- You should see the product show up in your node. In the content type settings, you can configure the display type for four different presentations.
When the Token Module is enabled, the Amazon Module provides token support, which can be used with other modules such as href="http://drupal.org/project/auto_nodetitle">Automatic Nodetitles and Path Auto’s automatic URL
CCK field tokens
(Pending resolution of #1043030)
Some of the items available for use as tokens for the CCK field are:
- Product ID
- Title retrieved from Amazon.com
- The 10-digit ISBN (International Standard Book Number)
- The EAN or 13-digit
- The detail page URL for the item
- The product's Amazon product type
(Where tokens are allowed, all available Amazon tokens are listed under Replacement Patterns.)
Tokens for Amazon ASIN CCK type work similarly to other CCK types, such as Text. If used as a multiple value field, the token will refer to the first value.
Tokens for Automatic Nodetitle
When combined with href="http://drupal.org/project/auto_nodetitle">Automatic Nodetitles, you can remove the need for users to enter a node title for your Amazon content type. Use the title fetched from Amazon.com as your node’s title.
- If you have a field named field_asin, automatically assign the product
title as your node title. Use [field_asin-title] as your Automatic title
- If you have a field named field_amazon, automatically assign the product
ID as your node title. Use [field_amazon-asin] as your Automatic title
(Use "Replacement Patterns" in your site's User Interface if you are unsure of your field names or which tokens are available to you.)
Note: Again, if you enable the Amazon Examples module (provided) it preconfigures a view called Amazon Example View which uses the CCK type "Amazon Example", so you don't have to do anything to try out a view.
There are three ways to use Views with Amazon module:
- Configure a node-type view and just use and configure the Content: ASIN field (or whatever your field is called. This will allow you to present the view with four different basic presentations, but does not allow sophisticated access to the many pieces of information provided with Amazon data.
- Configure a node-type view and create a relationship on the Content: ASIN field (or whatever your field is called. Make the relationship required. You will then have access to many fields and filter options that can be displayed in your view.
- Configure an "Amazon Item" type view. This will let you have access to all Amazon Items cached on your system, with all of the information stored in each. There is no linkage information to the nodes that might use these items.
If you create a relationship on the Content field, you get access to a wide variety of product information. Some of the important items are:
- All Participants (authors, etc.)
- Detail Page URL (link to Amazon.com page, or Amazon Store page)
- Invalid ASIN - set to 1 if the ASIN can no longer be looked up on Amazon, but remains in your database.
- List Price
- Product Image (configurable for the three sizes Amazon provides)
You can also use any of the many data items together with the views custom data field to construct a more sophisticated link, image, etc. There is an example of this in the examples views.
Note that the Editorial review[s] and Customer Reviews are also available. Since there may be more than one of these per Amazon item, you'll need to use a view that is filtered by a single ASIN, or you'll end up with more rows than you were expecting.
Using the Amazon Examples CCK type and View
Amazon module now ships with a feature which provides a sample content type and a sample view. Here's a quickstart on how to use it:
- Download (if necessary) and enable the features module
- Enable the features module at admin/build/modules
- Go to the features UI at admin/build/features and enable the "Amazon Examples" feature.
- You now have a CCK type called "Amazon Example".
- Create a couple of instances of "Amazon Example" by going to node/add/amazon_example. Here are a couple of ASINs you can use: 1430209895 and 0470429038. Your nodes should show a thumbnail and the title of the item at this point.
- Go to the Views interface at admin/build/views and you'll see an "Amazon Example View". Click "edit" and you can look at and modify and experiment with it. The two nodes you created should show up there.
First, enable the Amazon Filter module at Admin->Site Building->Modules.
Now go to Administer -> Site configuration -> Input formats. Switch on the Amazon filter for each input format you want to process Amazon tags.
Now you can use many filters in the format [amazon <ASIN> <action>] in any text field that is processed by the filter.
Some filters just present a simple view of the product:
- [amazon 0596515804 thumbnail] presents a thumbnail and the item title.
- [amazon 0596515804 full] presents a larger image and more information.
[amazon 0596515804 inline]
just puts the item title linked to the Amazon page inline.
Alternately you can use an ISBN, ISBN-13, or Amazon link in place of the ASIN:
- [amazon http://www.amazon.com/Using-Drupal-Angela-Byron/dp/0596515804 full]
- [amazon 978-0596515805 full]
In addition, many, many other options are available, providing access to much of the data available:
- [amazon 0399155341 author]
- [amazon 0596515804 asin]
- [amazon 0596515804 isbn]
- [amazon 0596515804 ean]
- [amazon 0596515804 title]
- [amazon 0972380175 editorialreview] (The product description; may not be available except in the US locale.)
- [amazon 0596515804 detailpageurl]
- [amazon 0596515804 salesrank]
- [amazon 0596515804 publisher]
- [amazon 0596515804 manufacturer]
- [amazon 0596515804 studio]
- [amazon 0596515804 label]
- [amazon 0596515804 binding]
- [amazon 0596515804 listpriceamount]
- [amazon 0596515804 listpricecurrencycode]
- [amazon 0596515804 listpriceformattedprice]
- [amazon 0596515804 productgroup]
- [amazon 0596515804 producttypename]
- [amazon 0596515804 invalid_asin] (set to 1 if this ASIN is no longer valid on Amazon)
- [amazon 0596515804 deweydecimalnumber]
- [amazon 0596515804 edition]
- [amazon 0596515804 numberofpages]
- [amazon 0596515804 publicationdate]
- [amazon 0596515804 type]
- [amazon 0596515804 releaseyear]
- [amazon 0596515804 publicationyear]
- [amazon 0596515804 smallimage]
- [amazon 0596515804 smallimageurl]
- [amazon 0596515804 smallimageheight]
- [amazon 0596515804 smallimagewidth]
- [amazon 0596515804 mediumimage]
- [amazon 0596515804 mediumimageurl]
- [amazon 0596515804 mediumimageheight]
- [amazon 0596515804 mediumimagewidth]
- [amazon 0596515804 largeimage]
- [amazon 0596515804 largeimageurl]
- [amazon 0596515804 largeimageheight]
- [amazon 0596515804 largeimagewidth]
Theming Templates (.tpl.php files)
Amazon module provides many .tpl.php files which can be copied to your theme and altered to change the behavior and presentation of your system. See the Drupal Theming Guide for details about how this works.
- amazon_inline_item.tpl.php changes the 'inline' presentation.
- amazon-item-detail.tpl.php is used to theme most of the filter detail items, such as publicationdate, etc.
- amazon-item-details.tpl.php is used to present item details in the "full" presentation.
- amazon-item-thumbnail.tpl.php presents the 'thumbnail' presentation.
- amazon-item.tpl.php is the default item presentation.
- amazon-item-book-details.tpl.php (in amazon_media)
- amazon-item-dvd-details.tpl.php (in amazon_media)
- amazon-item-software-details.tpl.php (in amazon_media)
- amazon-item-video-games-details.tpl.php (in amazon_media)
In addition, the row-item template for views is provided and can be overridden. (amazon-views-view-row-item.tpl.php).
Amazon Store Module
If you want to use the Amazon for an actual shopping or browsing experience, you may be interested in the Amazon Store module, which uses Amazon module as a base. Amazon Store has significant integration with Amazon, and if installed, links from Amazon items in your nodes can be configured to point to Amazon Store product detail pages.
Associate IDs and Locales
While the Product Advertising API works across all Amazon's sites, to receive credit for referrals to one of the six Amazon sites you will also require a locale-specific Associate ID. For example, if you wish to refer your site's visitors to .co.uk products you will need an Associate ID from that site. Once you have obtained your ID, enter it into the field in 'Amazon API' under configuration in your site's admin pages.
These can be obtained from
- Canada (.ca) - https://associates.amazon.ca/
- Germany (.de) - https://partnernet.amazon.de/
- France (.fr) - https://partenaires.amazon.fr/
- Japan (.co.jp) - https://affiliate.amazon.co.jp/
- UK (.co.uk) - https://affiliate-program.amazon.co.uk/
- US (.com) - https://affiliate-program.amazon.com/
- If you want to understand what's going on under the covers, the documentation on Amazon's API is on their site.
Instructions how to Migrate data from Amazontools to Amazon module are available on a separate handbook page.