Skip to content

Latest commit

 

History

History
267 lines (197 loc) · 14.4 KB

README.en.md

File metadata and controls

267 lines (197 loc) · 14.4 KB
Raw

Zboží.cz Conversion Tracking

To gain the benefits of Zboží.cz conversion tracking, such as determining customer satisfaction with their purchase, or accessing performance statistics via API, you need to send all the neccessary information both via the frontend tracking code (JavaScript) and your backend interface.

The e-shop ID and a secret key are used for authentication and auhorization. You can obtain them in the administration panel, where you must also agree to the terms and conditions for conversion tracking and sign the data processing agreement.

You can use our testing environment – Sandbox, if you want to fine-tune and verify the functionality of your conversion tracking implementation. The Zboží.cz guidebook is also available for you to use.

Data Transmission

To ensure security and data reliability, it is necessary to send information from both the frontend and backend. Our system will then link the data by matching the orderId. All textual data must be UTF-8 encoded. Characters not supported by UTF-8 will be ignored during processing.

Frontend

Variable name Required Description
zboziId Yes (int) E-shop ID, you can obtain this information in the administration panel, or in the Sandbox.
orderId Yes (string, max. 255 characters) The order number/code generated by your e-shop. It must match in both the frontend and backend conversion code, so the data can be linked.
zboziType No (string) "standard" = standard conversion tracking (default); "limited" = limited tracking; "sandbox" = test mode for standard conversion tracking
consent Recommended (int) E-shop visitor’s consent for sending a conversion hit. Allowed values are 0 (consent not given) or 1 (consent given). Detailed information about consent can be found below.
eid Recommended (string) Customer’s e-mail. Can be sent as plain text or hash. The description can be found in the identity documentation (Hash email section). Provide it only if you have the customer’s explicit consent. See also eid vs. email.
aid Recommended (object with address) Customer’s residential or mailing address. Provide it only if you have the customer’s explicit consent. It contains fields a1 to a6, and the description can be found in the identity documentation (Address section).
tid Recommended (string) Customer’s phone number in the format +420724123456. Provide it only if you have the customer’s explicit consent. Detailed information can be found in the identity documentation (Phone number section).
id No (int) ID of the Sklik conversion code, used for conversion tracking in Sklik.
value No (int) Order value in CZK; used for conversion tracking in Sklik, it’s not considered in the standard Zboží.cz conversion tracking.

Consent for Conversion Tracking

Conversion code requires information from the advertiser on whether they have the website visitor’s consent to re-target them through cookies in the advertising network and to track them for conversion tracking (Act No. 127/2005 Coll., on Electronic Communications).

You should send the order information even if you don’t have this consent – failing to do so would unnecessarily cause errors in linking conversion data and prevent you from collecting customer reviews for these orders (this works independently of cookies).

To pass the consent information for targeted advertising and conversion tracking, use the consent parameter. If the consent was given (value 1), or the parameter was not included, Seznam.cz processes the data in the standard way, including reading cookies. If the consent was not given (value 0), the system processes the data for improving conversion tracking through modeling. This is done in compliance with the law (we neither store nor read the information from the user’s device).

Conversion JavaScript Code

The frontend code should be placed on the page that is displayed right after the order is submitted/confirmed, and its optimal placement is in the page’s header (before </head>). Do not insert the code asynchronously using the async attribute.

<script type="text/javascript" src="https://c.seznam.cz/js/rc.js"></script>
<script>
    /* identity object settings */
    if (window.sznIVA && window.sznIVA.IS) {
        window.sznIVA.IS.updateIdentities({
            eid: "CUSTOMER_EMAIL", // email or hashed email
            aid: {
                "a1": "STATE", // state
                "a2": "CITY", // city
                "a3": "STREET", // street
                "a4": "HOUSE_NUMBER", // house number
                "a5": "POSTAL_CODE", // postal code
            },
            tid: "PHONE", // phone number
        });
    }
    var conversionConf = {
        zboziId: ESHOP_ID, // Zboží e-shop ID
        orderId: "ORDER_NUMBER",  // Order number
        zboziType: "standard", // Type of Zboží.cz conversion tracking; for testing mode, use "sandbox".
        consent: CONSENT, // Visitor’s consent for sending the conversion hit
        id: SKLIK_ID, // ID of the Sklik conversion code (used for conversion tracking in Sklik)
        value: ORDER_VALUE, // Order value in CZK (used for conversion tracking in Sklik)
    };
    if (window.rc && window.rc.conversionHit) {
        window.rc.conversionHit(conversionConf);
    }
</script>

Content Security Policy Settings

If you are using Content Security Policy restrictions on your website, it is necessary to allow at least the following:

  • script-src 'unsafe-inline' https://*.seznam.cz https://*.zbozi.cz;
  • img-src https://*.seznam.cz;
  • frame-src https://*.zbozi.cz;

script-src 'unsafe-inline' is necessary for calling the script directly from the <script> tag. If you use another method for embedding scripts (e.g., GTM), it will affect the required Content Security Policy settings as well.

Backend

Authentication and Authorization

Variable Name Required Description
SHOP_ID Yes (int) E-shop ID, obtainable in the administration panel or the Sandbox.
PRIVATE_KEY Yes (string, max. 255 characters) Secret key for authorizing backend requests. Obtainable in the e-shop’s administration panel or the Sandbox. If this key is compromised, generate a new one.

Order Properties

Variable Name Required Description
orderId Yes (string, max. 255 characters) Order number/code from your e-shop. It must match in both the frontend and backend conversion code for data linkage.
email Recommended (email, max. 100 characters) Customer’s e-mail, used for purchase verification and product review requests. Do not send if the customer has not given consent.
cart Yes (array) Shopping cart contents.
deliveryType Recommended (string, max. 100 characters) Delivery method, preferably the DELIVERY_ID from your feed.
deliveryPrice Recommended (number) Delivery price in CZK, including VAT. (Signed 32-bit integer, 0 – (231-1)/100.)
otherCosts Recommended (number) Additional costs or discounts for the order, e.g., card payment fees, bulk discounts. List discounts as negative numbers. (Signed 32-bit integer, -231/100 – (231-1)/100.)
paymentType No (string, max. 100 characters) Payment type (e.g., card, cash, etc.).

Properties of Cart Items (Contents of the "cart" Variable)

Variable Name Required Description
itemId Yes (string, max. 255 characters) ID of the e-shop item (ITEM_ID from your feed).
productName Yes (string, max. 255 characters) Item name, ideally PRODUCTNAME from your feed.
unitPrice Recommended (number) Unit price of the item in CZK, including VAT. (0 – (231-1.)
quantity Recommended (number) Number of items purchased. (1 – (231-1).

eid vs. email

The customer’s e-mail address can be sent in two different fields: eid in the identity object (on the frontend) and email (on the backend as part of the order information). Although both fields typically contain the same data, their purpose and meaning are different:

  • eids part of the identity object used for conversion tracking, ad targeting, and retargeting. Its processing depends on the customer’s consent for this specific purpose (consent). The e-mail address can also be sent in hashed form. If it is not already hashed, it will be hashed before any further processing.
  • email on the backend is used for verifying customer satisfaction with the purchase and requesting a review of the purchased product. The general practice is to provide the customer with the option to opt-out, which is sufficient for this purpose. This is typically handled by a checkbox that allows the customer to choose, 'I do not agree with the provision of my data for the purpose of independent purchase review' during the purchase process. In this case, the e-mail address must not be hashed, as Zboží will send the review request to it.

Summary:

  • Send eid only if you have the customer's consent for ad targeting and tracking.
  • Send email if the customer has not opted out of data sharing for purchase review.

PHP

If your shop is built in PHP, you can use the ZboziKonverze.php class that we have prepared to simplify the process. If something doesn’t work as expected (e.g., network issues, or when the e-shop disables conversion tracking in the Zboží administration panel), the class throws exceptions. We recommend processing, or at least catching these exceptions, to ensure they do not interfere with order processing.

Example of Use:

<?php

include_once("ZboziKonverze.php");

try {

    // initialization
    $zbozi = new ZboziKonverze(ESHOP ID, "PRIVATE KEY");

    // test mode
    //$zbozi->useSandbox(true);

    // setting order information
    $zbozi->setOrder(array(
        "orderId" => "ORDER NUMBER",
        "email" => "email@example.com",
        "deliveryType" => "CZECH_POST",
        "deliveryPrice" => 80,
        "otherCosts" => 20,
        "paymentType" => "cash on delivery",
    ));

    // adding purchased item
    $zbozi->addCartItem(array(
        "itemId" => "1357902468",
        "productName" => "Samsung Galaxy S3 (i9300)",
        "quantity" => 1,
        "unitPrice" => 5000.50,
    ));

    // adding another purchased item
    $zbozi->addCartItem(array(
        "itemId" => "2468013579",
        "productName" => "BARUM QUARTARIS 165/70 R14 81 T",
        "quantity" => 4,
        "unitPrice" => 600,
    ));

    // sending
    $zbozi->send();

} catch (ZboziKonverzeException $e) {
    // logging potential errors
    error_log("Conversion error: " . $e->getMessage());
}
?>

Alternative Third-Party Modules

  • soukicz/zbozicz – PHP with namespaces and support for asynchronous order submission.

Custom Implementation

If you cannot or do not wish to use any of the prepared modules, you will need to create your own custom implementation.

Order data can be sent in two ways. The first and recommended method is using an HTTP POST request containing a JSON payload with the order data. The second option is sending an HTTP GET request, where the order data is serialized into URL parameters.

The request must be sent to this address: https://www.zbozi.cz/action/SHOP_ID/conversion/backend, where SHOP_ID is unique for every e-shop. For testing, use this address: https://sandbox.zbozi.cz/action/TEST_ID/conversion/backend, where a TEST_ID will be randomly generated.

Test Mode Disclaimer:

Data sent to the test interface can be seen by anyone who knows the TEST_ID. Therefore, do not use the test interface to send real data!

HTTP POST

Request Example:

POST /action/ID%20PROVOZOVNY/conversion/backend HTTP/1.1
Host: www.zbozi.cz
Content-Length: 688
Content-Type: application/json


{
    "PRIVATE_KEY": "PRIVATE KEY",
    "sandbox": false,
    "orderId": "ORDER NUMBER",
    "email": "email@example.com",
    "deliveryType": "CZECH_POST",
    "deliveryPrice": 80,
    "paymentType": "cash on delivery",
    "otherCosts": 20,
    "cart": [
        {
            "itemId": "1357902468",
            "productName": "Samsung Galaxy S3 (i9300)",
            "unitPrice": 5000.50,
            "quantity": 1
        },
        {
            "itemId": "2468013579",
            "productName": "BARUM QUARTARIS 165/70 R14 81 T",
            "unitPrice": 600,
            "quantity": 4
        }
    ]
}

HTTP GET

Order data can be sent as parameters in a GET request. The parameter names are the same as in the case of JSON. The only difference is in the cart parameter, which is a serialized string of its attributes and values separated by semicolons (e.g., productName:productName;itemId:productId;unitPrice:100;quantity:3).

For example, the following cart JSON:

"cart": [
    {
        "itemId": "1357902468",
        "productName": "Samsung Galaxy S3 (i9300)",
        "unitPrice": 5000.50,
        "quantity": 1
    },
    {
        "itemId": "2468013579",
        "productName": "BARUM QUARTARIS 165/70 R14 81 T",
        "unitPrice": 600,
        "quantity": 4
    }
]

has to be written as: cart=itemId:1357902468;quantity:1;unitPrice:5000.5;productName:Samsung+Galaxy+S3+%28i9300%29&cart=itemId:2468013579;quantity:4;unitPrice:600;productName:BARUM+QUARTARIS+165%2F70+R14+81+T

Request example: https://www.zbozi.cz/action/SHOP_ID/conversion/backend?orderId=ORDER_NUMBER&PRIVATE_KEY=PRIVATE_KEY&deliveryType=CESKA_POSTA&paymentType=dob%C3%ADrka&email=email%40example.com&cart=itemId:1357902468;quantity:1;unitPrice:5000.5;productName:Samsung+Galaxy+S3+%28i9300%29&cart=itemId:2468013579;quantity:4;unitPrice:600;productName:BARUM+QUARTARIS+165%2F70+R14+81+T