Bazaarvoice for Magento 2 Extension

Transcription

1 Bazaarvoice for Magento 2 Extension Integration Guide Version: Disclaimer Copyright 2016 Bazaarvoice. All rights reserved.

2 The information in this document: Is confidential and intended for Bazaarvoice clients. No part of this document may be shared with anyone outside your company or your company-partners without prior approval from Bazaarvoice. Is provided as is without warranty of any kind either expressed or implied, including, but not limited to the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. Is periodically updated to be in sync with the improvements and/or changes in our product offers. May be changed without notice. Some examples depicted herein are provided for illustration only and are not guarantees of a specific result. You bear the risk of using this document. Bazaarvoice is not liable for any technical or typographical errors that might be inadvertently present in this document. Bazaarvoice might have patents and/or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents, or legal rights to any other intellectual property in any Bazaarvoice service or product. All Bazaarvoice brand and product names are trademarks or registered trademarks of Bazaarvoice in the United States and may be protected as trademarks or registered trademarks in other countries. All other product, service, or company names mentioned here are claimed as trademarks and trade names by their respective companies. Contact Us: Bazaarvoice Inc Stonelake Blvd. Austin, TX Tel (toll-free): (866) Tel (toll): (512) info@bazaarvoice.com Bazaarvoice 1

3 Table of Contents Introduction System Requirements Before You Get Started Mapping your Magento Environment to your Bazaarvoice Environment Scenario 1: Map Multiple Magento Websites to a Single Bazaarvoice Instance Description of Scenario How to Setup the Scenario Scenario 2: Each Magento Website maps to a separate Bazaarvoice Instance Description of Scenario How to Setup the Scenario Scenario 3: Each Magento Store (Group) maps to a separate Bazaarvoice Instance Description of Scenario How to Setup the Scenario Scenario 4: Each Magento Store View maps to a separate Bazaarvoice Instance Description of Scenario How to Setup the Scenario Using Bazaarvoice Families Product Catalog Feed Inline Ratings Product Detail Cloud SEO BV Pixel Purchase Feed Submission Installation Configuration Pre-Requisites Disable Magento Reviews (if applicable) General Ratings and Reviews Questions and Answers Feeds Cloud SEO Bazaarvoice 2

4 BV Pixel Product Catalog Feed Appendices Appendix A: Code Logic and Data Mapping Setup Script Operations Product Feed Field Mapping Brands Categories Products Include Categories Algorithm Include Products Algorithm Purchase Feed Algorithm BV Pixel Data Mapping String Replacement of Special Characters Appendix B: Advanced Configuration Putting Bazaarvoice Content Behind a Tab Purchase Feed Change Delivery Schedule of Bazaarvoice Feeds Appendix C: Troubleshooting Contact Bazaarvoice for Support Bazaarvoice Logging Verify Magento Cron is Running Manually Running Feeds Via Magento Admin Via command line Appendix D: Migrating to Production Steps for Testing Integration in Staging Before Launch on Production Steps to Move from Staging to Production Version History Bazaarvoice 3

5 Bazaarvoice 4

6 Introduction Bazaarvoice maintains a pre-built integration into the Magento platform. This pre-built integration is delivered in the form of a Magento Extension. The extension is supplied as-is and is intended to function as a started kit for clients to implement Bazaarvoice. It includes support for commonly required integration points, but does not include pre-built functionality for the exhaustive list of Bazaarvoice features. This extension may need to be customized by the client in order to implement functionality not included in the extension. System Requirements The requirements to run the Bazaarvoice Magento Extension are the same requirements established to run Magento Core. See Note: The link to Magento System Requirements frequently changes. Before You Get Started You should consider the following sections before installing the extension. Mapping your Magento Environment to your Bazaarvoice Environment Magento is a very flexible platform. As such, the following scenarios describe how the Magento extension can handle different ways to map the Magento environment to the Bazaarvoice environment. Scenario 1: Map Multiple Magento Websites to a Single Bazaarvoice Instance Description of Scenario BV Provisions a single instance Locales are mapped at the Store View level Bazaarvoice 5

7 A single product catalog feed is generated for the entire Magento Install (the feed will contain localized attributes (e.g. Product Page Urls, Product Names, etc.) for each Store View in the Magento Install) Limitations: If a product is in multiple store views of the same locale only the last one found will be included in the feed. The default values in the feed will be generated based on the first store id found in the Magento Install. How to Setup the Scenario Contact Bazaarvoice to provision a Bazaarvoice instance for your Magento Install In Magento Admin panel, set Feed Generation Scope to Global Set Bazaarvoice client-level settings (Client Name, SFTP Password, Cloud SEO Key) at the Default configuration scope in Magento. Set Locale at each Store View configuration scope (optional) Deployment Zone can be configured at the Store View scope as well. Scenario 2: Each Magento Website maps to a separate Bazaarvoice Instance Description of Scenario BV Provisions an instance for each Magento Website Locales are mapped at the Store View level Bazaarvoice 6

8 A single product catalog feed is generated for the entire Magento Website (the feed will contain localized attributes (e.g. Product Page Urls, Product Names, etc.) for each Store View in the Website) Limitations: Each Store View must map to a unique BV Locale within a given BV instance All stores within a single website must share the same category tree How to Setup the Scenario Contact Bazaarvoice to provision a separate Bazaarvoice instance for each desired Magento Website. In Magento Admin panel, set Feed Generation Scope to Magento Website Set Bazaarvoice client-level settings (Client Name, SFTP Password, Cloud SEO Key) at the Magento Website configuration scope. Set Locale at each Store View configuration scope Other Bazaarvoice client-level settings (Client Name, SFTP Password, SEO Cloud Key) should inherit from the Website scope. (optional) Deployment Zone can be configured at the Store View scope as well. Bazaarvoice 7

9 Scenario 3: Each Magento Store (Group) maps to a separate Bazaarvoice Instance Description of Scenario BV provisions an instance for each Magento Store (Group) Locales are mapped at the Store View level A single product catalog feed is generated for Magento Store (Group) (the feed will contain localized attributes (e.g. Product Page Urls, Product Names, etc.) for each Store View in each Store (Group)) Limitation: each Store View must map to a unique BV Locale within a given BV instance How to Setup the Scenario Contact BV to provision a separate BV instance for each desired Magento Store (Group). In control panel, set Feed Generation Scope to Magento Store / Store Group. Because settings cannot be configured at the Magento Store (Group) level, you must set the BV client-level settings (Client Name, SFTP Password, Cloud SEO Key) at the Bazaarvoice 8

10 Magento Store View configuration scope and ensure that these settings match for all Store Views within the given Store (Group). Locale should be set at the Store View configuration scope. (Optionally) Deployment Zone can be set at the Store View configuration scope. Scenario 4: Each Magento Store View maps to a separate Bazaarvoice Instance Description of Scenario BV provisions an instance for each Magento Store View Locales are mapped at the Store View level A single product catalog feed is generated for Magento Store View (the feed will contain a single set of localized attributes (e.g. Product Page Urls, Product Names, etc.) for the Store View locale) Bazaarvoice 9

11 How to Setup the Scenario Contact BV to provision a separate BV instance for each desired Magento Store View. In control panel, set Feed Generation Scope to Magento Store View. All control panel settings should be configured at the Magento Store View configuration scope. Because each Store View will map to a separate BV instance, the same locale can be used across the Store Views. Using Bazaarvoice Families The Bazaarvoice for Magento Extension includes support for creating Bazaarvoice Product Families where the Configurable product is the Parent, and Simple product is the Child. The sku or External ID is used as the Family Name. When product family support is enabled both the configurable, and simple associated products will be added to the family, and EXPAND will be set to true on both. We have added the ability for you to set EXPAND on simple products to false by adding a short xml snippet to the app/etc/local.xml file. See Appendix B Advanced Configuration. With EXPAND set to true both configurable, and simple products will display the totals for the entire family when displayed in the catalog. When EXPAND set to false only the configurable product will display the totals for the family, and the simples will display only their content. Below is how each piece of Bazaarvoice is affected when Bazaarvoice Product Families are enabled. Product Catalog Feed Configurable sku will be family name Configurable will be a member of it s family All associated simple products will be member of family Simples are included in feed whether they are visible or not. When simple is visible We will send its category We will send its url We will send its image When simple is Not Visible Individually We will send parent category We will send parent url We will send its base image if one exists otherwise send parent Bazaarvoice 10

12 Inline Ratings No Change here what is displayed depends on the EXPAND setting. When EXPAND true simples will display the totals of all family content. When set to false simples will display only their rating and review numbers. Product Detail Similar to above On products with single configurable option the ratings and reviews displayed will reflect the results for the resulting external id as selected. This means that when EXPAND set to false you would be able to see only the Ratings and Reviews for the simple product as selected based on the configurable option. An example of this would be if you have flavors as a configurable option. When the cherry flavor is selected you would see content relating to the cherry flavor. Cloud SEO Functions normally BV Pixel Simple sku is sent Simple name is sent Simple image is sent if base image available otherwise config image url is sent. Purchase Feed Same as BV Pixel Submission All submissions will be attributed to the simple product as selected. Bazaarvoice 11

13 Installation You can install our Magento 2 extension via Composer. Please follow these simple steps: 1. Make sure composer is setup properly for your Magento 2 Instance 2. In the Magento 2 root directory run the following command: composer require bazaarvoice/bazaarvoice-magento2-ext: After the above is successful, run this command in Magento root directory. This will let Magento know about the extension. php bin/magento module:enable Bazaarvoice_Connector 4. Run this command in Magento root. This will ensure any installer scripts we may have are executed properly and store the current data version. php bin/magento setup:upgrade 5. You may need to run this command to deploy an necessary static content php bin/magento setup:static-content:deploy 6. Run this command if you have a single website and store: php bin/magento setup:di:compile 7. Or this one if you have multiple websites or stores: php bin/magento setup:di:compile-multi-tenant 8. Clear cache from Magento admin. Configuration Complete the following steps to configure the extension. Pre-Requisites Before continuing, make sure you have the following information. Understand how you are mapping your Magento environment to Bazaarvoice (see previous section), include which locales should be enabled within Bazaarvoice. Whether or not you require Bazaarvoice Families functionality (see previous section). Bazaarvoice client name value. Bazaarvoice Deployment Zone value. Bazaarvoice SEO Key value. Bazaarvoice 12

14 Disable Magento Reviews (if applicable) You should first disable the default Magento reviews module, if your Magento store is currently configured as such. 1. Log in to the Magento Admin. 2. Navigate to Stores > Configuration > Advanced > Advanced. 3. Set Magento_Review module to Disable and Save Config. General With the information you obtained from Bazaarvoice it is time to start configuring the extension. 1. Log in to the Magento Admin 2. ig 3. Navigate to Catalog > Catalog > Storefront section, and make sure Use Flat Catalog Category and Use Flat Catalog Product are both set to Yes. (This will require the indexer to run.) 4. Navigate to General > Bazaarvoice Connector and configure the extension a. Set Enable Bazaarvoice Extension to Yes b. Select the desired Bazaarvoice Environment (Staging or Production) c. Set the Client Name (the name defined in the Bazaarvoice platform for the client instance; typically reffered to as client folder name ) d. Set Enable BV Product Families to Yes if you plan to use these features e. Set Deployment Zone (default is Main Site ) f. Set the Locale (e.g en_us, fr_ca, etc.; language-only values are not supported by Bazaarvoice) g. Set Enable Cloud SEO to Yes h. Enter your Cloud SEO Key this can be found in your Deployment Zone Implementation in the SEO settings section. i. Set Enable BV Pixel to Yes j. Set Debug to yes if you are in staging and need to troubleshoot the install. Ratings and Reviews 1. Set Enable Ratings & Reviews to Yes 2. Set Use Submission Container Page to Yes (if this is enabled you need to make sure the submission container url is configured in your Implementation. In Bazaarvoice Workbench navigate to Settings > Manage Applications, and select the Implementation you are working with. Select Technical Setup in the left navigation, and enter your container URL in the Container URL config. The url will be your Magento domain Bazaarvoice 13

15 followed by bazaarvoice/submission/container/. For example: 3. Make sure you select all of the areas you want to contain Inline Ratings in Enable Hosted Inline Ratings Questions and Answers Note : You may have to contact Bazaarvoice to enable Questions & Answers in the Bazaarvoice platform. 1. Set Enable Questions & Answers to Yes Feeds 1. Set Enable Product Feed to Yes (If you have multiple websites/store groups/store views this may be disabled by default, and only enabled on the website/group/view config for the site you are enabling Bazaarvoice) 2. Set CronJob Frequency (Minutes) to the same interval your Magento cron is running at. Usually this is run every minute, so a value of 1 would likely be entered here. 3. Set Feed Generation Scope according to how you are connecting to Bazaarvoice. A bit of planning should be done on deciding how this should be configured. 4. Set SFTP Username 5. Set SFTP Password 6. Set SFTP Host Name this is based on your location. Either Europe or Everywhere Else 7. Product Feed Filename setting should be left unchanged unless explicitly directed otherwise by Bazaarvoice. 8. Product Feed Export Path setting should be left unchanged unless explicitly directed otherwise by Bazaarvoice. 9. Set product feed attribute mapping. Attributes will only appear in the dropdown which have been set Yes for Use in Product Listing These attributes should be created in advance, and ensured that they are appearing in your product flat table. Otherwise they will be missing from the Product Feed 10. Set Expand Families in Product Feed to Yes if you want simple products to be displayed in your catalog with the reviews from all products in store. Cloud SEO The Magneto Extension utilizes the Bazaarvoice Cloud SEO solution. Bazaarvoice 14

16 The Bazaarvoice Magento Extension currently uses version of the BV EOSD for PHP found here: BV Pixel The Magento Extension includes support for BV Pixel. This feature is an analytics tag on the checkout success page. This tag provides a small set of data elements to BV when an online user completes the checkout process. Note: Around lines when viewing source of the Success page you will see the beacon if enabled in the Magento Admin. You need to make sure you are viewing the current source of the success page. By default the view source functionality in many browsers reloads the page in order to view it. In this case the information will not be visible. 1. Ensure that Enable BV Pixel is checked in the Magento Admin panel. Product Catalog Feed The Bazaarvoice for Magneto Extension includes support for generating a product catalog feed to Bazaarvoice and upload the feed via SFTP to Bazaarvoice. As of this release the schema version set in the feed is By default, the Bazaarvoice Product Feed is scheduled to run every day at 1 AM ( Note: the time zone is set based on the locale set in Magento at the default configuration scope). Complete the following to enable the Product Feed: Ensure that the Magento cron job is enabled Ensure that Enable Product Feed is checked in the Magento control panel. See the Advanced Configuration section for instructions on how to verify that the Magento cron job is running, as well as how to change the default time of day for the cron jobs. Bazaarvoice 15

17 Appendices Appendix A: Code Logic and Data Mapping Setup Script Operations During installation of the extension a number of changes are made to the Magento Database. 1. Add attribute sent_in_bv_postpurchase_feed to sales_order table with default value Create product attribute bv_feed_exclude 3. Two tables are created for the product feed Index (bazaarvoice_index_product, bazaarvoice_product_ci) Product Feed Field Mapping Brands Magento Attribute OptionId for assigned brand attribute Name from selected option of assigned brand attribute BV Attribute ExternalId Name LOCALIZED DATA Name from selected option of assigned brand attribute at the Store View level Name locale= Categories Magento Attribute *id/url path *id/url path of Parent Category Name URL of Category from Flat Table BV Attribute ExternalId ParentExternalId Name CategoryPageUrl LOCALIZED DATA Bazaarvoice 16

18 Category Name Name locale= CategoryPageUrl Products Magento Attribute sku name description id or path of assigned category. The assigned category is the deepest in the tree if product is in more than one category. Full url of the product detail page Full image url of the default product image id of the selected brand value(s) of the attribute mapped to UPC in BV Feeds configuration section value(s) of the attribute mapped to Manufacturer Part Number in BV Feeds configuration section value(s) of the attribute mapped to EAN in BV Feeds configuration section value(s) of the attribute mapped to ISBN in BV Feeds configuration section value(s) of the attribute mapped to Model Number in BV Feeds configuration section BV Attribute ExternalId Name Description CategoryExternalId ProductPageUrl ImageUrl BrandExternalId UPC ManufacturerPartNumber EAN ISBN ModelNumber LOCALIZED DATA Name ProductPageUrl Bazaarvoice 17

19 ImageUrl Include Categories Algorithm Root Category Based on the Feed configuration setting Include categories at level greater than 1 Include only active categories Find all categories that have the root path included in their path If the count is greater than 0 write the categories to the file Include Products Algorithm Retrieve the products from the website Only include Enabled products Only include products that are visible in the catalog aka Visibility does not equal Not Visible Individually Write to the file if there are more than 0 matching products. It is ensured that the CategoryExternalId is one that is included in the category section of the feed. Purchase Feed Algorithm There are 3 config settings for purchase feed process: - Enabled / Disabled - Triggering Event (Can be Shipping or Purchase) - Lookback days The purchase feed code adds one extra field / attribute to the Magento order record: - "ALREADY SENT IN FEED" (Field defaults to false when new order created by Magento) Purchase Feed process follows this algorithm: > Init new local feed file > Find all store groups in Magento Instance (Also know as stores, this is the level above store view) > For each store group > Check if purchase feed is enabled in the default store view within the group > If yes, > Find all Magento order meeting these criteria: (order is in a store within current store group) (order status = 'complete' or 'closed') (order created_date >= 30 days ago) (order "ALREADY SENT IN FEED" field = false) > For each order found: > Does order meet all these criteria: Bazaarvoice 18

20 (order "ALREADY SENT IN FEED" field = false) (order status is not 'cancelled') (order->store field is empty) (really this should never happen with Magento) (order has at least 1 item) (order has a customer address) > And, does order meet one or the other of these criteria: ("TRIGGERING EVT" = Shipping AND order has completely shipped AND more than 1 day has passed since the last shipment) or ("TRIGGERING EVT" = Purchase AND more than 1 day has passed since purchase happened) > If yes, > Add order to local feed file > Set "ALREADY SENT IN FEED" field = true for order > If no, do nothing > If no, do nothing > Save local feed, send local feed file to BV via SFTP BV Pixel Data Mapping Magento Order Increment Id TaxAmount ShippingAmount GrandTotal City RegionId Code CountryId OrderCurrencyCode *CustomerId Customer *CustomerFirstName StoreLocale Magento Etension Plugin Bazaarvoice orderid tax shipping total city state country currency userid nickname locale partnersource Bazaarvoice 19

21 Order Items Sku Name Price QtyOrdered sku name price quantity ImageUrl imageurl * When Guest Checkout is used there is not UserId for the customer. In this case we are sending the MD5 hash of the customer address. We also need to obtain the customer s first name from a different location. String Replacement of Special Characters Because the Bazaarvoice platform cannot accept product, category, or brand ID values that contain special characters, the Magento extension automatically transforms any offending ID values based on the following table: Special Character & Replace With bv38_amp_bv59 % bv37 (space) bv32 / bv47 $ bv64 # bv35 ] bv93 [ bv91 bv125 ` bv96 Bazaarvoice 20

22 ~ bv126 < bv38_lt_bv59 > bv38_gt_bv59 \ bv92! bv33 ^ bv94 ( bv40 ) bv41 bv124 = bv61? bv63 Bazaarvoice 21

23 Appendix B: Advanced Configuration Putting Bazaarvoice Content Behind a Tab In the default Magento 2 template we were able to put the rr and qa content inside the tab completely in module code without template modifications. Assuming any custom theme does not break that functionality, it should work out of the box. Purchase Feed Note: For most Bazaarvoice clients, BV Pixel data can be used as a replacement for the purchase feed feature. It is not necessary to enable both the BV Pixel as well as the purchase feed feature simultaneously. For clients who insist on enabling the purchase feed, the following should be completed: Ensure that Enable Product Feed is checked in the Magento control panel. By default, the feed is configured to run every day at 1:30 AM ( Note: the time zone is set based on the locale set in Magento at the default configuration scope). Change Delivery Schedule of Bazaarvoice Feeds The code below is an excerpt from the extension where the feed delivery schedule is set. This timing can be modified if need be. You should be mindful of the time of day feeds are processed daily at Bazaarvoice so that you are not behind schedule. The time zone is determined by the locale set in Magento at the default configuration scope. The format used is a standard cron expression. See this article for details: org/wiki/cron <config xmlns: xsi =" xsi:nonamespaceschemalocation ="urn:magento:module:magento_cron:etc/crontab.xsd" > <group id ="default" > <job name ="bazaarvoice_send_orders" instance ="Bazaarvoice\Connector\Model\Cron" method ="sendpurchasefeed" > <schedule> 30 2 * * 6 </schedule> <!-- Every Saturday at 2:30 AM --> </job> <job name ="bazaarvoice_send_products" instance ="Bazaarvoice\Connector\Model\Cron" method ="sendproductfeed" > <schedule> 0 1 * * * </schedule> <!-- Every day at 1:00 AM --> Bazaarvoice 22

24 </job> </group> </config> Appendix C: Troubleshooting Contact Bazaarvoice for Support Contact Bazaarvoice Support ( ) if you have issues installing or configuring the extension. It is helpful to provide Magento Admin panel credentials and SSH access for Bazaarvoice to efficiently provide support. Bazaarvoice Logging All logging form the Bazaarvoice Connector can be found in the standard Magento log directory as bazaarvoice.log Verify Magento Cron is Running To ensure the Magento cron job is running you can run crontab -l (the -l is to list the cron jobs that are running.) from the command line. Typically the job is scheduled as the web server user, but could vary depending on your hosting environment. If you are unsure contact your system administrator or hosting company. Manually Running Feeds Via Magento Admin From the Magento Admin navigate to Stores > Configuration > General > Bazaarvoice > Feeds and click the button to generate either the Product or Purchase feed. Via command line 1. Log into the magento server with SSH 2. From the Magento root folder run one of the following php bin/magento bv:product php bin/magento bv:purchase Bazaarvoice 23

25 Appendix D: Migrating to Production Steps for Testing Integration in Staging 1. Log in to Magento Admin 2. Make sure the Bazaarvoice Environment config is set to Staging 3. Follow this Implementation Guide to complete the integration with Bazaarvoice 4. Confirm with the Bazaarvoice team that integration is functioning properly (e.g. product feed is received by BV, product and category pages properly display BV content, etc.) Before Launch on Production 1. Staging environment database should be updated from production 2. Setup local host entries to point production domain to the staging Magento site 3. Make sure Bazaarvoice configuration is complete, and pointed to the production Bazaarvoice environment 4. Generate a product feed, and ensure it is successfully delivered to Bazaarvoice 5. Set Bazaarvoice environment config back to staging 6. Return base urls to the appropriate staging environment urls 7. Remove your local host entries Steps to Move from Staging to Production 1. Following your procedures release the code to your production environment 2. Make sure caches are cleared, etc 3. Duplicate configuration steps from staging environment making sure environment is set to production Bazaarvoice 24

26 Version History Version Release Date Changes /13/2017 Merge pull request for setting area code during setup /28/2017 MGP Update Product Feed Schema from 5.6 to 14.4 MGP Allow multiple UPC s, EAN s, Model Numbers, Manufacturer Part Numbers, ISBNS /10/17 Add check to setup script for area code /19/16 Initial release of Magento 2 extension Bazaarvoice 25

27 Bazaarvoice Inc Stonelake Blvd. Austin, TX Tel (toll-free): (866) Tel (toll): (512) Bazaarvoice 26