Technical Documentation for the Conversion Tracking Service

Performance

If your e-shop solution supports this implementation, we recommend first referring to its official documentation. For supported platforms, this is the most efficient approach. If you decide to proceed with a direct implementation, follow these steps:

2 Conversion Tracking Scripts

Unlike the legacy conversion tracking, which included only one tracking script on the thank you page, we are transitioning to using two scripts:

Product page code
Order confirmation page code

You can find them in the Heureka admin panel. We recommend copying the scripts directly from the admin panel and only updating the values of the relevant arguments.

Implementation via HTML

The standard procedure for properly enabling conversion tracking involves using two tracking scripts. The code for the cart utilizes the heureka() function with several arguments. The order in which this function is called does not matter, but send must be called at the very end, after all other functions.

Product Page Code

You do not need to change anything in this script.

Order Confirmation Page Code

1. E-shop Identification

By using the authenticate method, you identify your e-shop.

2. Create a New Order

By using the set_order_id method, you create a new order and set the ID assigned to it by your e-shop.

3. Add Product(s) to the Order

By using the add_product method, you add products to the order. This method will be called as many times as there are products in the order. Please do not add items like shipping, cash on delivery (COD), packaging fees, recycling fees, etc.!

4. (Optional) Add Other Non-product Items to the Order

By using the add_additional_item method, you add other non-product items such as shipping, cash on delivery, packaging fees, recycling fees, vouchers, discounts, etc., to the order. You can call it once for the total sum of all items, or separately for each individual item.

5. Set Order Value

By using set_total_vat, you set the total order price (including or excluding VAT, depending on your settings).

6. Set Currency

By using set_currency, you set the currency of the order.

We recommend sending orders already converted to the portal’s currency ('EUR' for heureka.sk, 'CZK' for heureka.cz). Otherwise, with a larger volume of data, statistics may be distorted due to currency conversion. If you still decide to send orders in different currencies, it must be one of the currencies we support (currently 40 currencies according to the European Central Bank). You can find a list of them on this page. We update exchange rates every day at midnight.

The currency must be in ISO 4217 format (e.g., CZK, EUR, USD).

If you use an unsupported currency or an invalid value, the order will be saved in the portal’s default currency, which may distort statistics.

7. Send the Order to Our Server

By using send, you confirm the entire order and send it to our server. This call must be the last one in the script.

Testing Click Identifier Passing During Order Creation

If you want to test locally whether an order will be correctly paired with a user’s click (i.e., will result in a conversion), follow the steps below:

1. Adding a Parameter to the URL

Add the parameter hgtid=test to the URL on the page where one of the tracking scripts is implemented (for example: https://localhost:4001/order_summary?hgtid=test).
Check whether the hg_ocm_id cookie was created with the value test.

2. Creating an Order

Complete the order creation process.

3. Verification on the Order Confirmation Page

On the order confirmation page (“thank you page“), check whether the value of this cookie was passed in the request payload.

This procedure will help you ensure the proper functioning of click identifier passing and its correct processing in the system.

Conversion Tracking Settings

Displaying Costs and VAT

This setting determines whether your costs will be displayed with or without VAT. By default, we assume that you send values including VAT. However, this behavior can be adjusted on the conversion tracking settings page (where you can also access the settings by clicking the “Settings” button on the statistics page). If you change this option, costs will be displayed without VAT.

The setting should match the format in which you send us the order value (with or without VAT).

Cookies

The conversion tracking service works with the hg_ocm_id cookie, which serves an analytical purpose and ensures the storage of the exit identifier from the Heureka product detail page.

Description of JavaScript Code Methods

Name	Description	Usage Example
`heureka('authenticate', 'API_KEY');`	Sets your public key, which is used to authenticate your e-shop when processing requests. The key is automatically inserted into the code found in your admin panel. This key is different from the key for the Verified by Customers service! Do not change this key.	`heureka('authenticate', 'KJSAkjas809aKJS');`
`heureka('set_order_id', 'ORDER_ID');`	Sets the order number generated by your system. Although calling this method is not mandatory, it acts as a safeguard against duplicate order reporting and distorted statistics.	`heureka('set_order_id', '90492');`
`heureka('add_product', 'PRODUCT_ITEM_ID', 'PRODUCT_NAME', 'SINGLE_PRODUCT_PRICE_VAT', 'NUMBER_OF_PRODUCTS');`	Insert this line as many times as there are different products in the customer’s order. If the product name contains an apostrophe `'`, you must escape it with a backslash, i.e., `\'`. Adds: – Product ID (must match `ITEM_ID` in the XML feed) – Product name (must match the name you send us in the XML feed) – Unit price including VAT and mandatory fees – Quantity of items purchased in the order The product ID and product name are used for accurate conversion tracking. If filled in incorrectly, you risk that the conversion will not be recorded by the service.	`heureka('add_product', '89230', 'Bosch WNG254A0BY', '23990', '1');` `heureka('add_product', '45612', 'Xiaomi Watch S3', '2852.80', '1');`
`heureka('add_additional_item', 'ITEM_NAME', 'SINGLE_ITEM_PRICE', 'NUMBER_OF_ITEMS');`	Insert this line as many times as the number of different non-product items you want to add to the order. Adds: – Item name (optional, but recommended for easier identification) – Unit price – Quantity in the order	`heureka('add_additional_item', 'Voucher 100Kc', '-100', '1');heureka('add_additional_item', 'Poštovné', '79', '1');`
`heureka('set_total_vat', 'TOTAL_PRICE_WITH_VAT');`	Total order value (including or excluding VAT, depending on your settings).	`heureka('set_total_vat', '26842.80');`
`heureka('set_currency', 'CZK');`	Leave the currency set to the default according to the portal (‘EUR’ for heureka.sk, ‘CZK’ for heureka.cz). We recommend not sending orders in different currencies, but rather sending us orders already converted into the portal’s currency.
`heureka('send', 'Order');`	Sends the order to our system.

Implementation via GTM

We do not recommend implementation via Google Tag Manager (GTM) because it is often blocked by ad blockers, which can cause inaccuracies in conversion tracking.

We provide an example of tracking implementation via GTM based on a standard data layer (dataLayer) setup, as defined for Google Analytics 4. If your data layer implementation differs, you will need to adjust the relevant variables in the “Heureka – Purchase” tag to match your setup.

There are two ways to implement tracking via GTM:

The procedure outlined in this documentation.
Using a third-party GTM – Heureka template. Please note that we assume no responsibility for the use of this template.

We do not provide technical support for GTM implementation, as it is not our focus area. Therefore, we recommend implementing tracking directly via code.

For proper tracking according to these instructions, you must insert two “Custom HTML” tags with the corresponding JavaScript codes.

Product Detail Page Tag

1. Create a new “Custom HTML” tag

2. Navigate to tag type selection

3. Select the “Custom HTML” type

4. Copy the relevant JavaScript code into the newly created tag:

<!-- Heureka.cz PRODUCT DETAIL script -->
<script>
  (function(t, r, a, c, k, i, n, g) {t['ROIDataObject'] = k;
  t[k]=t[k]||function(){(t[k].q=t[k].q||[]).push(arguments)},t[k].c=i;n=r.createElement(a),
  g=r.getElementsByTagName(a)[0];n.async=1;n.src=c;g.parentNode.insertBefore(n,g)
  })(window, document, 'script', '//www.heureka.cz/ocm/sdk.js?version=2&page=product_detail', 'heureka', 'cz');
</script>
<!-- End Heureka.cz PRODUCT DETAIL script -->

5. In “Advanced Settings > Consent Settings“, set the tag’s behavior regarding Google Consent Mode to “No additional consent required“. The new tracking script automatically handles user consent behavior on its own.

6. Check that the tag is set up correctly and save your changes

7. Next, add the appropriate trigger to the tag to fire it at the correct moment—specifically, on the product detail page. In a standard Google Analytics 4 implementation, we use the view_item dataLayer event. If you are using a different data layer implementation, adjust the trigger accordingly (for instance, you can trigger the tag on a Page View event with a condition for page type set to “Product”, etc.).

1. Select the trigger

2. Create a new trigger (using the plus icon in the corner)

3. Select the trigger type “Custom Event”

4. Set the trigger to the “view_item” event

5. Check the trigger settings and save your changes

Thank-You Page Tag After a Successful Purchase

The conversion tracking tag needs to be fired on the thank-you page after a successful purchase, at the moment when the necessary transaction data is available in the data layer. This data is passed to the tag using dataLayer variables. In this example, we show dataLayer variables corresponding to the recommended Google Analytics 4 data layer implementation. If your data layer structure is different, adjust the variables used in the script accordingly.

If you do not already have the necessary variables set up in your Google Tag Manager container, please create them. You will need: transaction ID, transaction value, transaction currency, and the array of products in the transaction. You will also need the corresponding “API KEY” for your online store, which you can find in the administration panel.

The procedure for creating a “Data Layer Variable” is the same for all of them:

1. In the “Variables” tab, create a new variable using the “New” button

2. Select the variable type “Data Layer Variable”

3. Select the correct variable key and name the variable

4. Repeat the same procedure for all other required variables

5. Next, create a new “Custom HTML” tag as in the previous step and insert the following script into it. In the script, replace the “API KEY” value with your actual API key, and if necessary, adjust the relevant GTM variables according to your setup.

<!-- Heureka.cz THANK YOU PAGE script -->
<script>
    (function(t, r, a, c, k, i, n, g) {t['ROIDataObject'] = k;
    t[k]=t[k]||function(){(t[k].q=t[k].q||[]).push(arguments)},t[k].c=i;n=r.createElement(a),
    g=r.getElementsByTagName(a)[0];n.async=1;n.src=c;g.parentNode.insertBefore(n,g)
    })(window, document, 'script', '//www.heureka.cz/ocm/sdk.js?version=2&page=thank_you', 'heureka', 'cz');
    heureka('authenticate', 'API KEY');
    heureka('set_order_id', '{{dl.ecommerce.transaction_id}}');
    var items = {{dl.ecommerce.items}};
    if (typeof items !== "undefined"){
      for (var a = 0; a < items.length; a++){
        heureka('add_product', items[a].item_id.toString(), items[a].item_name.toString(), items[a].price.toString(), items[a].quantity.toString());
      }
    }
    heureka('set_total_vat', '{{dl.ecommerce.value}}');
    heureka('set_currency', '{{dl.ecommerce.currency}}');
    heureka('send', 'Order');
</script>
<!-- End Heureka.cz THANK YOU PAGE script -->

6. Set the appropriate trigger for the tag to fire it at the right moment—specifically, on the thank-you page when the relevant data is available in the data layer. In a standard Google Analytics 4 implementation, we use the “purchase” event. Also set the tag’s behavior regarding tracking consent to “No additional consent required“, as the tag automatically handles consent on its own.

1. Set the trigger to the “purchase” event

2. Set the consent settings in the same way as with the previous trigger

7. Check the tag settings and save your changes

8. After setting up and saving the tag, verify the implementation in “Preview mode“. If the tags fire and you see data being sent to the relevant endpoint ([https://harvester.ocm.heureka.group/](https://harvester.ocm.heureka.group/)), everything is in order and you can publish the implementation. This completes the Heureka conversion tracking implementation.

Implementation Issues

If you have implemented a new conversion tracking script and an error message appears on the statistics page stating “In the last 7 days we received XY orders with incorrect data”, it means that part of your script is not working as expected.

There are several possible warnings and errors you may receive. The severity can be either a warning or an error:

Warning: The script works as expected and orders are saved, but some values are not being sent correctly.

Error: Usually indicates a more serious implementation issue that may affect order saving.

Below is a description of the possible warning and error values.

Error Code	Severity	Description	Comments
PRICE_DONT_MATCH	Warning	Celková cena objednávky se neshoduje se součtem jednotlivých cen produktů
MISSING_ITEMS	Error	Objednávka neobsahuje žádné produkty
MISSING_ORDER	Error	Chybí údaje o objednávce	Přijatá objednávka neobsahuje žádné údaje. Pokud používáte náš skript, a ne vlastní implementaci, toto by se nemělo stát.
INVALID_ORDER_ID	Warning	Nesprávně vyplněné order_id	Nevyplňujete skutečné ID objednávky, ale odesíláte výchozí hodnotu (ORDER_ID). Musíte poskytnout jedinečné ID pro každou objednávku.
DUPLICATE_ORDER_ID	Error	Duplicitní order_id	Přijatá objednávka obsahuje stejné order_id jako některá z předchozích objednávek.
DUPLICATE_ORDER	Error	Duplicitní objednávka	Přijatá objednávka obsahuje stejné order_id a stejné položky objednávky jako některá z předchozích objednávek. Taková objednávka je označená za duplicitní a nezapočítává se do konverzí. (Nezobrazuje se mezi chybovými zprávami, pouze v response po odeslání objednávky)
MISSING_TOTAL_VAT	Error	Chybí hodnota celkové částky objednávky
INVALID_TOTAL_VAT	Error	Nesprávně vyplněná celková částka objednávky	Např. záporná hodnota nebo řetězec.
MISSING_CURRENCY	Error	Chybí měna objednávky	Neposíláte žádnou hodnotu měny.
INVALID_CURRENCY	Error	Nesprávně vyplněná měna objednávky	Posíláte hodnotu měny, ale taková měna neexistuje (např. překlep při zadání měny).
UNSUPPORTED_CURRENCY	Warning	Nepodporovaná měna objednávky	Posíláte platnou hodnotu měny, ale my nepodporujeme automatickou konverzi z této měny. To znamená, že budeme považovat částky objednávek za zadané ve výchozí měně portálu obchodu (= nesprávné údaje ve statistikách). Další podrobnosti o podporovaných měnách naleznete v části „nastavení měny“ HTML implementace.
DUPLICATE_PRODUCTS	Warning	Duplicitní produkty v objednávce	Objednávka obsahuje 2 a více produktů se stejným item_id.
MISSING_ITEM_ID	Error	Některým produktům chybí povinná hodnota item_id
MISSING_ITEM_NAME	Error	Některým produktům chybí povinná hodnota name
MISSING_ITEM_PRICE	Error	Některým produktům chybí povinná hodnota price_vat
INVALID_ITEM_PRICE	Error	Některé produkty mají nesprávně vyplněnou hodnotu price_vat	Např. řetězec.
MISSING_ITEM_QUANTITY	Error	Některým produktům chybí povinná hodnota quantity
INVALID_ITEM_QUANTITY	Error	Některé produkty mají nesprávně vyplněnou hodnotu quantity	Např. záporná hodnota nebo řetězec.