Skip to main content
Version: 2026.07

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.
  • A content-security-policy error means the storefront must allow https://cdn.upsur.ge for scripts and https://dashboard.upsur.ge for API connections.
  • 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://dashboard.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.

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.
  • If an old install reports publishable_key_retired, migrate from apiKey to siteId.

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://dashboard.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.