This guide is for developers who want to set up data tracking using the default data layer events supported by the Frosmo Platform. If your site has or is getting a basic feature setup from Frosmo, see the appropriate site preparation guide instead. Basic feature setups rely on their own dedicated data layer events.
To use the data layer on a site, the data layer module must be enabled for the site.
For an introduction to product tracking in the Frosmo Platform, see Data tracking overview.
Tracking products with the data layer means triggering a product view event whenever a visitor navigates to a product page or otherwise views a product on a site. The data you pass in the product view event is the product data for the viewed product.
You can trigger product view events from:
- Page code (meaning directly from your site source code)
- Shared code
Page code is the recommended solution. If you cannot use the data layer in your page code, use shared code.
Figure: Tracking products by triggering a product view event from a page (click to enlarge)
When you trigger a product view event:
- If the product is not in the product database, the Frosmo Platform adds the event data to the database as a new product. The platform uses the product ID to uniquely identify the product.
- If the product is already in the product database, and if the event data differs from the product data in the database, the Frosmo Platform updates the data in the database. The platform only updates product attributes whose values differ and adds attributes that do not already exist in the database. The platform does not remove existing product attributes that are missing from the event data.
- If the product is already in the product database, and if the event data does not differ from the product data in the database, the Frosmo Platform ignores the event data.
- By default, the Frosmo Platform increments the view count for the product by one. For a newly added product, this is the first view for the product.
To check that the product data is correctly stored in the Frosmo back end, call the Product API.
Triggering product view events
To trigger a product view event, call the dataLayer.push() function with the following object:
dataLayer.push({
frosmo: {
view: {
products: [{
/* Standard attributes */
id: '<PRODUCT_ID>',
availability: '<PRODUCT_AVAILABILITY>',
brand: '<PRODUCT_BRAND>',
image: '<PRODUCT_IMAGE_URL>',
name: '<PRODUCT_NAME>',
originalPrice: <PRODUCT_ORIGINAL_PRICE> | '<PRODUCT_ORIGINAL_PRICE>',
price: <PRODUCT_CURRENT_PRICE> | '<PRODUCT_CURRENT_PRICE>',
type: '<PRODUCT_TYPE>',
url: '<PRODUCT_PAGE_URL>',
/* Custom attributes */
<key>: <value>,
...
}]
}
}
});
The product data is stored in the frosmo.view.products array of product objects. You can send the data for one or more products in a single event.
Product object
The product object contains the data (attributes) for a single product. You can define standard attributes and custom attributes for a product.
The Frosmo Platform automatically trims string values by removing opening and ending white spaces. Empty string values are valid for all string attributes except id.
Standard attributes
To get the most out of the Frosmo Platform, include as many optional standard attributes in your product data as possible.
Table: Product object properties (standard attributes)
| Property | Description | Type | Role |
|---|---|---|---|
id | Product ID. The value must be a non-empty string. | String (256) | Required |
availability | Product availability in the web store. The possible values are:
If you provide a value other than one of those listed, the data layer push fails, and no product data is updated. | String | Optional |
brand | Brand name for the product, or the company that produces the product. | String (2048) | Optional |
categories | Categories to which the product belongs. This can also be keywords, tags, types, or any other set of classifiers used on the site. You can define a hierarchy of parent and child categories as a breadcrumb using
The maximum stringified length for the array is 2048 characters. If you only need to define a single category for a product, use the If you need to define a main category and one or more additional categories for a product, use the | Array of strings (2048) | Optional |
image | Product image URL. Even if you do not have a value for this property, it is recommended that you nonetheless pass an empty string. | String (2048) | Optional |
name | Product name. Even if you do not have a value for this property, it is recommended that you nonetheless pass an empty string. | String (128) | Optional |
originalPrice | Original unit price for the product. Use this property for the original starting price before any discounts. If the value is a string that can be represented as a number, the Frosmo Platform stores the value as a number. | Number | String (2048) | Optional |
price | Current unit price for the product, such as a discount price. Even if you do not have a value for this property, it is recommended that you nonetheless pass an empty string. If the value is a string that can be represented as a number, the Frosmo Platform stores the value as a number. | Number | String (2048) | Optional |
type | Product category. This can also be a keyword, tag, type, or any other form of classification used on the site. Define a hierarchy of parent and child categories as a breadcrumb using Even if you do not have a value for this property, it is recommended that you nonetheless pass an empty string. This property can be used in segmentation rules and therefore needs to have a value. If you need to define multiple categories for a product, use the If you need to define a main category and one or more additional categories for a product, use this attribute for the main category and the | String (128) | Optional |
url | Product page URL. Even if you do not have a value for this property, it is recommended that you nonetheless pass an empty string. | String (2048) | Optional |
Custom attributes
If the standard attributes are not sufficient to track your product data, define the necessary custom attributes to complement the standard ones. You can freely define as many custom attributes as you need for your products.
A custom attribute must meet the following requirements:
- The attribute name must be a string with a maximum length of 32 characters.
- The data type of the attribute value must be one of the following:
- Array
- Boolean
- Number
- Object
- String
- The attribute value can also be
null.
If the custom attribute is an object, the object properties can be anything you want them to be. The Frosmo Platform does not validate the properties against any data model or schema.
You cannot filter recommendation data by object properties. If you want to use a custom attribute for filtering recommendations, use one of the other supported data types.
Product object examples
Retail
iGaming
Testing product tracking
To test that products are correctly tracked with the data layer:
- Go to the site.
- Launch Frosmo Preview.
Select Advanced > Events.
Go to a page where products are tracked. If product view events are successfully triggered with the data layer, Frosmo Preview shows the following messages for each event:
product(contains the product data parsed from a single product object)dataLayer(contains the object passed to the data layer)trigger.event(contains information about the triggered event, including the object passed to the data layer)
Product view events log a dedicated
productmessage for each product object in thefrosmo.view.productsarray.To verify that the correct product data was sent, check the
dataLayermessage.
If you want more details on a data layer call, select the Advanced > Requests view in Frosmo Preview, and check the
setProductDatarequest to the Optimizer API.
Triggering product view events (deprecated method)
Do not use this method if you are preparing a site for integration with the Frosmo Platform.
This section documents the legacy method for tracking products with the data layer. This method is officially deprecated. If your site still uses this method, it is recommended that you migrate to the current solution. Contact Frosmo support to discuss the migration.
Checking that the product data is in the Frosmo back end
If you want to verify that the product data you're tracking is correctly stored in the Frosmo back end, try retrieving the data with the Product API.
The Product API nests all product attributes inside the attributes property, except for id, name, and type, which are returned in the product object root.
