Tagging Pages for Data Collection

The active merchandising tags are not used for web analytics reporting. They collect data that is used by your storefront for product placement and sorting search results.

You must instrument the ISML templates to enable analytics data collection. To instrument the pages, you add tags in specific places within your ISML templates to collect the data. Not all sites require all the data that can be collected, so omit any steps that are unnecessary for your site. Choose the pages to instrument carefully, because over-instrumenting pages can cause performance problems

For examples of already instrumented pages, in the latest version of Studio, select File > New > SiteGenesis Storefront Cartridges. This cartridge download includes SiteGenesis, which contains examples of already tagged pages.

To instrument your ISML templates:

Add the <isactivedatahead> Tag to templates containing HTML <head> tags.
Add the <isactivedatacontext> Tag to templates where category context is indicated.
Add <isobject> Tags to templates to capture activity related to viewing the following:
- Product details
- Product sets
- Search results
- Recommendations
Add calls to Salesforce B2C Commerce Client-Side JavaScript functions where product representations are made visible only as a result of storefront customer interaction after the page is rendered.
Validate your active data tags.

To collect active data, place the <isactivedatahead> tag in every ISML template that contains an HTML <head> tag that you want to collect the data from. ISML templates without an HTML <head> tag don't use the tag. Place the tag immediately before the closing head tag`.

The ` tag must appear:

Before any other analytic data collection ISML tags
After all references to external JavaScript libraries
In a location where <script> tags are valid

If this tag appears after any other analytic data collection ISML tags, those tags could fail to collect data. If this tag appears before any references to external JavaScript libraries, those external JavaScript libraries could become incompatible. This tag must appear where <script> tags are valid. For example, it can't be placed between two <tr> tags for rows of a table or similar structures in a page.

If the tag isn't placed in a page or isn't placed in a page correctly, the storefront customer could experience JavaScript errors. Customers could be notified of the error or the page rendering could be negatively affected.

Best Practice: Generally, always place the <isactivedatahead> tag in the <head> tags. However, if the template is used solely for a page or page set that could never have data of analytic interest, don’t add the tag.

This feature is implemented in SiteGenesis as follows:

The htmlhead.ism file references htmlhead_UI.isml via an include (<isinclude template="components/header/htmlhead_UI"/>).

The htmlhead_UI.html file contains this line: <isactivedatahead>.

To collect active data on the most specific category browsed on the page, add the <isactivedatacontext> tag to the <head> or <body> tags of site pages with valid <script> tags. The best location is wherever the category context of the site is most prominently indicated to the storefront customer. For example, breadcrumbs that are rendered that show the current category.

Best practice: Include this tag in exactly one template used to make up each HTML page. If this tag appears in multiple templates used to make up a single HTML page, the latest template takes precedence. For example, if one tag indicates the Hats category, and a later tag indicates the Socks category, the Socks category takes precedence. There is no negative effect if the tag appears in multiple templates with the same category value for the same HTML page, but it's redundant. If this tag doesn't appear in any templates that are used to make up an HTML page, no category context is associated with the page.

The specified category is also associated with data collected in the page about products.

If the categoryID attribute of ProductLineItem is set, Salesforce B2C updates the topCategoriesOrdered field with that category instead of the category specified by the isactivedatacontext tag.

The following table shows how this feature is implemented in SiteGenesis:

Template	Tag example
`components/productbreadcrumbs_left_directcategory.isml`	`<isactivedatacontext category="${category}">`
`components/productbreadcrumbs.isml`	`<isactivedatacontext category="${category}">`
`search/components/productsearchbreadcrumbs.isml`	`<isactivedatacontext category="${pdict.ProductSearchResult.category}">`

Embed the <isobject> tag in ISML templates to collect active data from customer storefront activity. This tag can appear any number of times in the same page, with no limit, but the tag must be placed where <script> tags are valid.

If the same product appears in multiple tags in the same page, for the same type of count only the first one is counted. It's unnecessary to wrap all product representations that result from searches, but product representations that aren’t wrapped are excluded from analytics collection. It's unnecessary to wrap the HTML content for every representation of every product that appears in the site. For example, it isn't always appropriate to wrap products in pages that show the contents of the cart.

Set the <isobject> tag <view> attribute to one of the following values, or data isn’t be collected.

Value	Collects	Details
detail	product views Each HTML page containing an tag with view="detail" counts as one product view for the product.	This value enables you to tag your site to collect hits on product information. The tag must be placed so that it wraps the ISML that represents the product details on a product detail page. Most sites use only one template to render product information on a product detail page. You can also tag templates that render a Quick view or show the products in a set. The tag results in an increment of the number of product views for a product. There aren’t clear rules about the number or detail type required of a product for it to count as a view instead of an impression. To make the impressions and views metrics meaningful, the views and impressions attributes must not be used interchangeably. Consider requiring the storefront customer to initiate an action to get more information about a product to consider it as a view. This action can call a quick view, click to the product detail page, or click through a product set to see product details.
none	Each HTML page containing an tag with view="recommendations" counts as one product impression for the product.	Collects search information for the storefront toolkit but doesn't count the object as a product hit for active merchandising. For example, you might want to use this for templates where no search hits are found. This attribute can be used to collect information for the Storefront Toolkit Search Information Tool even if active merchandising isn't enabled for the instance. The passed object attribute is an instance product search model object. For example,
recommendation	product impressions Each HTML page containing an tag with view="recommendations" counts as one product impression for the product.	This value enables you to tag your site to collect product recommendations hits. The tag must be placed so that it wraps the ISML that represents each product recommended to the storefront customer. Each template must wrap its recommended products in this tag, or those products are excluded from analytics collection. A site can have multiple templates that render recommendations: home page, landing pages, product detail pages, and in slots, search results, order confirmations, and cart views. If your site uses many different templates to render recommendations, create a common template that renders the product information included by these templates. Then add the tag there. You can also place the recommendation type in the pipeline dictionary or make it a module attribute. The tag increments the number of product impressions for a specified product. The tag also tracks that the product was recommended to the customer as part of the visit. The fact that it was recommended stays in effect until the customer ends the visit or completes the ordering process. The same product can only count for one product impression per page using this method. If multiple tags specify the same product, it's only counted one time.
setproduct	product impressions Each HTML page containing an tag with view="setproduct" counts as one product impression for the product.	This value enables you to tag your site to collect hits on products that are part of a product set. The tag must be placed so that it wraps the ISML that represents each product that is part of a product set. Most sites only have a few templates that render the product detail page for a product set. Each product set product detail page template must wrap each product in the set in this tag, or those products are excluded from analytics collection. As a best practice, don't include the tag unless the products in the set are represented on the page. For example, a product set is rendered in a slot among other recommended products. It isn't appropriate to add the tag for the products in the set that aren’t represented individually to the customer. When the set products are shown in greater detail, it's better to consider the product detail value. The tag increments the number of product impressions for a product. Even for a product with some representation on a page, if the page isn't intended to merchandise the product, no tag is needed. For example, a product set doesn't have its own image so the set product images appear instead. This lack of images alone isn't enough reason to tag the set products The same product can only count for one product impression per page using this method. If multiple tags specify the same product, it's only counted one time.
searchhit	product impressions Each HTML page containing an isobject tag with view="searchhit" counts as one product impression for the product.	This value enables you to tag your site to collect hits on search results. The tag must be placed so that it wraps the ISML for HTML components that represent the product: product name, image, callout, price, swatches, and other components. Use the instance type of ProductHit in the tag's attribute, when view is of type `searchhit`. For example, `ProductSearchHit` Most sites use only a single template to render products in search results. A site with different search result layouts for different categories can have multiple templates. When someone other than a storefront customer performs a search, other view values can achieve more meaningful results. For example, a search is performed using the API to determine the products to show in a slot. The product detail or recommendation view types can be a better choice, depending on how much detail is shown for the product and the merchandising intent. The tag increments the number of product impressions for the wrapped product. The same product can only count for one product impression per page using this method. If multiple tags specify the same product, it is only counted one time.

If you don't wrap a product representation in a template, the representation in that template doesn’t affect analytics data. You can place this tag anywhere an ISML template that contains a representation of a product with the intent of merchandising that product for sale. If a product representation is tagged but doesn't exactly match a view type listed previously, select the view type that best matches the intent.

The following table shows examples of the tag, and identifies the SiteGenesis templates that contain an example of the tag.

Tag Example	SiteGenesis Template
`<isobject object="${pdict.Product}" view="detail">`	`product/productdetails.isml`
`<isobject object="${pdict.Product}" view="setproduct">`	`product/producttocontentPS.isml AND product/components/bonusproduct.isml`
`<isobject object="${ProductSearchHit}" view="searchhit">`	`search/productgrid.isml`
`<isobject object="${product}" view="recommendation">`	`slots/product/product_1x4.isml`

<isobject object="${product}" view="recommendation"> does not currently aggregate data and is included for future development.

Some sites have pages that contain dynamic content that only appears to storefront customers in certain circumstances. For example, SiteGenesis features carousel widgets that cycle through several products when arrows are clicked, or rotating banners that cycle through several products over time.

If you don't use DHTML widgets in your storefront, you can ignore this topic.

If <isobject> tags are included in the ISML templates for all products in these widgets, then all products are included in the analytics collection. The products are included even if the customer never clicks in the carousel or waits long enough to cycle through the banners. Salesforce B2C Commerce provides JavaScript functions that enable you to be more precise when collecting data.

The B2C Commerce JavaScript library includes two JavaScript functions: dw.ac.capture and dw.ac.applyContext.

The dw.ac.capture function is used to collect analytics information for products that can't be guaranteed to appear. In the previous examples, the dw.ac.capture function is called in two cases. The function is called when the customer clicks an arrow to move the carousel and when the banner automatically rotates to show the next product.

Each time the dw.ac.capture function is called, analytics data is collected. If the carousel is cycled through all of its products so that when the initial product appears again, it can be counted twice. To avoid double counting, only call the capture function the first time a product appears.

The dw.ac.capture function collects the data and submits it for processing. The data can either be a single object with the product attributes listed (see following table), or an array of objects that each have these attributes.

Product attribute	Purpose	Optional
String id	The ID (SKU) of the product	Yes
String type	The type of data to collect, such as `dw.ac.EV_PRD_SEARCHHIT`

Only valid objects that have these attributes are collected. If no valid product objects are provided for collection, submission doesn't occur.

Examples:

This example is part of the app.js file in the SiteGenesis cartridge.

Arguments:

For each product specified in a call to the dw.ac.capture function, you must specify the type of event that causes the information capture. You can use the following constant values in the JavaScript library, in objects passed as arguments to the dw.ac.capture function.

Constant value	Description
`dw.ac.EV_PRD_DETAIL`	A product shown in detail, as for a product detail page
`dw.ac.EV_PRD_RECOMMENDATION`	A product shown as a recommendation to the customer
`dw.ac.EV_PRD_SEARCHHIT`	A product shown as a hit in search results
`dw.ac.EV_PRD_SETPRODUCT`	A product shown as a constituent of a product set

These constants correspond to the four values of the type attribute for the <isobject> tag.

These examples show how to use the dw.ac.capture function to track product view, search result view, and recommendations view in dhtml.

Examples:

Gathering these analytics requires that tracking is enabled during the shopper's session.

Use the dw.ac.applyContext function to change the analytics context from what is initially provided by the <isactivedatacontext> tag. For example, a rotating banner on the home page showcases a product from each top-level category of the site. If the <isactivedatacontext> tag isn't on that page, no category is associated with the representation of these products. If you want to associate a category context with each product in the banner, use the <isactivedatacontext> tag. The category provided in the tag could only be appropriate for the first product that appears in the banner. For each subsequent product to appear in the banner, call the dw.ac.applyContext function to associate a new category.

Each time the dw.ac.applyContext function is called, it affects all subsequent calls to dw.ac.capture until the next call to dw.ac.applyContext. For example, a banner cycles through products 1 through 6. Products 1 through 3 are in category A, and products 4 through 6 are in category B. You can use the <isactivedatacontext> tag or call dw.ac.applyContext to set category A before product 1 appears. This category stays in effect when the banner cycles to products 2 and 3. Because product 4 is in a different category, call dw.ac.applyContext before calling the dw.ac.capture function for product 4, to set the context to category B.

The following parameter sets the context for subsequent events that occur on the page. Call this function if automatic DHTML or customer activity changes the context of the page. This function doesn't cause data to be submitted for processing; it only changes values in the current context to be associated with data submitted later.

Configuration parameter	Purpose	Optional
String category	The ID of the category browsed on the page	Yes

Example:

For example, assume that a home page has a slot that shows the top selling product in each category in a carousel. Each time the carousel shows a new product, the context for that product is a different category. This function is called each time the carousel is scrolled, to set the appropriate category for the product now shown.

An active data integration is valid if the correct information is collected on a Production instance and retrieved on Production and Staging instances.

You can test on those instances or on other instances with an equivalent configuration. Because analytics information is only collected from the Production system, retrieved information is always identical for all instances of a site.

Use the Analytics Debugger tool to validate information that is sent from the template to Salesforce B2C Commerce. All cases of ISML tags and calls to the analytics JavaScript library must be validated to ensure they are collecting the expected data. Sample pages of the site to ensure that there are no places where tags or JavaScript calls are missing.

The Analytics Debugger (debugger) is a feature of the analytics JavaScript library. The debugger output is an alert message that shows each time information is provided to the JavaScript library for submission.

To turn on the debugger, include the following as the URL for a browser favorite or bookmark, and access that bookmark:

The debugger uses a session cookie to track that it was turned on. When it's turned on, it remains on for the rest of the browser storefront session. If the browser is closed, or the session otherwise comes to an end, it turns off automatically.

To manually turn it off, include the following as a separate bookmark:

The information in the alert messages shows exactly what is provided by the template for submission to Salesforce B2C Commerce. However, these messages don’t prove that the content was sent. If the debugger shows that information was submitted, but data was not collected, contact customer support to validate that B2C Commerce received the information.

If data collection isn't enabled for the store front, the debugger shows the message:

Analytics data collection is disabled.

If data collection is on and the debugger is enabled, navigating to a page in the storefront shows a window similar to the following: