.. |searchbox| image:: img/searchbox.png
:alt: Searchbox Tracking
.. |searchbutton| image:: img/searchbutton.png
:alt: Searchbutton Tracking
.. |resultCount| image:: img/resultCount.png
:alt: Result Count Tracking
.. |basketPDP| image:: img/basketPDP.png
:alt: Add to basket PDP Tracking
.. |basketPLP| image:: img/basketPLP.png
:alt: Add to basket PLP Tracking
.. |checkout| image:: img/checkout.png
:alt: Checkout Tracking
.. |product| image:: img/product.png
:alt: Product Tracking
.. |suggest| image:: img/suggest.png
:alt: Suggest Tracking
.. |associatedProduct| image:: img/associatedProduct.png
:alt: Associated Product Tracking
.. |redirectSubSelector| image:: img/redirectSubSelectors.png
:alt: Tracking Redirects
.. _search-collector: https://github.com/searchhub/search-collector
Search Collector
================
Introduction
############
To gather the required tracking data, searchHub provides a customized script, that is based on the open-source search-collector_ tracking library.
It scans the HTML DOM to gather search-related data and user events.
To integrate the tracking, only a couple of HTML attributes have to be attached to your page. The remaining search-collector implementation is done by searchHub.
.. note::
Our tracking script is capable of reading javascript objects to obtain the necessary data.
To find out more about tracking customizations, just contact us directly or look for a hint in the documentation.
..
TODO mention the sr is the foundation
User Story
##########
**searchHub Search Collector Integration**
Story
As a search-manager, I want searchHub to track the search related actions visitors do in our shop, so that I gain insights of search problems
and know about the optimization potential.
Acceptance criteria
- search related DOM elements are extended with according data-attributes as described at ``https://docs.searchhub.io/search-collector.html``.
- Embed the provided script into the shop, bound to the cookie compliance.
- When the required cookies are accepted, the script from ``c.searchhub.io`` is loaded.
- Search related events (e.g. typing something in the search box) cause requests to ``p.searchhub.io``
Technical hint
- The provided script is already adjusted by searchHub to the according shop.
- The data-attributes make sure, the tracking is immune to changes at the style or site structure.
- Single problems with some tracking events will be reported by searchHub and might need some more adjustment in the shop.
Rule of Thumb
#############
*If you are not sure which HTML element exactly to put the data-attribute on, using the elements you use for specific user events is a good rule of thumb.*
*E.g. if your click listener for the search button is attached to an HTML button element, you should add the corresponding collector HTML attribute to that button element.*
Script
######
Include your searchHub tracking snippet on every page in your shop like:
.. code-block:: html
Replace the ``{SCRIPT_ID}`` with the unique script id searchHub provided for you. The script will automatically load and execute. Please do not confuse the ``SCRIPT_ID`` with the searchHub api key. If you do not have the ``SCRIPT_ID`` please contact your searchHub representative.
Integration
################
Search box
------------------------------
The ``searchbox`` is used to perform text-based queries. In most cases, the ``searchbox`` is an HTML input element.
|searchbox|
.. list-table:: data-attributes
:widths: 50 50
:header-rows: 1
* - Name
- Value
* - data-track-id (required)
- searchBox
**Example**
.. code-block:: html
Search button
---------------------------------
The ``searchbutton`` is used to trigger a search.
|searchbutton|
.. list-table:: data-attributes
:widths: 50 50
:header-rows: 1
* - Name
- Value
* - data-track-id (required)
- searchButton
**Example**
.. code-block:: html
Suggest (search terms)
----------------------------
If search terms are proposed to the shop user while typing, each element containing keywords should be annotated with the ``data-track-id="suggestSearchTerm"`` attribute.
|suggest|
.. list-table:: data-attributes
:widths: 50 50
:header-rows: 1
* - Name
- Value
* - data-track-id (required)
- suggestSearchTerm
**Example**
.. code-block:: html
...
Jeans
Jeans Jackets
...
Result Count
---------------------------------
The writeResult count is the number of products found for the current search (**not** the number of products displayed on the current page). This is usually a somewhat higher number like hundreds or even thousands.
|resultCount|
.. list-table:: data-attributes
:widths: 50 50
:header-rows: 1
* - Name
- Value
* - data-track-id (required)
- resultCountContainer
**Example**
.. code-block:: html
Your search for jeans produced
9 results
Products
----------------------------
A product representation for the current search writeResult. The attributes here include a ``priceContainer`` in addition, the tracking script will automatically strip the non-numeric characters.
The value for the ``data-product-id`` attribute has to be an ID that uniquely identifies the product.
In B2B exist more edge cases. E.g. a certain SKU of the product family is used to represent the product group or family.
In such cases, it is important that the same IDs are used on the product listing page (PDP) and on the product detail page (PLP).
We recommend to use the mainId/parentId for products when possible.
|product|
.. list-table:: data-attributes
:widths: 50 50
:header-rows: 1
* - Name
- Value
* - data-track-id (required)
- product
* - data-product-id
- {mainId}
* - data-track-id
- priceContainer
.. note::
Add the `data-*` attributes on category and/or landing pages too. This way searchHub can track KPIs for queries that will trigger a redirect to specific landing pages with best selling products or a category pages instead of the PLP.
.. note::
You can omit the `data-product-id` and `data-track-id="priceContainer"` attributes if you have a javascript object that contains the required information.
E.g. the `dataLayer` object. Please contact us if you want to rely on js data.
**Example**
.. code-block:: html
...
39,99 € per unit
...
Zero Results Container
---------------------------------
The zero results container is the container that contains the text that is displayed when no products are found for the current search.
.. list-table:: data-attributes
:widths: 50 50
:header-rows: 1
* - Name
- Value
* - data-track-id (required)
- zeroResultsContainer
**Example**
.. code-block:: html
Sorry, no products could be found for your search "search phrase".
Redirects and Landing Pages
---------------------------------
When certain search queries trigger a redirect and do not land on the normal search results page, these pages often have banners or other buttons to guide the user more easily through the product assortment.
For example, if you are looking for a specific brand of clothing, the landing page might have banners for the most common categories (Training, Outdoor, Running...).
All buttons and links which lead to other pages that are associated to the initial query (or landing page) have to be labeled with attributes, in order to keep the association to the initial search query.
This can also span several pages. For example, a click on "Outdoor" can land on a subsequent page that again contains buttons and links such as "Jackets", "Bags", "Shoes" and so on.
If a subsequent page does not contain any products for the initial query, the button/link does not have to be labeled.
|redirectSubSelector|
.. list-table:: data-attributes
:widths: 50 50
:header-rows: 1
* - Name
- Value
* - data-track-id (required)
- redirectSubSelector
**Example**
.. code-block:: html
Are you interested in our products of Category A
Are you interested in our products of Category B
Are you interested in our products of Category C
Add to cart (PLP)
----------------------------
Some onlineshops allow the user to put products into basket directly from the PLP. Please add the ``data-track-id`` and ``data-product-id`` attributes to these basket buttons too.
An additional element containing the amount put into the basket can be annotated with the ``data-track-id="addToBasketQuantity"`` attribute, in most cases this is a common div, select or input element.
|basketPLP|
.. list-table:: data-attributes
:widths: 50 50
:header-rows: 1
* - Name
- Value
* - data-track-id (required)
- addToCartPLP
* - data-product-id
- {mainId}
* - data-track-id
- addToBasketQuantity
.. note::
You can omit the `data-product-id` and `data-track-id="addToBasketQuantity"` attributes if you have a javascript object that contains the required information.
E.g. the `dataLayer` object. Please contact us if you want to rely on js data.
**Example**
.. code-block:: html
Add to cart (PDP)
----------------------------
On the product detail page the ``Add to cart`` button has to be attributed with the ``data-track-id`` and ``data-product-id`` attributes.
An additional element containing the amount put into the basket can be annotated with the ``data-track-id`` attribute, in most cases this is a common div, select or input element.
|basketPDP|
.. list-table:: data-attributes
:widths: 50 50
:header-rows: 1
* - Name
- Value
* - data-track-id (required)
- addToCartPDP
* - data-product-id
- {mainId}
* - data-track-id
- addToBasketQuantity
.. note::
You can omit the `data-product-id` and `data-track-id="addToBasketQuantity"` attributes if you have a javascript object that contains the required information.
E.g. the `dataLayer` object. Please contact us if you want to rely on js data.
**Example**
.. code-block:: html
Associated Product
----------------------------
If on product detail page some associated products (recommendations, similar products and so on) are proposed to the shop
user, these products should be annotated almost the same way as products are annotated on the product listing page.
The only difference is the ``associatedProduct`` value of the ``data-track-id`` attribute.
|associatedProduct|
.. list-table:: data-attributes
:widths: 50 50
:header-rows: 1
* - Name
- Value
* - data-track-id (required)
- associatedProduct
* - data-product-id
- {mainId}
* - data-track-id
- priceContainer
.. note::
You can omit the `data-product-id` and `data-track-id="priceContainer"` attributes if you have a javascript object that contains the required information.
E.g. the `dataLayer` object. Please contact us if you want to rely on js data.
**Example**
.. code-block:: html
...
39,99 € per unit
...
Checkout
----------------------------
Checkout tracking is implemented on the very last summary page in your checkout process.
All products have to be attributed similar to the product listing page in addition to the ``"Commit and Buy"`` button which will finalize the order.
|checkout|
.. list-table:: data-attributes
:widths: 50 50
:header-rows: 1
* - Name
- Value
* - data-track-id (required)
- checkoutProduct
* - data-track-id (required)
- checkoutButton
* - data-product-id
- {mainId}
* - data-track-id
- priceContainer
* - data-track-id
- checkoutQuantityContainer
.. note::
You can omit the `data-product-id`, `data-track-id="priceContainer"` and `data-track-id="checkoutQuantity"` attributes if you have a javascript object that contains the required information.
E.g. the `dataLayer` object. Please contact us if you want to rely on js data.
**Example**
.. code-block:: html