Skip to main content
Version: Current platform

Troubleshoot the First Install

Start in browser developer tools. The console identifies initialization problems; the Network panel separates script loading, authentication, validation, and ingestion failures.

No window.upsurge​

Check the request for https://cdn.upsur.ge/sdk/upsurge.min.js.

  • A 404 usually means the CDN hostname or SDK path was changed in the snippet. For a pinned /sdk/<version>/upsurge.min.js, check that the version number exists.
  • A content-security-policy error means the storefront must allow https://cdn.upsur.ge in script-src, style-src and font-src, and https://api.upsur.ge in connect-src. See Content Security Policy.
  • Define window.UpsurgeQueue before the asynchronous script tag.
  • Queue calls as arrays, for example ['init', {...}].

The SDK calls the storefront origin​

Set baseUrl to https://api.upsur.ge. It is the platform API origin, not the CDN hostname or the merchant storefront. The SDK defaults to window.location.origin when baseUrl is omitted.

Feature bundles or fonts load from api.upsur.ge​

The Network panel shows upsurge-overlays.min.js, overlay-fonts.css or another SDK file coming from https://api.upsur.ge/sdk/, although the snippet loads the core from cdn.upsur.ge. A script loader such as Cloudflare Rocket Loader or Partytown hid the core's URL, so the SDK fell back to baseUrl. The files still work, but a Content Security Policy written for the CDN blocks them.

Use one of these fixes:

  • Exclude every Upsurge script tag from the loader: the inline snippet, the core and, if you use it, Smart Search. For Rocket Loader, add data-cfasync="false" to each tag.
  • Pin the core and set assetBaseUrl to the same version folder. See Pin a version.
  • Allow https://api.upsur.ge in script-src, style-src and font-src too.

401 Unauthorized​

  • Confirm siteId is the public ID shown on the Sites page.
  • Confirm the storefront's exact host or valid subdomain is registered for that site.
  • Inspect /api/v1/sdk/bootstrap; a denied bootstrap does not issue a runtime token.

Browser reports a CORS failure​

  • Test from the exact origin registered for the site, including the staging subdomain.
  • Confirm the request is sent to the expected Upsurge deployment.
  • If the registered origin is correct, ask the workspace or platform administrator to confirm that the deployment permits it.

400 or a partially successful 207​

Open the JSON response and inspect validation details or the per-event results array.

Common causes include:

  • missing product_id on product and cart events;
  • missing transaction_id, total_amount, currency, or products on purchases;
  • an unsupported event name;
  • custom events without event_name;
  • more than 100 events in one batch.

The request succeeds but Analytics is empty​

  1. Call await window.upsurge.flush() or wait for the default 10-second flush interval.
  2. Select a date range that includes the event time.
  3. Check the site and data-source filters.
  4. Refresh after a short processing delay.
  5. Inspect results for deduplicated: true; retried events can be accepted without increasing counts.

Tracking is intentionally disabled​

If respectDoNotTrack is true, a browser DNT preference disables tracking. Fingerprinting is separate and remains disabled unless enableFingerprinting is explicitly enabled.

Enable diagnostic logging​

Temporarily initialize with debug: true:

window.UpsurgeQueue.push([
  'init',
  {
    siteId: 'site_replace_me',
    baseUrl: 'https://api.upsur.ge',
    debug: true,
  },
]);

Remove debug logging after validation. If the install still fails, preserve the script URL, request URL, HTTP status, response body, and console error when escalating.