X-Cart:X-AdvancedCustomerReviews

X-Cart 4.4or above

X-Cart 4.3.2

X-Cart 4.2.3

X-Cart 4.1.12

What Advanced Customer Reviews module does

The module Advanced Customer Reviews allows your customers to post feedback about the products in your store. The module expands the default X-Cart Customer Reviews module's behavior bundled with X-Cart.

The module forces customers to write a review if they want to rate a product. You can control via General settings/Modules->Advanced Customer Reviews which of the store site visitors should be allowed to post reviews:

• all customers;
• registered customers;
• those who bought product.

You can set the initial status for new reviews:

• approved: a review will be visible in customer and admin area;
• pending: a review will be visible in admin area only;
• rejected: a review will be visible in admin area only;

The ‘Add your own review’ button will be available for those customers who are allowed to add review on the Product details page and Product reviews page.

In case the customer is not allowed to add review he will see the corresponding message.

Each review can be accompanied by:

• the name of the author;
• the author’s email (will be visible in admin area only);
• the rating of the product allows customers to evaluate a product based on a point scale;
• the customer’s comment with tips or thought on the product;
• the advantages and disadvantages of the product (these blocks can be disabled via General settings/Modules->Advanced Customer Reviews.

The 'Add your own review' form can be protected by image verification. See X-Cart:Image Verification page for details.

Ratings of a product by different customers from each review are summed up, so the resultant rating of a product represents a simple average of its ratings by all the customers who have voted. Rating points (so called ‘general product rating box’) are represented by stars for each product on the products listing page and the product details page. The customer has an ability to view the detailed product rating information in the AJAX popup in the general rating box or on the product reviews page.

Approved customer reviews created by your customers are posted for everyone to see in the 'Customer Reviews' section and on the Product reviews page. Also there is the 'Read all reviews' page in customer area. The list of product reviews can be sorted in different ways: most helpful first or newest first.

Each review can be rated as useful or not with the ‘Was the above review useful to you?’ feature. This feature can be disabled via General settings/Modules->Advanced Customer Reviews. Each review can be rated from a unique IP only once.

The review will be marked as ‘verified’ if the review author is a verified product owner. It means that the review is added by registered customer who has the orders in ‘Processed’ or ‘Completed’ statuses.

You can allow to show Customer Reviews Menu box with one most recent, most useful or random review with rating not less than defined in module’s setting.

You can allow to send review reminder to your customers in several days (configurable) after an order is completed and only once for a product.

Product ratings on web search results pages

When Advanced Customer Reviews module is installed and enabled, your store's product pages include special markup that allows Google and some other search providers to include information about your products' customer ratings and reviews into web search results. This information will appear in web search results as soon as your store's product pages are indexed by the respective search engine. People who will be doing a web search to find a specific product and will find the product at your store will be able to see in their search results the average star rating of the product as given by your store's customers, as well as whether the product has any reviews at your store.

The following screenshot demonstrates how a product is presented in the Google search results with the Advanced Customer Reviews module installed at the store:

And this is how a product is presented in the Google search results without the Advanced Customer Reviews module:

You can see that with the Advanced Customer Reviews module installed at your store potential buyers get more information about your products in their search results. This information helps them recognize your site as relevant to their search and may result in more clicks to your store's pages.

Although this feature is intended primarily to enhance the presentation of your product information in Google, the schema.org format that is used by the module to mark up your store's pages is recognized by other major search engines as well.

Roles in Advanced Customer Reviews module management

If you are an X-Cart GOLD or GOLD PLUS administrator/provider or an X-Cart PLATINUM or PRO administrator:

• You can enable/disable and configure the module Advanced Customer Reviews (See Enabling and Configuring 'Advanced Customer Reviews' ).
• You can fully control customer reviews: edit reviews posted by customers, delete or reject unwanted reviews, add reviews of your own, import and export reviews (See Managing Customer Reviews).

If you are an X-Cart PLATINUM or PRO provider:

• You can control customer reviews for your products only: edit reviews posted by customers, delete or reject unwanted reviews, add reviews of your own (See Managing Customer Reviews).

System requirements and installation

Advanced Customer Reviews is available as a built-in module with X-Cart's GOLD PLUS and PLATINUM packages v.4.5.3 or later. This means that if your store is based on X-Cart GOLD PLUS or PLATINUM v.4.5.3 or later, Advanced Customer Reviews is already installed in your store. To start using this module, you just need to make sure it is enabled and adjust its configuration.

For X-Cart GOLD and PRO versions 4.1.12, 4.2.3, 4.3.2, 4.4.0-4.5.2 and X-Cart GOLD versions 4.5.3 and later, Advanced Customer Reviews is available as an add-on module which can be purchased separately. The following instructions will guide you through the process of installing the Advanced Customer Reviews add-on module in your store.

System Requirements

To be able to successfully install and use the Advanced Customer Reviews add-on module, you need a working copy of X-Cart (X-Cart GOLD or PRO v4.1.12, 4.2.3, 4.3.2, 4.4.0-4.5.2 or X-Cart GOLD 4.5.3 or later) installed on your server. Make sure that the version of the module is the same as the version of the installed copy of X-Cart.

Note: If you do not remember the version of the installed copy of X-Cart, find it in the Environment info section of the Summary page in X-Cart Admin area.

Installation for X-Cart 4.4.x - 4.5.x

To install the module:

1. Obtain a distribution package for the X-AdvancedCustomerReviews add-on module by downloading it from the File Area section of yourX-Cart Account. The distribution package you need is contained in the archive file X-AdvancedCustomerReviews-x.y.z-with-installer.tgz where x, y andz are the version numbers of the module. Make sure the version of the module is the same as the version of the installed copy of X-Cart.

2. Put the distribution package to the X-Cart root directory on your server or hosting account.

• If you use a Windows-based server, or a UNIX-based server without terminal access:

a) Decompress the archive with the X-AdvancedCustomerReviews distribution package to a directory on your system using your favorite compression program (WinZIP or any other archiver with support for TAR files).

b) Use an FTP client to upload all the files contained in the archive (retaining the directory structure) to the X-Cart root directory on your server or your hosting account.

• If you use a UNIX-based server with terminal access:

a) Use an FTP client to upload the archive with the distribution package to the X-Cart root directory on your server or your hosting account.

b) Decompress the package using the following commands.

tar -xzvf X-AdvancedCustomerReviews-x.y.z-with-installer.tgz

Important: Make sure you keep the directory structure while unpacking and uploading the distribution package, otherwise some necessary files can be overwritten!

3. In a web browser, run the installation script httр://<YOUR_XCART_DOMAIN>/install-advanced-customer-reviews.php replacing the variable<YOUR_XCART_DOMAIN> with the true name of the domain where X-Cart is installed.

4. Enter the Auth code, accept the License Agreement and click the Next button.

5. The installation script copies the files and activates the module. Click the Next button to continue the installation.

6. The installation script generates a new system fingerprint. Click the Next button to complete the installation.

7. Use the ADMINISTRATOR AREA link to log in to the Admin area.

Installation for X-Cart 4.1.12, 4.2.3, 4.3.2

To install the module:

1. Obtain a distribution package for the X-AdvancedCustomerReviews add-on module by downloading it from the File Area section of yourX-Cart Account. The distribution package you need is contained in the archive file X-AdvancedCustomerReviews-x.y.z-without-installer.tgz where x, y andz are the version numbers of the module. Make sure the version of the module is the same as the version of the installed copy of X-Cart.

2. Put the distribution package to some directory on your server or hosting account (it can be not X-Cart directory)

• If you use a Windows-based server, or a UNIX-based server without terminal access:

a) Decompress the archive with the X-AdvancedCustomerReviews distribution package to a directory on your system using your favorite compression program (WinZIP or any other archiver with support for TAR files).

b) Use an FTP client to upload all the files contained in the archive (retaining the directory structure) to the X-Cart root directory on your server or your hosting account.

• If you use a UNIX-based server with terminal access:

a) Use an FTP client to upload the archive with the distribution package to the X-Cart root directory on your server or your hosting account.

b) Decompress the package using the following commands.

tar -xzvf X-AdvancedCustomerReviews-x.y.z-without-installer.tgz

Important: Make sure you keep the directory structure while unpacking and uploading the distribution package, otherwise some necessary files can be overwritten!

3. In the uncomressed directory find the 'manuals' directory and use instructions from the 'manual-x.y.z.htm' file.

Enabling and Configuring 'Advanced Customer Reviews'

To begin using the module:

1. Enable Advanced Customer Reviews module (Settings menu->Modules).

When the module is enabled, you can see:

• the Customer Reviews link in the Catalog menu;
• the Advanced Customer Reviews section in General settings->Modules section;
• the Customer Reviews link on the Product modify page.

2. Adjust the module settings via General settings/Modules->Advanced Customer Reviews.

• Who must be allowed to add reviews: Specify who can create reviews: select All customers, Registered customers or Customers who bought product.
• Default status for new review: Specify initial status for a review added by the customer: select Approved, Pending or Rejected.
• Stars in product rating scale: Select the number of stars you want to be displayed as the product rating scale.
• Use old ratings values for general product rating: Select the checkbox to use ratings added for the products whilst the Customer Reviews module was used.
• Show "Advantages" and "Disadvantages" blocks?: Select the checkbox to show ‘Advantages’ and ‘Disadvanatges’ blocks in the ‘Add your own review’ form and in the customer reviews list.
• Display "Was the above review useful to you?" box: Select the checkbox to allow your customers to vote for the useful reviews.
• Reviews per page (admin area): Specify the count of reviews per search reviews page.
• Default reviews order (customer area): Select the default reviews sort: select Most useful first or Most newest.
• Reviews per product details page (customer area): Specify the count of reviews per product details page in the Customer Reviews tab.
• Reviews per page (customer area): Specify the count of reviews per product reviews and products reviews pages.
• Display customer reviews menu (customer area): Select the checkbox to display Customer Reviews Menu box.
• Reviews order in customer menu: Specify which review should be shown in Customer Reviews Menu box. Select Most recent, Most newest or Random reviews.
• Display reviews with N-stars and higher rating only: Specify the lowest rating for review that can be shown in the Customer Reviews Menu box.
• Receive an email notification when new review is posted: Select the checkbox if you want to receive an email notification when new review is added.
• Notification email addresses (use ',' to separate multiple email addresses): Specify one or more emails for notification about new reviews.
• Send review reminder to customer (if order is completed): Select the checkbox if you want your customers to receive an email notification with the links to post their review about purchased products
• Send review reminder to customer in N days: Specify in which days after order is placed the review reminder will be sent to the customer
• Start send review reminder for orders with orderid equal or greater than: This setting can be usefull if you have a lot of orders and do not want to send review reminders to old orders. You can specify the orderid that was placed 4 months ago, so all orders that were placed earlier will not be taken into account for review reminders.
• Secure key for launching review reminder script (send_review_reminders.php): Key is used for launching review reminder script. The minimum length of a key is 6 symbols.

3. Click the Apply changes button.

Managing Customer Reviews

Viewing customer reviews from the Admin area

You can view customer reviews for any product without leaving the Admin area. There are two ways for viewing customer reviews:

• Search reviews page (the Customer Reviews link in the Catalog menu);
• Customer Reviews link on the Product Modify page.

To view customer reviews for a specific product:

1. Find the product for which you want to view customer reviews.
2. Open this product for modification.
3. In the 'Product Management' section menu, click the link 'Customer Reviews'. A dialog box titled 'Edit reviews' should be opened.

The 'Edit reviews' dialog box is the place where all the reviews regarding the product being viewed can be seen.

Adding customer reviews from the Admin area

You can use the 'Edit reviews' dialog box to add reviews of your own directly from the Admin area.

To add a review:

1. Find the product for which you want to add a customer review. Open this product for modification.
2. Open the 'Edit reviews' dialog box for this product.
3. Use the 'Add new review' section of the 'Edit reviews' dialog box to create a new review:

• Use the AUTHOR field to enter your name and, optionally, your email address.
• Use the MESSAGE field to enter the text of your review.
• Click the Add/Update button.

Your review should be added to the list of customer reviews both in the Customer area and the store's Admin area.

Editing customer reviews

You can edit any reviews created by your customers. To edit a customer review:

1. Find the product for which you want to edit a customer review. Open this product for modification.
2. Open the 'Edit reviews' dialog box for this product.
3. Find the review you would like to edit in the list of customer reviews for this product.
4. Edit the review (If necessary, you can change the contents of both the AUTHOR and MESSAGE fields).
5. Click the Update button.

The edited review should be updated both in the Customer area and the Admin area.

Deleting customer reviews

Customer Reviews module allows you to delete abusive posts and any inappropriate content which might be posted to your store website via the 'Customer Reviews' section of the 'Customer Feedback' form. To delete one or more reviews with undesirable content:

1. Open 'Customer Reviews' page in admin back-end. Or find the product whose customer reviews you want to delete. Open this product for modification and open the 'Edit reviews' dialog box for this product.
2. Find the reviews to be deleted in the list of customer reviews.
3. Mark the found reviews for deletion by selecting the check boxes next to them.
4. Click the Delete selected button.

The reviews will be removed from the list of customer reviews both in the Customer area and the Admin area.

Review Reminder

Module allows send review reminders to customers that purchased products in your store. Review reminder will be sent only once per each product because each customer can add review for a product only once. Reminder is sent for completed orders only. You can specify in how many days a reminder will be sent, so your customer will have some time to use the purchased product. After that customer can be ready to post his own review.

Since your store can have a lot of orders that were posted in past years and earlier the setting 'Start send review reminder for orders with orderid equal or greater than' is added. You can specify the orderid that was placed 4 months ago, so all orders that were placed earlier will not be taken into account for review reminders.

You can choose to launch the script send_review_reminders.php from the command line or to set up cron job to launch this script automatically. Example of command to launch the send_review_reminders.php script:

cd /var/www/vhosts/yoursite.com/httpdocs/xcart; /usr/bin/php -d safe_mode=Off send_review_reminders.php --key=c901d65fc15ff15d0ac0af967437d051

Or the script can be run manually in your browser:

http://yoursite.com/send_review_reminders.php?key=c901d65fc15ff15d0ac0af967437d051

Email Notifications

There are two types of notifications available in the module:

1. Notifications about new reviews;
2. Review reminder notifications for customers after they purchased some products from your store.

You can enable/disable any of these notifications separately via the 'General settings/Advanced Customer Reviews' page.

How to change the content of notifications?

Any email notifications sent by your store can be changed/customized using X-Cart templates. These templates can be found under the following directories of your X-Cart installation:

X-Cart 4.4.х-4.5.х:
<xcart_dir>/skin/common_files/mail/ - plain text email templates
<xcart_dir>/skin/common_files/mail/html - html formatted email templates

X-Cart 4.3.2 and earlier versions:
<xcart_dir>/skin1/mail - plain text email templates
<xcart_dir>/skin1/mail/html - html formatted email templates

Notifications about new reviews

• ‘Receive an email notification when new review is posted’: If selected, the store administrator receives email notifications about new reviews added in the store
• ‘Notification email addresses’: fill in this field with one email or with emails separated by comma. The notification about new reviews will be sent to the specified email(s).

The following templates are used for this notification:

Plain text mail templates for this notification	HTML mail templates for this notification
mail/acr_review.tpl mail/mail_header.tpl mail/signature.tpl mail/acr_review_subj.tpl	mail/html/lacr_review.tpl mail/html/mail_header.tpl mail/html/signature.tpl mail/acr_review_subj.tpl

Review Reminder notification

• ‘Send review reminder to customer (if order is completed)’: If selected, your customers will receive an email notification with the links to post their review about purchased products.

Other settings for review reminder are described in the (Enabling and Configuring 'Advanced Customer Reviews' ) section.

The following templates are used for this notification:

Plain text mail templates for this notification	HTML mail templates for this notification
mail/acr_review_reminder.tpl mail/salutation.tpl mail/signature.tpl mail/acr_review_reminder_subj.tpl	mail/html/acr_review_reminder.tpl mail/salutation.tpl mail/html/signature.tpl mail/acr_review_reminder_subj.tpl

Canonicalization

Advanced Customer Reviews module adds to your store such links:

http://www.example.com/reviews.php?productid=12

http://www.example.com/reviews.php?productid=12&cat=3

The content of such pages are identical. To consolidate properties, such as link popularity, and to avoid “duplicate issue” in search engines these new URLs should be canonicalized, i.e. it is recommended to pick a canonical (preferred) URL as the preferred version of the page. Advanced Customer Reviews for X-Cart v.4.3.2 and later specifies a canonical page to search engines by adding a <link> element with the attribute rel="canonical" to the <head> section of the page.

<link rel="canonical" href="http://www.example.com/reviews.php?productid=12">

Another way to pick a preferred URL is to set up a 301 redirect to the canonical URL. To enable 301 redirects for products reviews pages in your store, follow the procedure below:

1. Ensure that the following minimum requirements are met:

• Your store site is powered by Apache web server.
• The Apache web server has the module mod_rewrite configured and enabled.

2. Back up the .htaccess file located in your X-Cart installation directory.

3. Edit the .htaccess file located in your X-Cart installation directory to add the required configuration directives:

• Open the .htaccess file in a plain text editor.
• Copy this block:

# Reviews page redirect [[[
Options +FollowSymLinks -MultiViews -Indexes
<IfModule mod_rewrite.c>
RewriteEngine On

RewriteBase /

RewriteCond %{REQUEST_URI} ^/reviews.php [NC]
RewriteCond %{QUERY_STRING} ^productid=(.*)&cat=(.*)
RewriteRule ^(.*)$ reviews.php\?productid=%1 [R=301,L]

</IfModule>
# /Reviews page redirect ]]]

• In the plain text editor, paste the block you have copied at the end of the .htaccess file.
• Save the .htaccess file.

4. After adding the required configuration directives into your .htaccess file, try to open X-Cart's product reviews page with the additional parameter in the URL like ‘&cat=3’: http://www.example.com/reviews.php?productid=12&cat=3

You should be redirected to the URL without 'cat' parameter, i.e. URL should look like this: http://www.example.com/reviews.php?productid=12

Try to open other store’s pages. If you do not see any error messages returned by the server, all is well, redirects work correctly. If you see error messages, restore the original .htaccess file from backup and contact your hosting provider about the problems you are having with the functionality of Apache's mod_rewrite module (Send them the lines you have tried to insert into your .htaccess file).

Troubleshooting

"Review Reminder doesn't send emails"

Please check:

• The minimum length of a "Secure key for launching review reminder script" is 6 symbols.

• In your browser try to open the page:

http://<yourstore.com>/send_review_reminders.php?key=a2gHudkv81bpqrm61ft

(change <yourstore.com> to your URL and key to your own key from module's settings)

• If the page is blank or 'Key is not correct' message is shown then double check the key and its length.

• If you see the text like '0 order(s) are checked 0 email(s) are sent' then it means there are no orders for which review reminder must be sent right now. Review reminder email is sent once for completed orders only and after N days after order is created. Number of days is defined in module's settings. By default this setting is set as '21'.

Review Reminder logs are saved in '<xcart_root_dir>/var/log/x-errors_review_reminder-YYMMDD.php' files.