Installation

Requirements

• CS-Cart and Multi-Vendor 4.17.2 – 4.21.x (tested on CS-Cart 4.17.2, Multi-Vendor 4.17.2 and Multi-Vendor 4.21.2 with PHP 8.3).
• PHP 7.4 – 8.3, as supported by your CS-Cart version.
• A storefront theme based on Responsive (Responsive, Bright theme, or a child theme such as Nova, the 4.21 default).
• A Google Analytics 4 property with a web data stream (for the measurement ID G-XXXXXXXXXX), or a Google Tag Manager web container (GTM-XXXXXXX).
• Optional, for the server-side fallback and refunds: a Measurement Protocol API secret for the same data stream, and outgoing HTTPS from your server to www.google-analytics.com (or region1.google-analytics.com).

Install from the package

1. Open Add-ons → Manage add-ons in the admin panel.
2. Click the gear icon → Manual installation and upload kv_ga4_ecommerce-1.0.0.zip.
3. Find Ecommerce Tracking Pro in the list. The add-on is installed and set to Active.
4. Open the add-on settings and enter your measurement ID or GTM container ID (see Configuration).
5. On the License tab of the settings, enter your license key and save. If you bought the add-on on the CS-Cart Marketplace and entered the license number in Add-ons → Manage add-ons, you can skip this step. Until a key is verified, the add-on works for 14 days (see License).

The package mirrors the store root:

app/addons/kv_ga4_ecommerce/
design/backend/templates/addons/kv_ga4_ecommerce/
var/themes_repository/responsive/templates/addons/kv_ga4_ecommerce/
var/langs/en/addons/kv_ga4_ecommerce.po
js/addons/kv_ga4_ecommerce/func.js

On install, CS-Cart copies the storefront templates into design/themes/<theme>/ for every installed theme. The add-on creates one table, cscart_kv_ga4_ecommerce_orders. If the GDPR add-on is active, two services are also added to its cookie consent configuration: Google Analytics 4 (performance) and Google advertising (marketing).

Before you go live

1. Disable the core “Google Analytics” add-on if it is active. Otherwise page views and purchases are counted twice. The add-on’s Status block warns you while the core add-on is active.

2. Remove any GA4 or GTM snippet that your theme or another add-on prints. Alternatively, keep that snippet and turn off Load the tag on the storefront: the events then go to the existing tag.

3. In GA4, open Admin → Data streams → your stream → Measurement Protocol API secrets, create a secret and paste it into Server-side events → Measurement Protocol API secret.

4. Optional: add a cron job for the purchase fallback (the command is shown in Server-side events → Status):

   */10 * * * * php /path/to/store/admin.php --dispatch=kv_ga4_ecommerce.process

   Without cron, the fallback runs automatically while the store has traffic, at most every 5 minutes.

Custom themes not based on Responsive

If your theme has its own var/themes_repository/<theme>/ folder and does not inherit from Responsive, copy this folder into the theme after installation:

design/themes/responsive/templates/addons/kv_ga4_ecommerce/  →  design/themes/<theme>/templates/addons/kv_ga4_ecommerce/

The add-on only uses the index:head_scripts, index:body and index:scripts template hooks. Every theme that keeps the standard index.tpl hooks works.

Upgrade

1. In Add-ons → Manage add-ons, upload the new package with Manual installation.
2. CS-Cart sees that the add-on is already installed and offers two ways:
   • Use the dangerous way (tick I know the risks… first) replaces the add-on files and keeps all add-on data. Choose this one. Despite its name, it is the normal way to upgrade this add-on.
   • Use the safe way uninstalls the add-on first. That deletes the settings and the order tracking records, then installs the new version from scratch.
3. Open any page of the admin panel. On that first page view the add-on completes the upgrade by itself. It adds any new database tables and columns, new settings (with their default values), new language variables and e-mail templates. It also updates the version shown in Add-ons → Manage add-ons. Existing data and setting values are kept.

When files are uploaded over an installed add-on, CS-Cart resets the add-on’s language variables to the texts in the package. If you edited them in Administration → Languages → Translations, apply your edits again.

If you bought the add-on on the CS-Cart Marketplace, you can also upgrade it in Administration → Upgrade center. Steps 2 and 3 then happen automatically. The Upgrade center closes the storefront while it works. Reopen the storefront afterwards; the e-mail the Upgrade center sends links to the right page.

Upgrading to 1.1.0: this version adds the license check. After the upgrade the add-on keeps working for 14 days; enter your license key on the License tab of the settings within that time.

See the CHANGELOG for what changed in each version.

Uninstall

Add-ons → Manage add-ons → Ecommerce Tracking Pro → gear icon → Uninstall removes:

• the settings and language variables;
• the cscart_kv_ga4_ecommerce_orders table;
• the fallback timer;
• the two cookie-consent services in the GDPR add-on configuration.

No core files are changed at any time.