Amazon Link free WordPress plugin

This plugin is used to quickly add Amazon products links to your WordPress posts and pages. The product links can be simple text links, thumbnail images, full-size images, complex templates or full-blown Amazon flash widgets.

The product links that can be for any of the Amazon domains (UK, US, Brazil, Canada, China, Germany, Spain, France, Italy, India, Mexico, Australia and Japan).

The content of the product links can be statically entered by the Author (when the link is created), or dynamically refreshed when displayed using data from the Amazon site that is most appropriate for the nationality of the reader.

The product links to be displayed can be specified when the link is created, using the built in Amazon search widget, or dynamically generated by searching the content of the site.

All product links will contain the Amazon affiliate ID of the site author and will be the relevant one for that locale. This allows you to collect commission on any products purchased through the links.

Key features

• Search Tool to assist authors to create links in posts and pages
• Simple [amazon] shortcode used to generate product links
• Localisation of all links based on the nationality of the reader
• Amazon Product Details Cache to ensure pages load quickly
• Optional multinational popup to allow the reader to choose which Amazon site to visit
• Global options to update the behaviour of all the links on your site
• Ability to locally override the global options using the shortcode content
• Affiliate Tracking IDs for each WordPress user or by user specified ‘Channels’.
• Flexible template facility to enable the author to quickly create complex content quickly and consistently
• Includes built in templates for the major Amazon widgets (Carousel, My Favourites, etc.).
• Facility to extend and modify the functionality of the plugin using WordPress filters

Quick Start

To quickly add a simple text link add the following lines into an entry (page, post or text widget): [amazon asin=&text=]

Where ASIN Number is the unique amazon number used to identify products e.g. “1405235675”. The Link Text is simply what you want to be shown for the link, e.g. “Mr. Good”.

To utilise one of the templates simply specify the template option with the name of the template to use. For example: [amazon asin=&title=&thumb=&template=thumbnail].

To take full advantage of the plugin features it is recommended that you have an Amazon Web Services account, and enter the Access Key ID and Secret Access Key in the Amazon Link Settings page. Once your AWS account settings are entered the plugin can be configured to dynamically fill in the templates with live information from the appropriate Amazon site. Alternatively you can use the Amazon Search tool on the Page/Post edit screen to find Amazon products and let the plugin pre-fill the Amazon Link shortcode with all the details needed to create the appropriate template.

To generate a list of products relevant to the content of your site use the ‘cat’ option, to specify where the plugin should search for Amazon product links. This option can be either ‘local’ to search the current page content or a list of category ids to search specific sections of your site. For example I use this feature to provide friends and family some ideas for presents. This feature also needs access to the Amazon Web Service API and uses the ‘CartSimilarities’ feature to generate the list of items.

This is created by either putting the line amazon_recommends(,) in your template. Or putting the line [amazon cat=&last=] within a post or page. Where ‘Category’ is a list of category ids to search within (e.g. as expected by the ‘cat’ argument of query_posts function. The ‘last’ parameter is the number of posts to search through.

Latest Version – 3.2.10

• Bug Fix – The default ‘no image’ URL use https if site is using https
• Bug Fix – Remove any hard coded ‘http’ URLs (inc Templates)
• Bug Fix – Make links use ‘AWS’ parameters

Settings

The plugin Settings page is where the author can modify the behaviour of all the links embedded in their site.

Note any changes here will affect all existing links that do not explicitly set these options via the shortcode content. These options can be viewed as the ‘default’ behaviour any of which can be overridden locally by adding the appropriate parameter to the shortcode.

The Settings are split into 5 sections dealing with different aspects of the plugin:

• Display Options
• Localisation Options
• Amazon Associate Information
• Amazon Data Cache
• Advanced Options

Display Options

These options affect the default appearance and behaviour of standard text links and the type of Amazon Wishlist that is displayed.

Image Class

Allows the author to change the default class used when the plugin inserts a thumbnail or image into a post. This option is equivalent to the ‘image_class’ shortcode argument, and the %IMAGE_CLASS% keyword in the template.

Wishlist Template

This is the default template used by the plugin when it auto generates a list of products using the wishlist facility. This option can be overridden in the shortcode by specifying a valid template using the ‘template’ argument.

Wishlist Length

This is the maximum number of items to display in a wishlist. This option can be overridden in the shortcode by specifying the ‘wishlist_items’ argument.

Note: Amazon only returns a maximum of 5, for the ‘Similar’ type of list.

Wishlist Type

This sets the default type of wishlist to generate. A wishlist of type ‘Similar’ will show items similar to the ones found in the content. A wishlist of type ‘Random’ will show a random selection of the ones found. A wishlist of type ‘Multi’ simply lists the items in the order they were found. This option can be overridden in the shortcode by specifying the ‘wishlist_type’ argument.

New Window Link

If this option is enabled then when generating links, the plugin will ensure that if they are clicked on it will open it in a new browser window. This option is equivalent to the ‘new_window=1’ shortcode argument.

Link Title Text

This is the text that will appear in the link ‘title’ attribute for the Amazon links, it may contain any of the usual template keywords e.g. %TITLE% or %TEXT%. Leave blank to not have a title attribute.

Use Media Library

This option adds the ability to upload images for products from the Amazon site to your local WordPress media library. Once uploaded the plugin will always use these local images for all shortcodes for that product.

Add Amazon Link – Form Options

These options affect the default values that are shown in the ‘Add Amazon Link’ helper box that is used to insert Amazon Link shortcodes into Posts.

Link Text

If you do not specify the ‘text’ argument in your [amazon] shortcode, then this text will be used by default. This option is equivalent to the ‘text’ shortcode argument, and the %TEXT% keyword in the template.

Default Template

Use this setting to pre-select the template to use when inserting new Amazon Links into posts.

Default Channel

Use this setting to pre-select the channel to use when inserting new Amazon Links into posts. If nothing is selected then the ‘Default’ channel is always used.

Default Search Index

Use this setting to pre-select which search index should be used when searching for Amazon products.

Localisation Options

The localisation options control how the plugin deals with visitors from countries other than your default locale. The majority of these options require the ip2nation database to be installed.

At the top of this section is the current status of the ip2nation database and buttons to allow you to Remove, Update or Install the database.

Default Country

If localisation is not enabled, or has failed for some reason, then this is the default Amazon site to use for the link.

Localise Amazon Link

If this option is selected and the ip2nation database has been installed then the plugin will attempt to use the most appropriate Amazon site when creating the link, currently supports www.amazon.co.uk, www.amazon.com, www.amazon.com.br, www.amazon.ca, www.amazon.cn, www.amazon.de, www.amazon.es, www.amazon.fr, www.amazon.in , www.amazon.it and www.amazon.co.jp.

Global Defaults

When creating Amazon Links the plugin will use data provided in the shortcode in preference to data retrieved from Amazon (e.g. Setting the ‘Title=My Favourite Book‘ in the shortcode will override the Title retrieved from Amazon). If you have localisation enabled, by default the data in the shortcode will only override your default locale. Enable this option if you want shortcode data to override the Amazon data in all locales.

Create Search Links

If localisation or the Multinational popup are enabled then the plugin will create links to Amazon sites other than your default locale. Sometimes these links either do not work – for example that exact product ASIN is not available in that country. Or is not suitable – for example it is an incorrect region DVD or a book in the wrong language.

Selecting this option will force the plugin to generate links to non-local Amazon sites that search for your product rather than an exact ASIN link. The exact terms of the search are determined by the next option.

This option can be overridden in the shortcode by specifying the ‘search_link=1’ or ‘search_link=0’ argument.

Default Search String

If the ‘Create Search Links’ option is enabled then this string determines what keywords are used to create the search link. Any of the keywords used in the Templates can be used to generate the term, for example the keyword ‘%ARTIST%’ will be expanded by the plugin to the Author/Artist/Director of the linked item.

This option can be overridden in the shortcode by specifying the ‘search_text=Specific Search String’ argument.

Multinational Link

If this option is selected then the plugin will enable a small popup menu of country specific links whenever the user’s mouse rolls over the Amazon link, enabling them to select the site they feel is most appropriate.

Amazon Associate Information

To get the most out of the Amazon Link plugin it is highly recommended that you have access to the Amazon Product Advertising API and populate the ‘Amazon Web Services’ (AWS) key settings.

This will enable a number of features of the plugin that require access to Amazon Web Services (AWS). These include the generation of live data when displaying the links, providing a product search facility on the post/page edit admin screens, and the ability to generate product wishlists & recommendation.

If you wish to use any of these features then you must have the appropriate AWS Access IDs and enter them in these two settings. To get these keys simply register with the Amazon Web Service – Advertising API site and this will provide you with the appropriate strings. Note you must also enable the Product Advertising API in your AWS account for this to work correctly.

See the ‘Getting Started‘ section for a guide to joining the various Amazon Affiliate programmes & the Amazon Advertising API.

AWS Public Key

Enter the ‘Access Key ID’ found in your AWS Account under ‘Security Credentials > Access Credentials’

AWS Private Key

Enter the ‘Secret Access Key’ found in your AWS Account under ‘Security Credentials > Access Credentials’

Once you have entered your AWS Access keys and updated the options the AWS Keys Validated checkbox should be ticked. If it is not the Error Message displayed should provide a clue to why the keys are not working.

Live Data

If this option is enabled then the plugin will attempt to retrieve up to date (and localised) information on the product when generating the product link. For this to work the AWS Access keys in the global settings must be configured with valid keys. If not enabled then the plugin will only use the information included in the shortcode. This option can be overridden in the shortcode by specifying the ‘live=1’ or ‘live=0’ argument.

Note this option also changes the behaviour of the Amazon Search Tool. When the tool is used to insert shortcodes into the post it will automatically prefill the keywords needed for the selected template. It will only do this if live data is not enabled.

Condition

Change the condition of the items returned when making Amazon Web Service requests, this affects the items returned on the search box as well as the pricing and offers returned when getting details about a specific item. The Amazon website notes on the ‘Condition’ parameter:

Use the Condition parameter to filter the offers returned in the product list by condition type. By default, Condition equals “New”. If you do not get results, consider changing the value to “All…

ItemSearch returns up to ten search results at a time. When condition equals “All,” ItemSearch returns up to three offers per condition (if they exist), for example, three new, three used, three refurbished, and three collectible items. Or, for example, if there are no collectible or refurbished offers, ItemSearch returns three new and three used offers.

Prefetch Data

Normally the plugin will not fetch data from the Product cache or via AWS unless it needs to populate a keyword. This means that for simple text links the plugin is much faster. However if all your shortcodes are complex and require data retrieved from the AWS then enable this option to improve template parsing.

User Affiliate IDs

This options enables all users of the WordPress site to have their own set of Affiliate IDs. This allows each post author to collect Amazon commission on posts for which they are the Author. The IDs (one for each locale) are accessible on the User’s profile page.

Amazon Caches

Amazon Product Cache

If you use the plugin to its full extent and display a lot of content retrieved from the Amazon Web Service it is recommended that you enable the Amazon Product Cache.

This will improve page load times for pages that retrieve live data from the Amazon Web Service by keeping a local copy of the data.

At the bottom of this section are buttons to Enable, Disable (and remove) and Flush the content of the Amazon Data Cache.

Cache Data Age

Amazon recommend that data is not stored in caches for too long, especially price and availability information. Adjust this setting depending on the volatility of the data you display (e.g. Titles, List Prices and Artist information rarely change, however Offer prices may change more frequently).

Shortcode Cache

If you have a site with high levels of traffic, then it may be worth while enabling the ‘Shortcode cache’. This stores the expanded template in the site database rather than evaluating it for every visitor. You are trading off extra Database access and storage against Server CPU load. This option is currently experimental and has not been properly evaluated to see if it does actually reduce server load.

If you are already using some other form of WordPress content cache then this will add no additional benefit.

SC Cache Data Age

The number of hours data is kept in the shortcode cache without being refreshed. Keep this low to ensure that the latest product details are always displayed.

Advanced Options

Template ASINs

This setting only affects the Template Previews in the Template Manager section of the Amazon Link Settings page. Change this list of ASINs to change which ASIN(s) are used to generate the Template Previews.

Debug

If you are having problems with the plugin and need to contact me, it may be helpful if you could enable this option briefly. It causes the plugin to put extra hidden output in your sites pages that are displaying Amazon Links. I can use this information to diagnose any problems.

It is not recommended that this option is enabled for any length of time as it will show your AWS access keys in the page HTML source.

Purge on Uninstall

If you want to permanently uninstall the plugin then select this option before uninstalling on the ‘Installed Plugins’ page. This will ensure that all Amazon Link Settings, Templates, Associate Tracking IDs, Cache Data and the ip2nation data are removed from the WordPress database.

Shortcode

The main arguments available when creating a shortcode are listed below, enter each argument separated by a ‘&’. It is also possible to override settings on the global options page, or elements used in the product templates:

text

The text used to generate the amazon link, Enter any plain string e.g. ‘text=My Text’.

image_class

The css class used when displaying the image in the post.

asin

The unique Amazon product ID or IDs, of the form ‘1405235675,1234567890’. Enter as ‘asin=1405235675,1234567890’. It is also possible to specify different ASINs per local using the form ‘asin=1405235675,1234567890&asin=1840347839,0123456789’.

template

Which template to populate and display with product data, must be one of the templates listed on the Amazon Link > Templates Settings page.

chan

It is possible to manually select which set of tracking IDs the link uses by specifying the ‘chan=channel_id’ option. This will override the user specific affiliate ids.

cat

When creating a wishlist you must specify the post category(s) through which to search for other Amazon links. Enter as ‘cat=4,7’. Alternatively enter ‘cat=local’ to search the content on the current page.

last

When creating a wishlist you can specify how many posts to search through for Amazon links. Enter as ‘last=30’.

localise

Overides the ‘Localise Amazon Link’ setting. 0 to force the default country, 1 to force localisation.

multi_cc

Overides the ‘Multinational Link’ setting. 0 to disable the popup, 1 to enable the popup.

search_link

Overrides the ‘Create Search Links’ setting. 0 to force direct links by ASIN, 1 to force search based links.

search_text

Overrides the ‘Default Search String’ setting. A more specific search string can be used to generate the links.

default_cc

Overrides the ‘Default Country’ setting. Must be one of ‘uk’, ‘us’, ‘ca’, ‘cn’, ‘de’, ‘es’, ‘fr’, ‘in’, ‘it’ or ‘jp’.

pub_key

Overides the ‘AWS Public Key’ setting.

priv_key

Overides the ‘AWS Private Key’ setting.

wishlist_items

Set the number of items in this particular wishlist. Overides the ‘Wishlist Length’ setting.

wishlist_type

Set the type of this particular wishlist. Overides the ‘Wishlist Type’ setting.

Technical

AWS Requests

The plugin relies upon the php script aws_signed_request kindly crafted by Ulrich Mierendorff.

The plugin has two utility classes that might be of use to other plugin designers. The first is one for generating the options page (as well as the ‘Add Amazon Link’ meta box). The second is an AJAX facility for performing Amazon product searches and returning an array of product details, including a facility to fill in a HTML template with various attributes of the product using the patterns %TITLE%, %PRICE%, %AUTHOR%, etc. See the plugin source files for more details on how to utilise them.

Translations

The plugin comes with translation support but as yet no translations are included, please refer to the WordPress Codex for more information about activating the translation.
If you want to help to translate the plugin to your language, please have a look at the i18n/amazon-link.pot file which contains all definitions and may be used to create a language specific .po file, if you do then
contact me and I will add it to the plugin ready for the next update.

Disclosure

Amazon requires that all access to the AWS system contain a valid affiliate tag. If you don’t not have an affiliate account for all locales do not worry. If the setting is empty the plugin will automatically insert a valid one by default. However it is recommended that you enrol in the Amazon Affiliate program for all countries that your site targets.

Future Updates

There are a number of things I want to update the plugin to do, some of which have already been done in other plugins, but not quite how I would like. I would like to bring it all together in one plugin.

Features I will be adding to the plugin in the future:

• Allow the wishlist to search for legacy Amazon links not just ones embedded in the shortcode.
• Have static data for displaying the template previews, for users without AWS keys
• Source Widgets not working on new install – Template ASINs has no default?
• Add diagnostics submenu, get cache cron task working, display ‘not found’ items in cache page
• Add ‘Status’ Box -> Alerts on Dashboard, nag, ‘not found’ items, x% from locale with no tag
• Kindle items not showing list price, add format?
• Combine ‘convert’ and ‘alternates’ extras plugins
• Add flush to sc cache on any admin change, settings, template post/page edit.
• Add Price history database, graph popup -> cloud store/access data

Plugin Extras

This option which is automatically enabled when Developer Support is enabled, allows access to plugin extras. These are additional smaller plugins that provide extra features such as:

• Cache – Extra control and access to the Product Cache
• Convert – A Beta utility to convert Amazon Links to other formats
• Editorial – A plugin to add the EDITORIAL keyword to display Product Editorial Content
• Images – Allows access to all product images and the ability to change the size of images
• Redirect – Enables link cloaking
• References – Allows the user to create shortcuts to common products e.g. ref=fav books
• Spoof Locale – To enable testing of your site as if viewed from another country
• Styles – Change the stylesheet used by the plugin

Additionally any custom feature developed are also only available with this option enabled.

Upgrading

Some guidance on upgrading the Amazon Link plugin from one version to the next.

Be prepared

As with all software upgrades have a recent backup your database prior to installation, at the very least take a screenshot of your settings. The plugin should upgrade okay but there may be teething problems with the new version so if you want to regress to a previous version you may need to reset your settings.

Disable Extra Plugins

The latest versions of the plugin support additional features installed as ‘extra’ plugins if you have installed any of these then prior to upgrading the Amazon Link plugin disable them.

Install the New Version

Upgrade the plugin using your usual method, normally using the ‘Update Now’ button on the Main Plugins page.

Any problems at any point in the upgrade process don’t hesitate to use the WordPress Amazon Link plugin forums to get help.

Check Your Settings

After the new version has been updated and re-activated go to the Amazon Link Settings page and check your settings are as expected, your IP2Nation database is detected, the AWS keys still validate and the cache is detected.

On the Affiliate IDs Settings page check your affiliate IDs are all correct (especially those in the default channel).

Check the Templates are still available on the Templates Settings page, and check each template displays as expected.

Upgrade Extra Plugins

If you are using any extras plugins go to the Extras Settings page and check if any need updating. One at a time Activate each plugin in turn checking for any problems.

Check Your Links

Browse a good cross section of your posts and pages check that the links are displayed as you expect and your affiliate IDs are included in the links.

If you use localisation then try using the spoof locale extras plugin to check what you site and links look like from other locales and that your affiliate IDs are included in the links.

Feedback

Good or bad please feedback your view on the latest plugin version in the forum, rate or review the plugin, mark the plugin as ‘Working’ or not on the main plugin page, or if your feeling generous a donation might help the next version along!