Best-Practice Pages, Components, Types, Names & Values for Tracking
- Sylvain Paillard
As documented in the HTML markup requirements without Narrative API Response , you can track many components appearing on any page of your web-site, not only the components which are returned as part of the Boxalino Narrative API Response.
In this article, we document our Best-Practice naming for such tracking and highly recommend you to follow it as closely as possible in your integration:
Parameters conventions
We recommend to pass parameters as key values pairs (with = sign in between) and separated by the pipe sign ‘|'.
So to track something with a name ‘myname’ and two parameters: color:blue and size:big, the following string value should be used:
myname|color=blue|size=big
data-bx-narrative-type
For the type, we recommend to track the page type using the following values.
We indicated the Customer Journey Step as per our definition: Widget & Page Optimizers (WPO)
type | Customer Journey Step | description | parameters |
|---|---|---|---|
home | WELCOME | The home page of the web-site | typically none, but if you have several versions, you can indicate it in
|
campaign-global | WELCOME | A marketing campaign page which is not related to or presenting a specific part of your sortiment | the campaign name, id (and other parameters if applicable):
|
top-category | CONSIDERATION* | A top-level category page which is not showing primarily a listing of products | typically none, as the category id should be set as data-bx-narrative-field & |
category | CONSIDERATION* | A category page showing a listing of products | |
autocomplete | CONSIDERATION* | A Search autocompletion (appears while you type) | |
search | CONSIDERATION* | A search page | |
finder | CONSIDERATION* | A product quick finder page | |
brand | CONSIDERATION* | A brand page | |
topic | CONSIDERATION* | A topic page | |
campaign-list | CONSIDERATION* | A marketing campaign page which is related to and/or present a specific listing of products | |
listing | CONSIDERATION* | Any other product listing pages | |
content-listing | CONSIDERATION* | A content list page | |
pdp | EVALUATION | the product detail page | typically none, as the current product id should be set as data-bx-narrative-field & |
blog | EVALUATION | a content page of the type blog | typically none, as the current content id should be set as data-bx-narrative-field & |
magazin | EVALUATION | a content page of the type magazin | |
campaign-item | EVALUATION | a content page of the type campaign | |
content-item | EVALUATION | any other content page | |
basket | PURCHASE | the basket page or the basket overlay | if an overlay, indicate it with
|
checkout | PURCHASE | the checkout page | the checkout process step
|
account | LOYALTY | the account page | the section of the account
|
* for the cases of CONSIDERATION, as they are becoming quickly complicated, it is advised to consider using the Boxalino Narrative API as early as possible as this will make the tracking much simpler as it is all automated by the Boxalino Narrative API response. Adding elements in Boxalino there will be automatically tracked in the proper way without additional efforts on your side.
data-bx-narrative-field & data-bx-narrative-value
You should indicate here the context of the page in a way which is directly compliant with the data you export to Boxalino.
For example, you are in on a product page for the product sku = 123 and you export the value “123” in to boxalino as sku value in your “doc_product” export, then you should set these parameters accordingly:
data-bx-narrative-field='sku'
data-bx-narrative-value='123'
If possible use the standard fields as described, but if needed you can use a field any attribute you export in your doc_product data.
The same is true if you are on a category page, in such case, it is best to set the field to “category_id” and set the value as the current category_id (same for ‘brand’ and so on).
For the case of content, same thing, but of course use an standard or custom attribute name as field which you are exporting in your doc_content data.
Read more:
doc_product the export data structure of your product
doc_content the export data structure of your headless content
doc_attribute the list of standard attribute names (like ‘sku’, ‘id’, ‘external_id’ and ‘products_group_id’ which are always there when you are exporting your data to Boxalino).
data-bx-narrative-name
As you will do it anyway in your Boxalino Narrative Layout projects, we recommend you to use a component-base architecture for all visual displays of your front-end.
The main idea being to create modular front-end component which are re-used in many different places of your front-end as we document it here: Check-list: empower your Website Layout with Narratives
There you can simply indicate the name of the component and, if needed, the role it has on its page in the parameter (this is particularly useful if the same component is used several times on the same page for different reasons).
You do not need to indicate anything about the page itself, as you are already providing this information in the attribute bdata-x-narrative-type (as indicated above).
Here are a few examples.
image-slider|section=main-pdp-images
banners-slider-full-width|section=top-campaigns
data-bx-narrative-group-by & data-bx-item-id
We speak here of what qualify the visual element which is shown to the user (an image in a slider, a price, a delivery information, …)
This is the part of the tracking which is the less possible to standardize as it really depends of many aspects specific to your projects.
Typically, we recommend to leave the data-bx-narrative-group-by with it’s default value ‘id’, unless you are able to define the nature of the value in a clear name.
For example, if you are tracking as value the url of an image (because you do not have any better name/value to provide), then you can set the value of the data-bx-narrative-group-by with “src” or “url” to indicate what it is.
For the value of the data-bx-item-id istelf, we recommend to put a value which is descriptive and easy to read and to use as a group and to only put the specific value as a parameter (with the exception of a price which should be set as the numerical value of the price directly).
For example, for such a case:
we recomend a tracking like :
orange|date=17.02.22
So that you will have easily the reports on all the cases “orange” together and, only for advanced analysis can you go in the decoding and mining of the displayed date.
data-bx-variant-uuid
Typically do not set. Only if you have another tracking system and you would like to inform us of the unique identifier used in the other tracking system