Com GoogleBaseXML Documentation

Googlebase Menu

• GooglebaseXML Documentation
• Legacy Versions for Joomla 1.5 and Virtuemart 1.1x
• Getting Your Product Feed Accepted by Google
• Product Feed Images
• My feed shows a parsing error

This article describes the usage for our component GooglebaseXML. This extension for Joomla and Virtuemart generates a product feed which can be uploaded to Google Merchant Centre for submission to Google product search and Google Shopping.

System Requirements

This documentation is for the version 4 series of GooglebaseXML. The component requires Joomla 2.5 and Virtuemart 2. You can find documentation for older versions of the component, compatible with older versions of Joomla and Virtuemart, here.

Installation

Upload and install as normal using the Joomla! installer.

Basic Usage

Basic usage is quite straightforward. Once you have installed the component go to components->Googlebasexml on your admin menu. This will bring up a simple control panel for Googlebasexml. Clicking the options button will bring up the global options for the feed. All options can be set globally, or on a per-feed basis. We discuss the options below. We recommend that you do read the documentation first, before submitting your feed to Google.

You will need to create one or more feeds. Click the ‘new’ button to create a new feed. Under ‘Details’ you need to give it a name. This name will not be output in the feed, so you can give it a name that is most helpful to you. Now set the feed options, and click ‘Save and Close’.

Now you should see your feed listed, including its title and URL. You can create as many feeds as you want, and submit them all to Google. This is useful when you want feeds targetting more than one country, you can create a feed for each country. Also if you have a lot of products you may need find it helps to have several feeds, each of a smaller sizer.

Submitting the Feed to Google - Scheduled Upload

The URL will look something like this: http://www.mysite.com/index.php?option=com_googlebasexml&format=xml&id=1. This is the URL that you can submit to Google for scheduled upload. The feed will be dynamically generated so is automatically updated to reflect your current products.

Submitting the Feed to Google - Manual Upload

Alternatively you can just click the link to see the generated feed. The save the resulting page to your computer as a text or XML file, then you will be able to upload it manually to Google.

Feed Specification

You can find details of Google’s feed specification here. You should read it carefully. If you do not follow its requirements your feed will probably be rejected.

The format of the product data stored by Virtuemart is substantially different from that required by the Googlebase feed specification, hence it requires some extra work to support all the Google feed attributes. However this can be done with GooglebaseXML. The component supports the following main product attributes:-

 id, title, link, price, sale price, sale price effective date, description, condition, gtin, brand, mpn, image link, additional image links, product type, google product category, availability, quantity, shipping, manufacturer, shipping weight, featured product, identifier_exists.

Additionally the component allows for the variant attributes: size, color, age group, gender, pattern and material. If your Virtuemart products include child products then the component can display these as product variants. If you are going to do this it is important to read Google’s feed specification carefully.

Because Virtuemart does not directly support some of these attributes it is necessary to use a bit of ingenuity to use them. Where the attribute will normally have a constant value for most or all your products the easiest way is to to define a default value in the component parameters. Where the attribute varies for your products then the recommended method of including the information is through the use of Virtuemart custom fields. There is also a simple method of embedding condition, mpn and gtin data, simply by including it in the product description (this is described below), however recommend using the custom field approach, it is more flexible, for example you can choose to hide it from customers by making it a hidden field.

Virtuemart Custom Fields (Virtuemart 2)

The most effective way to include the attribute data that Google requires is through the use of Virtuemart product custom fields. We have a general guide to creating custom fields in Virtuemart 2 here . You can use this method to include variant attributes for your products, also to include mpn, gtin, condition, availability and google category information.

The process is:

1. In your Virtuemart admin go to product->custom fields, and create a product custom field, called for example gtin. This only needs to be a simple string field, and not a cart attribute;
2. In your product editor, go to the custom fields tab, select the custom field and add the required value, then save;
3. Now open the Googlebase XML options, under Custom Field For GTIN you should see the custom field listed, select it and save, so that the feed know which custom field to use.

The process needs to be done in that order because until some custom fields are defined they will not be available as options in the GooglebaseXML configuration.

Understanding the Component Options

Basic Options

The basic options should be quite easy to understand. There are some important points:

1. The title, description and store URL are required, and will be included in the feed.
2. Google requires a unique identifier for each product. If you don’t have an identifier for the product it will not be included in the feed. If your store uses SKUs (stock keeping units) for your products it is a good idea to set the product identifier to the SKU. Otherwise you will need to set it to the product id. This is the identifier generated automatically in the product database so will alway exist.
3. If your store just uses a single language and currency, and you are just submitting the feed for one target country (and are not including shipping information, see below for more about shipping), then you do not need to set the target country, language, or currency, in fact it is probably better not to. The default values for your store will automatically be used. If you are including shipping information, or you are submitting feeds targetting more that one country, you will need to set the target country. If you are submitting to more than one country you can use the ‘Add country code to identifier’ option to generate a unique identifier per product per feed, which Google requires.
4. You can choose to limit your feeds to specific categories, or paginate your feeds. The normal reason for doing this is when you have a lot of products, and your server runs out of memory trying to generate the feed. In this case you can try generating a feed for each of your main categories and submitting each feed to Google separately.

Alternatively you can use the limit and limit start options. ‘Limit’ will control the number of products included in the feed, ‘Limit Start’ controls the number of products skipped before the count starts. Note that the count starts from 0, not 1. An example should make this clear. Suppose you have 5,000 products. That is a lot of products, and the chances are that your server will run out of memory before generating a feed of that size if you try to include all the products at one. To solve this, you can create 5 feeds. The limits will be set as follows for each feed:-

Feed	Limit	Limit Start
Feed 1	1000	0
Feed 2	1000	1000
Feed 3	1000	2000
Feed 4	1000	3000
Feed 5	1000	4000

Product Options

This tab allows you to set options for supplying product information such as the brand, condition, GTIN, MPN, tax and shipping.

Brand

There are a variety of ways in which the brand information can be set: setting a default value, using the Virtuemart manufacturer, using the category name, using a custom field (see above for an explantion of how to use custom fields). How you want to do this will depend on how your store is organised. For example, some stores group their product categories by brand, so using the category name is a natural choice. However, if most of your products have the same brand, using a default value may be the natural choice, with perhaps a custom field to override this in case of any exceptions.

Condition:

Google accepts only the following values for this: new, used, or refurbished. You can set the default value for this attribute for your site using the component ‘default product condition’ parameter. You can create a custom field to supply the value (see custom fields above). You can also over-ride the default value for an individual product by including one of the following in your product description:-

• Condition: New
• Condition: Used
• Condition: Refurbished

For example, if your site sells mostly new stuff with a few refurbished items you might want to set a default value of ‘new’ for your products’ condition, and include the string ‘Condition: Refurbished’ somewhere in your product description.

The other required attributes are self-explanatory, since they match Virtuemart data fields. Note that Googlebase will not accept free items, so the component tests whether the product price is greater than 0 before listing a product.

gtin

GTIN stands for Global Trade Identification Number. This is a unique product identifier for your product. These identifiers include UPC (in North America), EAN (in Europe), JAN (in Japan), and ISBN (for books). You can include any of these values within this attribute.

If you are using Virtuemart 2.6 (or above), supplying the gtin is straightforward, because Virtuemart now includes a product_gtin field, you just supply it in the product editor. The feed will automatically use this value.

If you are using earlier versions of Virtuemart you can create a custom field to supply the value (see custom fields above).

Alternatively you can embed the information in the product description. To include a gtin, add one of the following to your product description:-

• upc: 001234567891
• ean: 1001234567891
• jan: 123456789
• isbn: 0451524233
• gtin: 0451524233

Note that the numbers above are examples, you will need to replace them with the actual product code number.

mpn

MPN stands for manufacturer product number (the number which uniquely identifies the product to it’s manufacturer).

If you are using Virtuemart 2.6 (or above), supplying the mpn is straightforward, because Virtuemart now includes a product_mpn field, you just supply this. The feed will automatically use this value.

If you are using earlier versions of Virtuemart, you can create a custom field to supply the value (see custom fields above). Alternatively, to include this attribute, include the following in your product description:-

• mpn: GO1234568OOGLE

Please note that the number is an example, replace this with your actual number. The code can accept the following characters: a-z A-Z 0-9 :\-_

identifier_exists

For most products Google requires at least two out of the three attributes: brand, mpn, and gtin. However for some products, such as vintage clothing or original works of art, these kind of identifiers do not make sense. In this case it is possible to send a special identifier_exists tag with a value of FALSE. You can turn this option on, then the feed will send this value if there is no gtin or mpn.

Product Type

Google accepts text such as ‘Home & Garden > Kitchen & Dining > Appliances > Refrigerators’ for this attribute. The Googlebasexml component constructs this from the category path for the product.

Google Product Category

Google product category must correspond exactly to the product taxonomy defined here: http://www.google.com/support/merchants/bin/answer.py?answer=160081

For example: Food, Beverages & Tobacco > Food Items > Grains, Rice & Cereals.

There is no need to worry about escaping the > and & characters, this will be done automatically when the feed is generated.

If most of your products belong to the same category the easiest way to set this attribute is through setting a default value in the GooglebaseXML parameters. If you want to override this for an individual product you can do this by setting up a custom Google category field as a product custom field (see custom fields above).

Availability

This attribute consists of text with only three accepted values: ‘in stock’, ‘out of stock’, ‘available for order’,’preorder’. You can set the default value for this attribute using the component ‘Default Product Availability’ parameter. If you want to override this for an individual product you can do this through the Virtuemart product editor, which includes an ‘availability’ field (on the product status tab), or through setting up a custom product availability field.

Shipping

You can set the main shipping data through the Google merchant centre control panel. If you are using weight-based shipping the feed can display shipping weights. If you are not using weight based shipping it is best to turn off the ‘show weight’ option, it may cause problems for your feed.

 You can also have the feed calculate shipping directly using the Virtuemart standard weight-based shipping. It should be stressed however that there really is no good reason to do this, it will involve the feed generation in a lot of extra calculation. Provided you have specified your shipping rules correctly in the Google Merchant Centre and turned on the ‘show weight’ option in the feed, Google can do this work for you. If you do elect to display the shipping costs in the feed you must select the target country, so that the correct shipping rules can be selected.

Product Variant Options

The feed can optionally display additional attributes such as gender, age group, colour and size. These are required for clothing products in the US, and optionally can be included for other items and other countries. You can use custom fields to represent this data. Please note that you will actually have to have some custom fields defined in order for there to be selectable options for the size, colour etc data.

Google also allow you to submit data for product variants. They define variants as a group of identical products that only differ by the attributes ‘color’, ‘material’, ‘pattern’ or ‘size’.

The feed can display child products as product variants by selecting the ‘Show Product Variants’ option on the ‘Product Variant Options’ tab. If this option is selected, for products that have children, the child products will be displayed instead of the parent product, which will not be displayed. If this option is not selected child products will be excluded from the feed, only the parent products will be displayed. Simple products that do not have children or parents are unaffected by this option.

If you want to display product variants it is a good idea to read Google’s feed specification carefully, specifically the section on product variants: http://support.google.com/merchants/bin/answer.py?hl=en-GB&answer=188494&topic=2473824&ctx=topic#GB .

Advanced Options

You will not normally need to set the advanced options. However for reference this is what they do:-

• Base URL: Occasionally there is a problem with the product links caused by a bug with Joomla SEF URLS when the site is in a sub-directory of a domain. This parameter can be used to enforce the correct path in the product links. Just set it to your domain without the sub-directory path, in other words the root domain of your site.
• Debug component: this option includes a lot of additional information in the feed which we can use to debug most data related problems. Please turn it on if you are contacting our support, otherwise keep it turned off
• Clean Output Buffer: this option can be used when faulty 3rd party Joomla extensions such as system plugins cause a problem with the XML validation resulting in a parsing error (see below for more details). Faulty plugins can insert extra whitespace before the feed is generated. This option attempts to correct the problem by forcibly emptying the Joomla output buffer before generating the feed.

Troubleshooting

1) Problem. The page takes a long time to load, and finally you get a blank page.

When this happens it is because the script is running out of memory, which can happen if you have a large number of products.

Solution

The script includes code to increase the memory size by changing the PHP configuration, but some hosting providers do not allow the configuration to be changed at run-time.

You may be able to solve this by putting a text file in the root folder of your site called php.ini - this should contain the line:- 

memory_limit=256M 

which will increase the memory to 256 megabytes. You can experiment with this value if you require more.

 An alternative is to submit multiple feeds as described above using the Limit and Limitstart parameters. This is the option that we recommend. Once you have set up the feeds you only need to submit them to Google once, they can be automatically submitted by scheduled upload in future.

2) The page loads, but I do not see any products, just a title and description.

If the page loads and you see a title and description, but no products, it is not a problem with your memory limit, but with the options you have chosen for the feed..

Firstly, check the category options. A lot of sites will often have a main category, then sub-categories where the products actually are, it may be that this is what your problem is. If you want to show products in any child categories of your main category you will need to include those categories too, the feed literally includes only products in the category or categories that you actually select. You can include more than one category at a time using control-click or shift-click to select them.

Also, check if you are using product SKUs to identify your products. Google require a unique product identifier, the feed can use either the id number in the product table, or the product sku. The sku is probably a better choice but you need to make sure your products actually have skus if you are doing this.

Also check that the product prices are visible on your site, google require this, so that the feed will not include products that don’t have a visible price.

3) Problem. The feed shows an XML parsing error

This problem is usually caused by faulty 3rd party system plugins which contain whitespace characters such as a space or line break outside of PHP tags. These characters are output directly, ahead of the feed, resulting in an empty space before the opening <xml> tag in the feed. Unfortunately the specification for an XML document is very precise and this is not allowed: the <xml> tag must be the very first thing in the document. The result is a parsing error.

There is more information about how to track down the source of the error here. We also include an option ‘Clean Output Buffer’ on the advanced tab of the configuration options. You can turn this option on, it will attempt to solve the problem by forcibly emptying the Joomla output buffer before the feed is generated. This is not guaranteed to work, but it may.

4) Problem. The feed is not showing my discounts.

The calculation of discounts is a perennial problem, because what you as a store owner may consider to be a discount is not necessarily what Google considers to be a discount. Google require both a start and end date for the discount, otherwise they consider it to be just a normal price. Virtuemart allows you to create a discount in three different ways: you can create an override price, create a calculation discount rule and then assign it to a product, or create a generic rule and allow products to automatically adopt it. The feed needs to carefully check each case to see if a relevant start and end date exist. If they do not then the feed should include the discounted price as the normal price, because this is what Google ask for.

Solution

Firstly make sure you have included start and end dates for the discounts. If you have, and the feed is still reporting the discounts incorrectly please let us know. Please also supply information that we can use to track down the source of the problem:

• which method you are using to create the discount, eg is it an override price or a generic discount rule?
• which version of Virtuemart are you using
• is the final price being reported correctly, or is the discount not being applied at all?

If you just tell us that your discounts are not working without any other information then this gives us nothing at all to go on and we cannot help you.