Salesforce Commerce Cloud - SFRA & SiteGenesis

Installing the Pixlee Salesforce Commerce Cloud Cartridge

This article explains how to install Pixlee extension module (cartridge) on web stores built on top of Salesforce Commerce Cloud (SFCC) B2C platform.

SFCC presently provides two reference applications to be used as starting points for building client stores:

• Storefront Reference Architecture (SFRA)
• Site Genesis

Pixlee SFCC cartridge supports both these applications, details on how it can be installed for both are provided below.

Before you begin

Pixlee account setup

To take advantage of services provided by Pixlee, you first need to sign up for Pixlee account. You can start with requesting a demo or contacting Pixlee directly.

Getting your Pixlee Account ID and API keys

Once you have an account, you will be able to look up your Account ID and API keys (Account API Key and the Account Secret Key) required for connecting your store to Pixlee services.
Please refer to Getting your API Keys for more details as to how to obtain those keys.

Configuring your widgets

The cartridge allows Pixlee widgets (a.k.a. displays) to appear on storefront pages like product details and category landing. Those widgets allow moderated content collected from social media or manually uploaded, related to your products or navigation categories, to be presented to your web site visitors. The visitors can also share or upload their own content straight from the site.

Pixlee widgets can be created and configured in Pixlee Admin, the configuration allowing to control their appearance and behavior.

As per your needs, configure two such widgets – one for product detail page and another one for category landing page (the widgets will automatically pick the relevant content to show for each product or category).

To configure your widgets:

1. Go to https://www.pixlee.com, log in, and navigate to the Publish tab. Alternatively, point your browser to https://app.pixlee.com/app#publish while logged in.

2. Click the Install Product Displays and it should present you with a lightbox that looks like following.

3. Customize the widget as you wish and click Save.

4. Take note of the widget ID. This number we be need in one of the later steps.

Repeat the steps 1-4 and generate your second widget for category landing pages.

Deploy Pixlee cartridge to your SFCC environment

Getting the cartridge

The Pixlee SFCC SFRA cartridge is available by downloading Pixlee_SFCC_SFRA.zip

The repository (or zip file) has three top-level folders:

• cartridges
• documentation
• metadata

Updating the metadata

The first thing we need to do when deploying the cartridge is to update the metadata of your SFCC environment. This metadata update includes:

• Extensions to SFCC systems objects (site and organization preferences)
• Service definition
• Two sample jobs

The easiest way to update the metadata of your environment with the above is to do a site import. For that purpose:

1. Open the metadata folder and create a zip of its pixlee_site_template subfolder:
   Please make sure the zip file has the same name as that folder:

2. In your SFCC Business Manager, navigate to Administration > Site Development > Site Import & Export:

3. Click Choose File, select the zip you created in the previous step, and then click Upload. Once upload completes, you should be able to see the zip file in the list of availabel imports:

📘

NOTE:

The label of Choose File button can be different depending on your browser

4. Select the zip file from the list of available site imports and click Import, and then click OK to confirm.

5. Wait for the import job to finish, it should take less than a minute.

In case the import was successful, you should be able to see the following:

• Pixlee site preferences in Merchant Tools > Site Preferences > Custom Preferences.
• Pixlee Organization preferences in Administration > Global Preferences > Global Custom Preferences.
• Pixlee service definition (pixlee.http.service) in Administration > Operations > Services.
• Two sample jobs (Pixlee Product Export – SFRA and Pixlee Product Export – SiteGenesis) in Administration > Operations > Jobs.

Building and deploying the code

To make your store application take advantage of Pixlee services, we need to make sure that the cartridge code is built and deployed (uploaded) to your SFCC environment. This process is different depending on the reference application your store is built upon, so a separate set of instructions will be given for SFRA and Site Genesis.

SFRA

The SFRA version of Pixlee cartridge is designed around the same build and deployment concepts as the SFRA core cartridges and plugins provided by Salesforce.

1. In the root folder of your cloned repository, run npm install to install all of the local dependencies (node version 8.x or current LTS release recommended)

2. If necessary, update the path to your base SFRA installation in package.json file from the same root folder.

Normally you would have a top-level project folder, into which the repositories of SFRA base cartridge and all required plugins, libraries and any other LINK cartridges will be cloned. In case you have cloned the Pixlee cartridge into that folder as well, the below change will not be required. Otherwise, update paths.base property in the package.json to contain a relative path to the local directory containing the Storefront Reference Architecture repository. Its default value will be as follows:

"paths": {
    "base": "../storefront-reference-architecture/cartridges/app_storefront_base/"
}

3. Once you are certain the correct path to SFRA cartidges is configured, run npm run compile:js command from the root folder of Pixlee repository.

4. Finally, having downloaded all local resources and having compiled the script files, we can upload the code to our SFCC environment (sandbox). That can be done from the command line as well, for which purpose a file called dw.json needs to be created in the root folder of Pixlee repository. It should have the folliwing content:

   {
   "hostname": "{{your-sandbox-hostname}}.demandware.net",
   "username": "{{your_login}}",
   "password": "{{your_pwd}}",
   "code-version": "{{version_to_upload_to}}"
   }

Once you have the file in place, run npm run uploadCartridge command. Make sure it uploads the two cartidges (int_pixlee_sfra and int_pixlee_core) required for SFRA based applications (even though uploadCartridge command sounds like a single cartridge will be uploaded, it should acutally upload those two and report so).

Site Genesis

For Site Genesis based application we will need to upload int_pixlee and int_pixlee_core cartridges as they are, no preliminary building or installing local resources will be required.

In case you are using Eclipse, make sure to import both those to your project workspace (by using File > Import > General > Existing Projects into Workspace or File > Import > Git > Projects from Git):

Make sure to select only the cartridges needed for Site Genesis but not int_pixlee_sfra (though it should not affect the application if uploaded):

Finally, make sure that both cartridges are attached to you SFCC environment:

If you are using an alternative editor or IDE, you can still use the process described for SFRA to upload the cartridges (withouth running the npm run compile:js), having first updated scripts.uploadCartridge property in package.json to include int_pixlee instead of int_pixlee_sfra:

"scripts": {
. . .
    "uploadCartridge": "sgmf-scripts --uploadCartridge int_pixlee_core && sgmf-scripts --uploadCartridge int_pixlee",
. . .
},

Having uploaded the cartridges relevant for your application in any of the ways described above, you may confirm they are present in your active code version (that should be the one you specified in dw.json file) by navigating to Administration > Site Development > Code Deployment in Business Manager and clicking on that version.

Configuring SFCC environment

Now that we have the metadata updated and code uploaded, it's time to configure our SFCC instance (sandbox).

Updating cartridge paths

We will need to add int_pixlee_core and one of the other cartridges to your cartridge path, depending on the type of reference application your store us built upon.

SFRA

For SFRA based applications, add the following to your cartridge path:

int_pixlee_sfra:int_pixlee_core

Note that with SFRA based applications custom cartridges should be added to the left of the base SFRA cartridge but to the right of the custom cartridge containing the customization for the specific project or client. For example, your effective cartridge path may look as follows:

app_client:int_pixlee_sfra:int_pixlee_core:app_storefront_base:modules

Site Genesis

For SiteGenesis based stores, add the following cartridges:

int_pixlee:int_pixlee_core

Unlike SFRA, for SiteGenesis based applications project or client specific customization should have been made to the SiteGenesis cartridges themselves, so Pixlee cartridges should be to the right of those. For example, your cartridge path may look as follows:

cleint_sitegenesis_controllers:client_sitegenesis_core:int_pixlee:int_pixlee_core

To update cartridge path:

1. Navigate to Administration > Sites > Manage Sites, and click on the name of the site cartridge path of which you want to update.

2. Click on Settings tab and make the required changes to the Cartridges field, and then click Apply:

📘

NOTE:

Please make sure all cartridge names are properly delimited by colons (:)

Configuring Site Preferences

To configure the site preferences for your site, select that site in Business Manager, navigate to Merchant Tools > Site Preferences > Custom Preferences and select Pixlee:

The following table lists the site preferences that we need to configure:

Enable Pixlee Plugin is there to control whether the functionality provided by the cartridge is available on the storefront for a site.

Account ID, Pixlee API Key and Pixlee Secret Key should be populated with the corresponding details from Profile Settings > API Credentials, as described in the earlier section of this article. These credentials can be accessed directly by following this URL while logged in to Pixlee Admin: https://app.pixlee.com/app#settings/pixlee_api

SKU Reference is a setting to control which SFCC product attribute should be used to retrieve product IDs to be reported to Pixlee. The two options are:

• Product ID - this is the default option, in which case ID system attribute of Product system object will be used.
• Manufacturer SKU - an alternative options, allowing the value of manufacturerSKU system attribute of Product system object to be used.

Custom Product Host allows the hostnames of PDP URLs to be replaced when products are exported to Pixlee by the means of Pixlee Product Export job. If left empty, the hostname will not be replaced. If populated, the entered hostname will replace the one configured in SFCC. For example, if www.example.com is set, the following PDP URL

http://pixlee-test-sandbox-dw.demandware.net/s/SiteGenesis/demandware-mens-yarmouth-gloves/TG786.html?lang=en_US

will be changed to

http://www.example.com/s/SiteGenesis/demandware-mens-yarmouth-gloves/TG786.html?lang=en_US

PDP Widget ID and CLP Widget ID should be populated with the IDs of the widgets you want to show on product details and category landing pages respectively, steps on how to retrieve these values were covered earlier in this guide in the Configuring your widgets section.

Tracking option allows controlling the tracking behavior of the Pixlee cartridge. The cartridge contains some logic to fire events to Pixlee every time a product is added to cart, and when an order is finally placed. In addition to that, the scripts loaded from Pixlee and the widgets provided by Pixlee to be embedded on product details and category landing pages come with their own tracking functionality.

Both SFRA and Site Genesis reference applications include some logic to obtain consent from the customer to be tracked each time a new session is initiated, for which purpose a popup like this is shown:

The Tracking option setting allows the behaviour of both the cartridge, Pixlee scripts and widgets tracking to be controlled and aligned with the consent given by the customer. The available options are:

• Always track (TRACK_ALWAYS) - in this case tracking will always be enbled, no matter if customers have given consent or not. This is the default option, replicating the behaviour of the previous version of the cartridge.
• Track except if customer explicitly opted out (TRACK_IF_NOT_OPTED_OUT) - in this case the customers will be tracked until they explicitly indicate they do not want to be tracked (like by clicking the No button on the above popup). For example, this option allows customers to be tracked on the first page they open, on which the tracking consent popup is shown.
• Track only if customer explicilty opted in (TRACK_IF_OPTED_IN) - in this case customers will not be tracked until the explicitly give their consent (like by clicking Yes button on the above popup). For example, with this option customers will surely not be tracked on the first page they visit, on which the tracking consent popup is shown.
• Disable tracking (TRACK_NEVER) - this is the most restrictive option, with which customers will never be tracked no matter of their consent. It is intended to be used for test purposes only, on non-production environments.

📘

Organization preferences

Even though there are two organization preferences defined by Pixlee cartridge, there is no need to set any of them, both will be automatically populated by the cartridge setup or job execution.

Configuring Jobs

The first thing you would do in order to start using Pixlee widgets on your store is to let Pixlee know of the products you are selling. The product infomation is to be communicated offline, by the means of a job.

Pixlee SFCC cartridge provides a job step called custom.PixleeExportProducts allowing products from a single or multiple sites to be exported at once. The follwing table lists the configuration parameters:

Products Source alows the source of the product to be exported to Pixlee. It has the following options:

• CATALOG_API - this is the default option, which replicates the behaviour of the previous version of Pixlee cartridge. If selected, dw.catalog.ProductMgr.queryAllSiteProducts() API will be used to retrive the products.

• SEARCH_INDEX - this option is considered to provide better performance and guarantees that only products showing on the site will be exported. It will use ProductSearchModel related APIs.

Images View Type allows the view type of the product images, URLs for which will be included in the export to Pixlee, to be specified. Its default value is large. It should have one of the values defined in Image Settings of the master catalog.

Main site ID should contain the ID of the site for which full product details should be exported. It could be usefull in situations where you have multiple sites in SFCC sharing the same products. For example, let's consider you have a US site in English, a Canadian site in English and French, and a Mexican site in Spanish, all using products from the same master catalog. In this case you will want to nominate one of those sites as a main one, let's assume that would be the US site. With that configuration, having the job step set to run for all 3 sites, it will export full product details (including main PDP and image URLs, price in USD) and US English regional details for the US site, and only regional details (including localized PDP and image URLs) in Canadian French and English for Canada site and Spanish for Mexico site.

On the other hand, you may have multiple different brand sites each using a different set of products running on the same SFCC environment. In that case you would not want to nominate any of those sites as main, so in order to properly export the products to Pixlee a separate jobs using the same job step component should be configured.

The cartridge comes with two sample jobs like that, one for SFRA (RefArch) and another one for Site Genesis. You may adjust them to the way that suits your needs, or remove and set up your own job.

Break After is a setting that can be used for testing and debugging the job with a large number of products. In general, if an export for a prodcut fails, the failure will be logged, but the job will continue and try to export the next product (though it will finally end with an error). If you have a large number of products in the catalog though (say 100,000) and for some reason exporting each prodcuct results in an error, you may prefer to stop the job after a number of consecutive fails. The default value is NEVER, which means that the job will never stop even if the export of each product fails, and that is the one to be used in Production environments.

Test Product ID is another attribute that should be used only during testing or debugging the job. If set, it will look up the product for the ID specified and only export that product. If no such product exists, nothing will be exported. If left bank, which should be the default value and the value for Production environment, all prodcts will be exported.

To configure your jobs navigate to Administration > Operations > Jobs.

The following screenshot shows the example job step configuration for SFRA sites (RefArch and RefArchGlobal):

Site assignments of that step are illustrated on the following screenshot:

Updating your SFCC application

Depending on your application, some changes to its modules and components might be required to make Pixlee services function properly.

SFRA

In an ideal scenario where you only have SFRA base cartridge and Pixlee cartridge installed, there is no need to make any changes to your application, the functionality provided by the cartridge will be available immediately after the cartridge is build and deployed as described above.

In real world there be lots of other 3rd party crtridges and plugins which may override the same components as the ones in Pixlee SFRA cartridge (int_pixlee_sfra). In that case you will need to merge changes from all those cartridges and plugins following the guidelines from this example repository provided by Salesforce:
https://github.com/SalesforceCommerceCloud/plugin_cartridge_merge

Also, in case you override any of the templates that int_pixlee_sfra cartridge overrides (that would be the ones outside of pixlee folder), please make sure you port the changes from Pixlee cartridge into your client cartidge. All such changes should be wrapped in comments as follows:

<iscomment>Pixlee changes BEGIN</iscomment>
<isinclude template="pixlee/widgets/pdp" />
<iscomment>Pixlee changes END</iscomment>

Site Genesis

As mentioned earlier, with Site Genesis based applications your client cartridges will very likely appear to the left of Pixlee cartridge in the cartridge path. Because of that changes will have to be made to some of the components in your client code. These will include changes to isml templates, and some changes to models or pipelines depending on whether you are using JavaScript controllers or pipelines.

Changes to templates

1. Add the folowing lines to the very end of your checkout/cart/minicart.isml template:

   Pixlee changes BEGIN
   
   Pixlee changes END

2. Add the following lines to the end of your checkout/confirmation/confirmation.isml template, just above :

   Pixlee changes BEGIN
   
   Pixlee changes END

3. Add the folowing lines to the very end of your components/footer/footer_UI.isml template

   Pixlee changes BEGIN
   
   Pixlee changes END

4. Add the following lines to the end of your product/productdetail.isml template, just above the closing div tag for pdpMain container:

   Pixlee changes BEGIN
   
   Pixlee changes END

5. Add the following lines to the end of your rendering/category/catlanding.isml template

   Pixlee changes BEGIN
   
   Pixlee changes END

Changes to JavaScript controllers based Site Genesis applications

📘

NOTE

This change is required to allow add to cart events to be triggered from wishlist page. In case wishlists are not in use on your store, there will be no need to apply it.

In you scripts/models/CartModel.js, add the following lines to addProductToCart function, in the condition handling the case for product addition from list (around line #100):

// Pixlee changes BEGIN
var eventsHelper = require('int_pixlee/cartridge/scripts/pixlee/helpers/eventsHelper');
eventsHelper.processAddProductListItem(productList.getItem(params.itemid.stringValue), params.Quantity.stringValue);
// Pixlee changes END

Changes to pipelines based Site Genesis applications

📘

NOTE

This change is required to allow add to cart events to be triggered from wishlist page. In case wishlists are not in use on your store, there will be no need to apply it.

In your Cart pipeline update Cart-AddItem subpipeline, the branch that takes care of adding products to cart from a product list, to include a call to PixleeCart-ProcessAddProductListItem just before it ends:

Testing and Troubleshooting common issues

To test that everything was implemented correctly, we need to check two things -

1. Were all the products exported?
2. Are API calls being successfully made to the Pixlee API?

Were all the products exported?

Before testing, please make sure that the Pixlee Product Exports job has at least ran once. If you've already run the exports once, skip to step 3.

1. In order to run it manually. Open Business Manager. Under Administration tab click Job Schedules link under the Operations section.

2. Check the checkbox next to Pixlee Product Exports and click Run.

3. Login to Pixlee and navigate to Products under the Album tab. Alternatively, click this link..

4. You should see a list of products on this page.

5. Try searching for a few products on this page that you know exist in your catalog.

6. In case the list is empty or you were not able to search for a particular product, proceed to the next step. Otherwise, proceed straight to the next section i.e. Are API calls being successfully made to the Pixlee API?

7. There can be several causes of failure to export products so first, we need to find out the exact cause of the failure. The Pixlee Product Exports job logs all exceptions and errors to the server logs. So the next step for us is to get the logs.

8. Open Business Manager. Under Administration tab click Job Schedules link under the Operations section. Click the Pixlee Product Exports link.

9. Click Schedule and History tab and History you'll find a summary of all the processes that ran recently.

10. Click the link to download the log file. Contact us at [email protected] and attach the log file with the email.

Are API calls being successfully made to the Pixlee API?

API calls are made to Pixlee API when a customer adds something to their cart and when they buy something on your store. We need to make sure that these calls are being made at the right time.

We recommend using Google Chrome for the next steps. But feel to apply the same steps to any other browser of your choice.

1. Open a product page of your store.

2. Open Chrome Developer Tools - Right click on the page anywhere and click Inspect. Alternatively, use keyboard shortcut CMD + OPTION + I ( CTRL + SHIFT + I for Windows). On the resulting menu, click the Network tab.

3. Ensure that Preserve log checkbox is checked before proceeding.

4. While keeping the Chrome Developers Tools open, switch to the product page and click Add to Cart on the product page.

5. After the product has been added to cart, switch to Chrome Developers Tools again.

6. In the Filter bar type pixlee and that should reduce the number of results. And then look for two calls named addToCart in the results.

7. If you found the addToCart calls then your analytics were integrated correctly. If not, please revisit Analytics Setup or contact us at [email protected].

8. While keeping the Chrome Developers tools open, proceed to checkout and buy the product that you added to cart previously. Use a test payment method for the checkout.

9. When you reach the order confirmation page switch back to Chrome Developers Tools. This time look for Conversion calls in the result instead of addToCart.

10. If you do not see conversion calls like in the screenshot, please revisit Analytics Setup or contact us at [email protected].