Mastering Adobe Analytics s.Product Syntax

November 20, 2019Brent Scheffer

Adobe Analytics is one of the more difficult analytics tools to properly implement. It has many custom settings, variables, and syntaxes to follow in order to properly track a site. Adobe Analytics s.products syntax is perhaps the trickiest one to get right. It’s with this variable where you pass information about your products: the SKU, the quantity of products sold, the total price of the products, taxes, shipping costs, and potentially a lot of other data.

The structure of Adobe s.products is very particular. It relies on semicolons, pipes, and commas as delimiters. Use the wrong one — or use too many, or too few — and your reports will be in bad shape. I’m sure that if the folks at Adobe re-built s.products today, they would go with an easier to use syntax for sending in the product data, such as an object.

I’ve written code that takes the guesswork out of when to use a comma (,), a semi-colon (;), or a pipe (|) and allows you to easily map your site’s data layer values directly to the s.products variable.

“The s.products variable may be the most syntactically complex variable used by data collection. Commas, semi-colons, pipes, and equal signs all play specific roles in the variable. …Mistakes in implementation of this variable are understandable, but unfortunately for developers, s.products is often a site’s most important variable because it makes possible the tracking of revenue, units, product names, and so forth” — Adobe Analytics Team

The Challenge of Adobe Analytics s.Products Syntax

The Adobe Analytics s.products syntax has been written about since Omniture released SiteCatalyst, and it still garners new authors today in Adobe Analytics. Perform a Google search on “adobe analytics s.products syntax” and you’ll have plenty of reading material. I won’t be rehashing what others have written on the subject, but it’s important to know the Adobe Analytics implementation best practices when it comes to setting the variable. Here’s s.products syntax for one product.

Category;Product;Quantity;Price;eventN=X[|eventN2=X2];eVarN=merch_category[|eVarN2=merch_category2]

Multiple products get even more confusing to read if you’re using most of the values. You use the same format as above and separate each product by a comma:

Category;Product1;Quantity1;Price1;eventN=X[|eventN2=X2];eVarN=merch_category[|eVarN2=merch_category2],Category;Product2;Quantity2;Price2;eventN=X[|eventN2=X2];eVarN=merch_category[|eVarN2=merch_category2],etc…

It’s pretty easy to see how properly managing and setting this variable can cause implementers nightmares when they inevitably drop or add a delimiter and cause revenue recognition to be inaccurate when reporting to the CMO.

Note: The leading value in the product string syntax is Category. This value has been deprecated and replaced with Classifications for grouping product SKU data in the reports. Although it has been deprecated, you must still account for the presence of the value by leaving a leading semicolon when you code s.products. That being said, this code does NOT support adding Category to s.products.

Common Mistakes with Adobe Analytics s.Products Syntax

Let’s go over some of the more common syntax mistakes that are made when setting Adobe Analytics s.products, so you can avoid these issues in the future:

Too Few or Too Many Semicolons

The first issue most Adobe Analytics implementors run into is using the incorrect number of semicolons. When you set s.products, you must follow the defined format for Adobe analytics implementation. For instance, sometimes you need to set s.products without a quantity or price, but you also need to set either an increment event, a merchandising eVar, or both. If you use the wrong number of semicolons, your reports will be garbled at best. In the example below, the correct number of semicolons after the product SKU but before the success event is three.

Switching the Location of Merchandising Events and Merchandising eVars

Merchandising events and eVars (custom conversion variables) allow you to specifically set certain event/eVar values to individual product SKUs without having to allocate those values to everything else. Swapping the location of events and eVars is easy to do because there’s no rhyme or reason to their order. Personally, I thought “evar” comes before “event” alphabetically, so naturally eVars come before events, but actually that would be wrong and leads to bad data. Correct syntax has the events in slot five and eVars in slot six of the s.products syntax.

Delimiting eVars and Events with A Pipe (|) Instead of a Semicolon

Like all other product string values, incrementor events and merchandising eVars are separated with a semicolon. However, unlike other values, the latter can contain multiple delimited values within each slot. You may set more than one merchandising event or merchandising eVar in their proper slot. To do this, delimit multiple eVars and/or events with a pipe.

More Easily Build the Adobe Analytics Products Variables

The following sections contain the code, how to use it, and a real-world use case:

Download the Code

Here is the code that is needed to make this solution work. Download the code HERE.

This code has been thoroughly tested, but you’ll want to do your own testing. You’ll take full responsibility for its use.

Requirements

You must meet certain requirements before using this code. Your site must reference Adobe Analytics via the ‘s’ object and must be able to provide this code with the product data to use for setting your s.products variable.

How the Code is Used

1. The code is written as an Adobe plugin, so the Adobe “s” object must exist before you run it. Also, the “s” object must be available where you run it. You’ll want to place the plugin in the same location as your other Adobe plugins.

2. The code needs a variable to contain the results of s.buildProducts(). In the examples below, that variable is called finalProductString. The finalProductString variable is what you’ll want to set to s.products. (i.e., s.products = finalProductString)

3. Next, you’ll need to map the values from your site’s data to the variables in the code. Whether you’re tracking a single product or multiple products, the next part is the same.

1. My plugin contains an object called “s.oProduct”. Create a new s.oProduct instance for each product you want to add to s.products. All of the parameters below are optional when creating s.oProduct.
   1. newProduct = new s.oProduct (<sku>, <quantity>, <unit price>);
      1. <sku> = the product’s SKU (required)
      2. <quantity> = # of item purchased (optional)
      3. <unit price> = Our code wants the unit price. Do NOT send the total price. Our code will take the quantity you provide, multiply it by the unit price, and will show the total price in s.products. (optional)
      4. If you’re not on the purchase page, you can either not pass <quantity> or <unit price> or you can pass those parameters as empty strings; either is fine.
2. If applicable, set any merchandising eVars for that product
   1. Syntax: newProduct.add(“<evar variable>”, <evar value>);
      1. Make certain your <evar value> does not contain a comma, semicolon, or pipe.
      2. Ex: newProduct.add(“evar10”,<evar10 value>);
3. Set any incrementor events for that product
   1. Syntax: newProduct.add(“<event variable>”, <event value>);
      1. Make certain your <event value> does not contain a comma, semi-colon, or pipe.
      2. Ex: newProduct.add(“event7”,<event7 value>);

4. You add the current product to s.products by calling
a.productArray.push(newProduct);
<newProduct> is the new product you’d like to add

An Example Scenario Where This Code Could Be Used

Let’s look at an example of how we might use this code on the typical pages in a checkout flow.

Suppose you have a company that sells clothing. I’d like to track the following:

1. The SKUs of the products (set in products)
2. The Quantity of the products sold (set in products)
3. The Total Price of the product sold (set in products)
4. A product badge (set in eVar4)
5. The Avg Rating of the Product by customers (set in eVar5)
6. The # of Reviews for each product (set in eVar6)
7. If there was a product discount (set in event7)

Product Detail Page

On this page, there’s only one product. I want to know the SKU of the product, as well as the product badge, which is a graphic I show to drive product sales. (Example values are: “Hot!,” “10% Off,” and “Best Selling!”) I also want to know the average rating of the product by customers (ratingAvg) and the number of customer reviews (ratingCount).

Example: Product Detail Page

The Final Value of s.Products

“;889588698317;;;;eVar4=hot!|eVar5=4.7|eVar6=125”

Example: Add To Cart

Adding the product from the previous PDP page we only need the product id.

Example: Example: Add To Cart

The Final Value of s.Products

“;889588698317”

Example: Cart Page

Example: Cart Page

The Final Value of s.Products

“;889588698317,;51511123”

Example: Purchase/Order Confirmation

Example: Purchase/Order Confirmation

The Final Value of s.Products

“;889588698317;3;177;event7=5,;51511123;2;150,;7961231251;1;98”

Conclusion

As you can see, the Adobe Analytics product variables syntax can be problematic. It’s easy to make a mistake when creating s.products. Hopefully, by using this Adobe plugin, your s.products will be syntactically perfect.

About the Author

Brent Scheffer

Brent Scheffer is a Senior Analytics Implementation Consultant at Blast. He is an analytics technologist, experienced in the implementation, maintenance, and creation of complex analytics solutions. A creative and dynamic thinker, Brent has a proven track record of providing business intelligence and analytics solutions for various organizations, including numerous Fortune 1000 companies.

Connect with Brent on LinkedIn. Brent Scheffer has written 1 posts on the Blast Digital Customer Experience and Analytics Blog.